home *** CD-ROM | disk | FTP | other *** search
/ Fujiology Archive / fujiology_archive_v1_0.iso / !MAGS / !BONUS / COVERDSK / STFORMAT / STF35.ZIP / STF35B.MSA / GFABASIC / GFABASIC.TXT < prev    next >
Text File  |  1992-04-07  |  219KB  |  6,739 lines
  1. August 1991
  2.  
  3. No part of this publication may be copied ,  transmitted or stored 
  4. in  a retrieval system or reproduced in any way including but  not 
  5. limited  to photography,  photocopy,  magnetic or other  recording 
  6. means,  without prior written permission from the publishers, with 
  7. the  exception of material entered and executed for  the  reader's 
  8. own use.
  9.  
  10. This version created fot ST FORMAT.
  11.  
  12. THIS IS NOT PUBLIC DOMAIN. FULL COPYRIGHT REMAINS IN FORCE.
  13.  
  14.  
  15. MARCH 1992
  16.  
  17. Copyright 1991 GFA Data Media (UK) Ltd
  18.  
  19. Published by:  GFA Data Media (UK) Ltd
  20.                Box 121
  21.                Wokingham
  22.                Berkshire
  23.                RG11 5XT
  24.  
  25. Special Offer to ST Format Readers
  26.  
  27. This  document  is  over  129 pages if  printed  on  A4.  We  have 
  28. documented  all  GFA-BASIC  commands.  All  commands  are also
  29. contained in the full GFA-BASIC REFERENCE manual which contains  
  30. much more information than is contained in this  'brief' document.
  31. Most commands are fully explained with an example program.
  32.  
  33.  
  34. You  can obtain the FULL documentation,  normally sold  for  50.00 
  35. pounds for only 25.00 pounds (plus 5.00 postage).  All orders must 
  36. be returned direct to GFA,  using the special coupon in the  issue 
  37. of ST Format that this disk was supplied with.
  38.  
  39. Also you can obtain the GFA-BASIC Compiler 3.5 and manual for only 
  40. 20.00  (plus  postage of 5.00).  (normally  30.00).  The  compiler 
  41. manual  contains 48 pages.  You will need the compiler to  produce 
  42. desk top accessories and link C and assembler code into your  GFA-
  43. BASIC programs.
  44.  
  45. Or  order both the Interpreter and Compiler for only  45.00  (plus 
  46. 5.00 postage) which would normally retail for 80.00.  
  47.  
  48.  
  49. Please  make  Cheques  and  Postal  Orders  payable  to   GFA-DATA 
  50. MEDIA (UK) LTD. We also can accept VISA and ACCESS credit cards.
  51.  
  52.  
  53.  
  54.  
  55. TECHNICAL SUPPORT
  56.  
  57. Technical  Support is only available to users who  have  purchased 
  58. the full GFA-BASIC 3.5 Interpreter.  All technical problems should 
  59. be sent to GFA in writing, enclosing a stamped addressed envelope, 
  60. and  quoting  their registration card number (supplied  with  each 
  61. purchased  product).  Sorry but we are unable to supply  technical 
  62. support  to  users  who are unable  to  quote  their  registration 
  63. number.
  64.  
  65. Now to the documentation:
  66.  
  67. Introduction
  68.  
  69. Welcome to GFA-BASIC.  With the GFA-BASIC interpreter you now have 
  70. the opportunity to explore the Atari ST,  and create  professional 
  71. programs.
  72.  
  73. We  believe that GFA is the best programming  language  available, 
  74. not  just for the Atari ST,  but also for the  Amiga,  MS-DOS  and 
  75. Windows 3.0/3.1.  When you have quickly mastered GFA-BASIC for the 
  76. Atari ST,  you can transport your program to any PC running either 
  77. MS-DOS or Windows (and soon OS/2 and Unix!).  This means that  you 
  78. will  only  need  to learn one language for  all  these  different 
  79. machines and operating systems. 
  80.  
  81. This  manual contains all the GFA-BASIC 3.5  command  descriptions 
  82. and syntax. This manual is an edited version of the full reference 
  83. manual (which is over 540 pages) and is a reference manual for the 
  84. GFA-BASIC  commands  only.  The  full  reference  manual  contains 
  85. example  programs for most of the commands and reference  material 
  86. for the Atari BIOS, XBIOS and GEMDOS.
  87.  
  88. This manual is a reference manual for the GFA-BASIC  commands.  It 
  89. does  not attempt to teach you to program,  there are other  books 
  90. available for this purpose.  Neither does this edited manual  does 
  91. not  document  the hardware or operating system  features  of  the 
  92. Atari.
  93.  
  94. This is the GFA-BASIC Interpreter. There are many more products in 
  95. the  GFA range to help you develop your programs.  Please  contact 
  96. your  distributor or GFA for more information and prices of  these 
  97. products.
  98.  
  99. GFA-BASIC Interpreter Reference Manual (Full version)
  100.  
  101. This  loose  leaf manual has over 540  pages,  dealing  with  each 
  102. command  with  a full description an  example.  The  Atari  system 
  103. routines,  GEMDOS, AES, VDI and GDOS are all described. The Line-A 
  104. call  is  also described (although Line-A is now  declared  as  un 
  105. supported by Atari). Just about every useful table is presented in 
  106. this  manual,  including  GFA-BASIC  error  messages,  Bomb  Error 
  107. messages,  TOS Error messages, Scan code table, ASCII tables, Fill 
  108. and style patterns, and VT-52 control codes.
  109.  
  110. GFA-BASIC Compiler 
  111.  
  112. The  GFA-BASIC  Compiler will compile your interpreter  code  into 
  113. fast stand alone programs. Desk top accessories can also be easily 
  114. created.  The  GFA-BASIC Compiler also has options for  optimising 
  115. code  for  either  speed or  size.  External  code,  either  C  or 
  116. assembler  can  also be linked into your programs using  the  GFA-
  117. BASIC Compiler. The manual (48 pages) fully explains how to create 
  118. a desk top accessory with examples. The compiler also supports the 
  119. Atari TT, allowing code to be compiled for either ST or TT ram.
  120.  
  121. GFA-BASIC Software Development Book
  122.  
  123. This  book  covers  in  depth  structured  programming,  debugging 
  124. routines, Line A calls, Assembly routines, AES functions and GDOS. 
  125. Special attention is paid to dialog boxes and their creation. This 
  126. book  is over 341 pages and is supported by a disk containing  the 
  127. many examples of source code discussed within the book.
  128.  
  129. GFA GEM Utility Pack
  130.  
  131. THE  GEM GUP is a framework of GFA-BASIC 3 routines that  you  can 
  132. merge  into  your own programs.  GUP takes the  responsibility  of 
  133. managing  the intricate GEM interface,  leaving the programmer  to 
  134. concentrate  on  the  main  program  logic.  The  example  program 
  135. supplied demonstrates how easy it is to create alternative  icons, 
  136. and  use up to 5 different window types.  The  demonstration  also 
  137. shows how to use all the GEM gadgets, including scroll bars, title 
  138. bar, info bar, grow box, grab bar etc. GFA GUP is a quick start to 
  139. programming GEM.  GUP is supplied with a 60 page manual and  disk, 
  140. fully documenting all of the GEM routines. 
  141.  
  142. GFA Assembler
  143.  
  144. An integrated development tool for the Atari  ST/STE,  comprising 
  145. editor,  macro assembler,  linker and debugger. Supports multiple 
  146. window,  file compare,  background assembly. Editor checks syntax 
  147. of  machine  code on entry,  hence ideal for programmers  new  to 
  148. assembly language. Also creates files that can be loaded directly 
  149. into GFA-BASIC.
  150.  
  151. GFA-Basic and Assembler User Book
  152.  
  153. This  book covers all that you will need to know  in  interfacing 
  154. assembler routines into GFA-BASIC on the Atari  ST/STE.  Includes 
  155. an introduction into assembly programming,  creation of desk  top 
  156. accessories, graphic manipulation. Book (364 pages) plus disk.
  157.  
  158. GFA G-Shell
  159.  
  160. Professional  development  shell for  GFA-BASIC  Interpreter  and 
  161. Compiler  on the Atari ST/STE and TT.  
  162. GFA-GShell allows the programmer to  skip between Interpreter  and 
  163. Compiler  and other programs,  such as an assembler  and  resource 
  164. editor.   Supports make facility and  on line help files.  If  you 
  165. are using GFA-BASIC Interpreter and Compiler professionally,  then 
  166. GFA-GShell will improve your productivity.
  167.  
  168. GFA-DRAFT 3.2      
  169.  
  170. Powerful  and  comprehensive,  yet easy to use CAD  software  for 
  171. Atari ST/STE and Atari TT.  Runs in both high and medium  resolu-
  172. tions.  Icon and menu driven commands. There are symbol libraries 
  173. for  electrical,  electronic users and architects.  Libraries  of 
  174. symbols are also easy to create. 
  175.  
  176. A  program/macro interface (using GFA BASIC) will enable  you  to 
  177. create complex forms and repetive patterns.  Exports:  HPGL,  DXF 
  178. and  GEM  files.  Will  support almost any model  of  printer  or 
  179. plotter.  GFA-Draft  Plus  3.2  also  supports  the  Atari  laser 
  180. printer.
  181.  
  182.  
  183. These GFA products and others are available from:
  184.  
  185. GFA Data Media (UK) Ltd
  186. Box 121
  187. Wokingham
  188. Berkshire
  189. UK RG11 5XT
  190.  
  191. Sales Line Only     Tel: 44 (0)734 794941
  192.                     Fax: 44 (0)734 890782
  193.  
  194.  
  195.  
  196.  
  197. Using GFA-BASIC for the first time
  198.  
  199. The GFA-BASIC program disk is not copy protected, so before you do 
  200. anything else,  make a copy and store the original disk in a  safe 
  201. place. 
  202.  
  203. GFA-BASIC  is started by double clicking on the program file  icon 
  204. GFABASIC.PRG.  After  a  short  while the Editor  screen  will  be 
  205. displayed,  which is where you can write and debug your  programs. 
  206. Lets  now  try entering an example program.  Enter  the  following 
  207. program lines, pressing the RETURN key at the end of each line.
  208.  
  209. DEFFILL 1,2,8
  210. REPEAT
  211.   WHILE MOUSEK=1
  212.     PBOX MOUSEX,MOUSEY,MOUSEX+30,MOUSEY+30
  213.   WEND
  214. UNTIL MOUSEK=2
  215.  
  216. In the upper right hand corner of the editor screen you will find 
  217. the RUN menu item. Click the RUN button or press Shift and F10 
  218. keys together and the example program will start. A simple program 
  219. showing the use of the mouse. Move the mouse while holding down 
  220. the left button. End the program by pressing the right mouse 
  221. button. Press the Return key to end the program. The program could 
  222. also have been stopped by pressing the CONTROL, SHIFT and 
  223. ALTERNATE keys all at the same time. You will now be returned to 
  224. the editor.
  225.  
  226. GFA-BASIC does not need line numbers. It is bad programming 
  227. practice to say GOTO 10. If you must use GOTO, then use:
  228.  
  229. GOTO label
  230. ...
  231. label:
  232.  
  233. GFA-BASIC offers you the chance to create structured programs, and 
  234. indented   in  such  a  way  to  enable  easy  documentation   and 
  235. understanding of program flow.
  236.  
  237. How  to proceed from here.  We suggest you first  become  familiar 
  238. with  the GFA-BASIC Interpreter's editor.  Then load some  of  the 
  239. demonstration  programs from the disk and  run  these.  Experiment 
  240. with these programs by changing the values of variables to see the 
  241. effect.  The  next step really depends upon the  individual,  your 
  242. knowledge  of the Atari,  your knowledge of programming  and  your 
  243. program requirements.  What ever your experience or  requirements, 
  244. GFA-BASIC  is the best documented programming  language  available 
  245. for the Atari ST, and there are several books and development aids 
  246. to help you.
  247.  
  248.  
  249.  
  250. The Editor
  251.  
  252. THE GFA-BASIC Editor has been specially designed for program 
  253. development. Syntax errors are recognised as you type the commands 
  254. in, and in addition the commands are indented automatically.
  255.  
  256. Only one instruction per line is allowed, but a comment may be 
  257. added to the end of a line by beginning the comment with a ! mark.
  258.  
  259. Program lines may be up to 255 characters long, but when a line 
  260. exceeds 80 characters, the line will scroll.
  261.  
  262.  
  263. Cursor Keypad
  264.  
  265. Left arrow          moves cursor left one character
  266. Right arrow         moves cursor right one character
  267. Up arrow            moves cursor up one line
  268. Down arrow          moves cursor down one line
  269.  
  270. Insert              Inserts a blank line
  271. ClrHome             moves cursor to top left corner
  272. Ctrl ClrHome        moves cursor to start of program listing
  273.  
  274. Help                With the help key procedures and functions can 
  275.                     be folded and unfolded. Move the cursor to the 
  276.                     start of a procedure or function and then 
  277.                     press Help. The procedure will the fold down 
  278.                     to a single line
  279.  
  280. Numeric Keypad
  281.  
  282. Ctrl 4              moves cursor left one character
  283. Ctrl 6              moves cursor right one character
  284. Ctrl 8              moves cursor up one line
  285. Ctrl 2              moves cursor down one line
  286. Ctrl 7              jumps to start of program
  287. Ctrl 1              jump to end of program
  288. Ctrl 9              move one page up
  289. Ctrl 3              move one page down
  290. Ctrl 0              Inserts a line
  291. Ctrl .              deletes a line
  292.  
  293. The numeric keypad can be swithed to a mode where it is not 
  294. required to press the Ctrl key. This mode is toggled on and off by 
  295. pressing Ctrl and - on the numeric keypad. 
  296.  
  297. Delete              deletes character at cursor position
  298. Backspace           deletes character to left of cursor
  299. Tab                 moves cursor right eight characters
  300. Ctrl Tab            moves cursor left eight characters
  301. Return              moves cursor to start of next line
  302. Enter               moves cursor to start of next line
  303. Escape              enter Direct Mode
  304.  
  305. Further editor commands
  306.  
  307. Ctrl Delete         deletes line which cursor is on
  308. Ctrl U              un-deletes line
  309. Ctrl Y              deletes line which cursor is on
  310. Ctrl N              inserts blank line
  311. Ctrl Q              call Block menu (as F4)
  312. Ctrl B              mark start of block
  313. Ctrl K              mark end of block
  314. Ctrl R              Page up
  315. Ctrl C              Page down
  316. Ctrl E              replace text
  317. Shift Ctrl E        find replace text
  318. Ctrl F              find text
  319. Ctrl left arrow     cursor to start of line
  320. Ctrl right arrow    cursor to end of line
  321. Ctrl up arrow       page up
  322. Ctrl down arrow     page down
  323. Ctrl Clr Home       cursor to start of program
  324. Ctrl P              delete character right of cursor
  325. Ctrl O              undelete text deleted with Ctrl P
  326. Ctrl Z              cursor to end of program
  327. Ctrl Tab            cursor left eight characters
  328. Ctrl G              move to line number display
  329.  
  330. Editor marks
  331.  
  332. Ctrl n              where n= 0 to 6 will mark a position
  333. Alt n               will jump to marked position n, except:
  334.  
  335. Alt 7               cursor to last cursor position before RUN
  336. Alt 8               to start of program
  337. Alt 9               cursor to start of last search
  338. Alt 0               cursor to position of last change
  339.  
  340. Menu Bar
  341.  
  342. Atari Logo
  343.  
  344. This leads to a GEM menu bar:
  345.  
  346. Save
  347.  
  348. A file select box will appear, and a program can be saved by 
  349. entering a name and selecting OK.
  350.  
  351. Load 
  352.  
  353. A file select box will appear, and a program can be selected and 
  354. loaded into the editor.
  355.  
  356. Deflist
  357.  
  358. See the DEFLIST command.
  359.  
  360. New Names
  361.  
  362. The editor will warn you if you enter a new variable name.
  363.  
  364. Editor
  365.  
  366. Returns you to the editor.
  367.  
  368.  
  369.  
  370. Load (F1)
  371.  
  372. Load a GFA-BASIC 3 .GFA tokenised file.
  373.  
  374. Save (Shift F1)
  375.  
  376. Save the program as a tokenised .GFA file.
  377.  
  378. Merge (F2)
  379.  
  380. Load an ASCII text file into the editor at the cursor position. 
  381. The existing program in the editor is not erased.
  382.  
  383. Save,A (Shift F2)
  384.  
  385. Save the program in memory in ASCII format. The extension .LST 
  386. will be added to the file name. If the file already exists the old 
  387. file will be changed to .BAK.
  388.  
  389. Llist (F3)
  390.  
  391. This command controls the output of the print out. These Dot 
  392. commands have no effect on the running of the program and only 
  393. affect the printout:
  394.  
  395. .ll xx         Max line length
  396. .pl xx         Max page length
  397. .ff xxx        Form feed character for printer
  398. .he text       Text to appear on first line of each page
  399. .fo text       Text to appear on last line of each page
  400. .lr xx         Left margin
  401. .l-            Switch dot commands off
  402. .l+            Switch dot commands on (default)
  403. .n1 to .n9     Switch on line numbers up to 9 characters
  404. .n0            Switch off line numbers
  405. .PA            Force form feed
  406. .P-            Do not list dot commands
  407. .P+            List dot commands
  408.  
  409. In the header and footer text, the following can also be inserted:
  410.  
  411. \xxx           The ASCII character xxx
  412. \d             Date
  413. \t             Time
  414. #              Page number
  415.  
  416. To print the symbols \ and ##, use \\ and \ respectively.
  417.  
  418. Quit (Shift F3)
  419.  
  420. Results in Do you really want to quit message. If Yes selected, 
  421. thenyou will return to the desktop.
  422.  
  423. Block (F4)
  424.  
  425. If no block marked then message Block ??? will appear. If a block 
  426. has been selected using the BlkSta and BlkEnd then the block menu 
  427. will appear:
  428.  
  429. Copy
  430.  
  431. Copies the block to current cursor position. 
  432.  
  433. Move
  434.  
  435. Moves the block to current cursor position.
  436.  
  437. Write
  438.  
  439. Saves the block as an ASCII file (.LST)
  440.  
  441. Llist
  442.  
  443. Prints the block out to printer
  444.  
  445. Start
  446.  
  447. Moves the cursor to start of block
  448.  
  449. End
  450.  
  451. Moves the cursor to end of block
  452.  
  453. Del
  454.  
  455. Deletes the block
  456.  
  457. Hide
  458.  
  459. Removes the block marker
  460.  
  461. Clicking the mouse outside the Block menu or pressing a key also 
  462. removes the block marker.
  463.  
  464. New (Shift F4)
  465.  
  466. The program currently in the editor is erased from memory.
  467.  
  468.  
  469. Blk End (F5)
  470.  
  471. The line before the cursor is marked as the end of block. If the 
  472. start of block marker is located before this line, the block is 
  473. shown in a different colour (or dotted background on a monochrome 
  474. screen). Also actioned with Ctrl K.
  475.  
  476. Blk Sta (Shift F5)
  477.  
  478. Marks the beginning of a block as above. Also actioned with Ctrl 
  479. B.
  480.  
  481. Find (F6)
  482.  
  483. Enter a text string to be searched for. If the string is found, 
  484. the search cab be continued with Ctrl F or Ctrl L. Also actioned 
  485. with Shift Ctrl F or Shift Ctrl L.
  486. Folded procedures and functions are not searched.
  487.  
  488. Replace (Shift F6)
  489.  
  490. This function will replace one string of text by another. Input 
  491. the text to be replaced, then the replacement text. On finding an 
  492. occurrence, the actual replacement can be effected with Ctrl E. 
  493. Also activated with Shift Ctrl E.
  494.  
  495. Pg down (F7)
  496.  
  497. Scrolls the screen down one page. Also activated with Ctrl C.
  498.  
  499. Pg Up (Shift F7)
  500.  
  501. Scrolls the screen up one page. Also activated with Ctrl R.
  502.  
  503. Insert/Overwr (F8)
  504.  
  505. Switches between insert and overwrite.
  506.  
  507. Txt16/Text8 (Shift F8)
  508.  
  509. Only on monochrome monitor. Either 16 pixel high characters or 8 
  510. pixel high characters will provide 23 or 48 lines on the screen 
  511. respectively.
  512.  
  513. Flip (F9)
  514.  
  515. Flip between Edit and Output screen. Press any key to return to 
  516. the Edit screen
  517.  
  518. Direct (Shift F9)
  519.  
  520. Switch to Direct mode, where commands will be actioned 
  521. immediately. Some commands, such as loop commands are not 
  522. available in direct mode. Direct mode can also be entered by 
  523. pressing Esc key. The last 8 commands entered in direct mode are 
  524. remembered and can be recalled using the up and down arrow keys. 
  525. The Undo key will recall the last command. 
  526.  
  527. A procedure can be called from direct mode.
  528.  
  529. Test (F10)
  530.  
  531. Tests all loops, subroutines and conditional instructions for 
  532. consistency without running the program.
  533.  
  534. Run (Shift F10)
  535.  
  536. The program in the editor memory is started. A running program can 
  537. be interrupted using Ctrl Shift Alt keys together.
  538.  
  539.  
  540. Clock Display
  541.  
  542. The clock can be set by clicking on the clock and entering a new 
  543. time.
  544.  
  545. Line Numbers
  546.  
  547. Clicking on the line number box (beneath the clock) allows you to 
  548. enter a line number. On input the cursor will jump to this line 
  549. number. Also activated with Ctrl G.
  550.  
  551.  
  552. COMMANDS AND FUNCTIONS
  553. ======================
  554.  
  555. The following commands and functions have been sorted by  alphabetical 
  556. order.  Each entry describes the command syntax and the action of  the 
  557. command.  Some  of the more complex commands have examples.  The  full 
  558. GFA-BASIC  Interpreter Reference manual contains examples for most  of 
  559. the commands. The advanced commands such as the operating system calls 
  560. BIOS, GEMDOS and XBIOS are not covered here and should be consulted in 
  561. the GFA-BASIC Interpreter Reference manual.
  562.  
  563. *
  564. Syntax:    *y
  565. Action:    returns the address of variables, but for strings or arrays
  566.            the address of the descritpor is returned. (ARRPTR is the
  567.            same as *).
  568.  
  569. +
  570. Syntax:    a$+b$
  571. Action:    Concatenation operator, to add strings together.
  572.  
  573. +          Arithmetic operator (a+b adds a and b).
  574. *          a*b (a times b).
  575. /          a/b (a divided by b).
  576. ^          a^b (a to the power b).
  577. <>         a<>b (a not equal b).
  578. <=         a<=b (a less than or equal to b).
  579. >=         a>=b (a greater than or equal to b).
  580.  
  581.  
  582. ==
  583. Syntax:    a==b
  584. Action:    Comparison operator for approximately  equal 'a' and 'b' are
  585.            numeric expressions. The == operator is used in the same way
  586.            as a comparison with = but only 28  bits of the mantissa are
  587.            compared i.e. about 8.5 digits.
  588.  
  589. @
  590. Syntax:    @FRED
  591. Action:    GOSUB PROCEDURE fred (@ is synonymous with GOSUB).
  592.  
  593. ABS
  594. Syntax:    ABS(X)
  595. Action:    Returns the absolute value of a number. (see also SGN).
  596.  
  597. ABSOLUTE
  598. Syntax:    ABSOLUTE x,y
  599. Action:    Assigns the address y to the variable x.
  600.  
  601. ACHAR
  602. Syntax:    ACHAR code,x,y,font,style,angle
  603. Action:    ASCII characters value 'code' are displayed at the graphics
  604.            location x,y.
  605.          Font can be:
  606.            0 = 6x6 (Icon font).
  607.            1 = 8x8 (Normal colour font).
  608.            2 = 8x16 (Normal monochrome font).
  609.          Larger values are taken to be the font header address of a
  610.          GDOS font.
  611.            Text type (bold, faint etc. 0-31) and output angle
  612.            (0,900,1800,2700) can be specified.
  613.  
  614. ACLIP
  615. Syntax:    ACLIP flag,xmin,ymin,xmax,ymax
  616. Action:    To define a 'clipping' rectangle to which LINE-A screen
  617.            output will be limited.
  618.            Flag 0 = clipping off, non zero = on.
  619.  
  620. ACOS
  621. Syntax:    ACOS(x)
  622. Action:    Returns the arc-cosine (in radians) of x.
  623.  
  624. ADD(x,y)
  625. Syntax:    z%=ADD(x%,y%)
  626. Action:    Integer addition.
  627.  
  628. ADD
  629. Syntax:    ADD x,y
  630. Action:    Increase value of variable x by y.
  631.  
  632. ADDRIN
  633. Syntax:    address of the AES Address Input block.
  634.            With an index after this function, the appropriate 
  635.            parameter block is accessed directly.
  636.            ADDRIN(2)=x is the same as
  637.            LPOKE ADDRIN+2,x
  638.  
  639. ADDROUT    address of the AES Address Output block, see above.
  640.  
  641. AFTER ticks GOSUB proc (see also EVERY).
  642. AFTER CONT
  643. AFTER STOP
  644.            Procedures can be called after the expiry of a set time.
  645.            Time in ticks (200ths of a second).
  646.            To continue the process, use CONT, and to stop
  647.            use STOP.
  648.  
  649. ALERT
  650. Syntax:    ALERT a,message$,b,button$,var
  651. Action:    Creates an alert box
  652.            'a' chooses type of alert symbol, 0=none, 1=!, 2=?, 3=stop
  653.            'message$' Contains main text. 
  654.            Up to 4 lines of 30 characters/line
  655.            lines are separated by the '|' symbol (Shift \).
  656.            'button$'  Contains text for the buttons 'B'.
  657.            'b' is the button to be highlighted (0,1,2,3) 
  658.            to be selected by just pressing return.
  659.            'var' This variable is set to the number of the button 
  660.            selected.
  661.  
  662. Example:   ALERT 1,"Pick a|button",1,"Left|Right",a%
  663.            ALERT 0,"You pressed|Button"+STR$(a%),0,"OK",a%   
  664.  
  665. ALINE
  666. Syntax:    ALINE x1,y1,x2,y2,f,ls,m
  667. Action:    Draw a line using LINE A. x1,y1 are the start coordinates 
  668.            x2,y2 end of line. f = colour (0-15). ls = line style in 16 
  669.            bit information, (solid, dashed, dotted ..).
  670.            m  mode
  671.            0  Replace
  672.            1  Transparent
  673.            2  Inverted
  674.            3  Inverted transparent
  675.  
  676.  
  677. AND
  678. Syntax:    x AND y
  679. Action:    Logical operator, performs a logical AND, results in a true 
  680.            or false result.
  681. AND()
  682. Syntax:    AND(x,y)
  683. Action:    See AND above.
  684.  
  685. APOLY TO
  686. Syntax:    APOLY adr_pnt,num_pnt,y0 TO y1,f,m,addr,num_pattern
  687. Action:    Similar to POLYFILL, draws a sequence of joined lines, with 
  688.            'num_pnt' corners, and fills the resulting area with a user 
  689.            defined pattern. 'adr_pnt' is the address of the array 
  690.            holding the alternating x,y corner coordinates. 'num_pnt' 
  691.            is the number of points. y0 and y1 specify the highest and 
  692.            lowest part of the screen where filling can occur. The 
  693.            parameters f,m,addr,num_pattern are the same as for HLINE.
  694.  
  695. APPL_EXIT
  696. Syntax:    APPL_EXIT()
  697. Action:    Informs the system prog has finished - this is a dummy 
  698.            function as QUIT or SYSTEM do this automatically.
  699.  
  700. APPL_FIND
  701. Syntax:    APPL_FIND(fname$)
  702. Action:    Returns the ID of the sought after application. Either 
  703.            returns the apps ID or -1 if it cant be found. fname$ is an 
  704.            8 character filename - without extension. 
  705.            
  706. Example:    PRINT APPL_FIND("CONTROL") 
  707.  
  708.            prints  -1 if it cant find the  CONTROL.ACC,  or 
  709.            returns it's ID [2].
  710.  
  711. APPL_INIT
  712. Syntax:    APPL_INIT()
  713. Action:    Announce the program as an application.
  714.  
  715. APPL_READ
  716. Syntax:    APPL_READ(id,len,adr_buffer)
  717. Action:    Instruction bytes can be read from the event buffer.
  718.            id - id of the application from whose buffer reading is to 
  719.            be done.
  720.            len - number of bytes to read.
  721.            adr_buffer - address of the buffer.
  722.  
  723. APPL_TPLAY(mem,num,speed)
  724. APPL_TRECORD(mem,num)
  725.            APPL_TRECORD makes a record of user activities, and TPLAY 
  726.            plays these back at the specified speed (1 - 1000).
  727.            * ONLY VALID on TOS 1.4 and above. *
  728.  
  729. APPL_WRITE
  730. Syntax:    APPL_WRITE(id,len,adr_buffer)
  731. Action:    Bytes are written to the event buffer. SEE APPL_READ.
  732.  
  733. ARECT
  734. Syntax:    ARECT x1,y1,x2,y2,f,m,addr,num_pattern
  735. Action:    Similar to PBOX, x1,y1 and x2,y2 are opposite corners of a 
  736.            rectangle. The parameters f,m,addr,num_pattern are the same 
  737.            as for HLINE.
  738.  
  739. ARRAYFILL
  740. Syntax:    ARRAYFILL x(),n
  741. Action:    Assigns the value 'n' to all elements of a field array
  742.            x().
  743.  
  744. ARRPTR
  745. Syntax:    ARRPTR(x)
  746. Action:    Finds the address of the (6 byte long) descriptor of
  747.            a string or field. (Same as *x)
  748.  
  749. ASC
  750. Syntax:    ASC(x$)
  751. Action:    Finds the ascii code of the first character of a string.
  752.  
  753. ASIN
  754. Syntax:    ASIN(x)
  755. Action:    Returns the arc-sine (in radians) of x.
  756.  
  757. ATEXT
  758. Syntax:    ATEXT x,y,font,s$
  759. Action:    Output text at x,y coordinates using A LINE.
  760.  
  761. ATN
  762. Syntax:    ATN(x)
  763. Action:    Returns the arc tangent of x.
  764.  
  765. BASEPAGE
  766. Syntax:    BASEPAGE
  767. Action:    Returns the address of the basepage of GFA-Basic.
  768.  
  769. BCHG(x,y)
  770. BCLR(x,y)
  771.            Allow setting and resetting of bits. 
  772.            BCLR sets the y-th bit of x to zero.
  773.  
  774. BGET
  775. Syntax:    BGET #i,adr,cnt
  776. Action:    Reads from a data channel into an area of memory
  777.  
  778.            'i'   \
  779.            'adr'  -- integer expressions.
  780.            'cnt' /            'i'       is the channel number.
  781.            'cnt'     bytes are read in and stored in memory
  782.                      starting at address 'adr'
  783.            Unlike BLOAD, several different areas of memory can be
  784.            read from a file.
  785.  
  786. BIN$
  787. Syntax:    BIN$(x[,n])
  788. Action:    Changes value of 'x' to a string containing the binary 
  789.            value of 'x'. The optional parameter 'n' specifies the 
  790.            number of character positions to be used (1 to 32).
  791.  
  792. BIOS
  793. Syntax:    BIOS(n[,x,y])
  794. Action:    To call the BIOS routine. The optional parameter list can 
  795.            be prefixed with W: or L: to denote word or longword 
  796.            parameters. (if non given, default is W:)
  797. Example:
  798.            REPEAT
  799.            UNTIL BIOS(11,-1) AND 4
  800.            
  801.            Waits for the Control key to be pressed.
  802.  
  803.            Please refer to GFA-BASIC Interpreter Manual for full  list 
  804.            of BIOS calls. 
  805.  
  806. BITBLT
  807. Syntax:    BITBLT s%(),d%(),p%()
  808. Action:    Raster copying command similar to GET and PUT but
  809.            more flexible and faster for some applications.
  810.            's%' the description of the source raster
  811.            'd%' the description of the destination raster
  812.            'p%' co-ordinates of the two equally sized rectangles
  813.                 and the copying mode (see PUT).
  814.  
  815. BLOAD/BSAVE
  816. Syntax:    BLOAD "filename" [,address]
  817.            BSAVE "filename",address,length
  818. Action:    Load and save memory from and to disc drive.
  819.  
  820. Example:   DEFFILL 1,2,4
  821.            PBOX 100,100,200,200
  822.            BSAVE "RECT.PIC",XBIOS(2),32000
  823.            CLS
  824.            PRINT "IMAGE STORED. Press a key to continue"
  825.            ~INP(2)
  826.            CLS
  827.            BLOAD "RECT.PIC",XBIOS(2)
  828.  
  829. BMOVE
  830. Syntax:    BMOVE scr,dst,cnt
  831. Action:    Fast movement of memory blocks.
  832.            'scr' is the address at which the block to be moved
  833.            begins.
  834.            'dst' is the address to which the block is to moved
  835.            'cnt' is the length of the block in bytes.
  836.  
  837. BOUNDARY
  838. Syntax:    BOUNDARY n
  839. Action:    Uses function vsf_perimeter to switch off (or on) borders 
  840.            on filled shapes (PBOX, PCIRCLE ..). If n is zero - no 
  841.            border, n - non zero = border.
  842. BOX
  843. Syntax:    BOX x,y,xx,yy
  844. Action:    Draws a rectangle with corners at (x,y) and (xx,yy)
  845.  
  846. BPUT
  847. Syntax:    BPUT #n,adr,cnt
  848. Action:    Reads from an area of memory out to a data channel.
  849.            'n' is a channel number.
  850.            'adr' is start address of memory to read from.
  851.            'cnt' bytes are read from address.
  852.  
  853. BSAVE      See BLOAD
  854.  
  855. BSET(x,y)  Allows setting and resetting of bits. 
  856. BTST(x,y)  BSET sets the y-th bit of x to 1.
  857.            BTST results in -1 (TRUE) if bit y of x is set.
  858.  
  859. Example:   x=BSET(0,3)
  860.            PRINT x,BSET(0,5)
  861.  
  862. BYTE(x)    Returns the lower 8 bits of the numerical expression x. 
  863.            (See also CARD(), WORD() ).
  864.            
  865. BYTE{x}    As  a function eg.  y=BYTE{x} one can read the contents  of 
  866.            the address x.  As a command one writes to address  x.  eg. 
  867.            BYTE{x}=y. This is similar to PEEK and POKE but is not done 
  868.            in supervisor mode.  (See also CARD{},  INT{},  LONG{}, {}, 
  869.            FLOAT{}, SINGLE{}, DOUBLE{}, CHAR{} ).
  870.  
  871. C:
  872. Syntax:    C:addr([ x,y,....L:x, w:y])
  873. Action:    Calls a C or assembler program with parameters as in C. The 
  874.            parameters can be sent as 32-bit long words or 16-bit words 
  875.            to the subroutine.  eg.  a%=C:adr%(L:x,W:y,z) leads to  the 
  876.            following situation on the stack:
  877.            (sp)     ->return address (4bytes)
  878.            4(sp)    ->x (4 bytes)
  879.            8(sp)    ->y (2 bytes)
  880.            10(sp)   ->z (2 bytes)
  881.            The value returned by the call is the contents of D0.
  882.  
  883. CALL
  884. Syntax:    CALL addr([ x,y,....L:x, w:y])
  885. Action:    Calls a machine code or  C  subroutine   at address 'addr'. 
  886.            When the call is made,  the return address is on the top of 
  887.            the stack, followed by the number of parameters as a 16-bit 
  888.            word,  then  the address of the parameter list as a  32-bit 
  889.            word.
  890.  
  891. CARD(x)    Returns  the lower 16 bits of the numerical  expression  x. 
  892.            (See also BYTE, WORD).
  893.  
  894. CARD{x}    Reads/writes   a  2-byte  unsigned  integer   (similar   to 
  895.            DPEEK/DPOKE). (See also BYTE{},  INT{},  LONG{}, {}, 
  896.            FLOAT{}, SINGLE{}, DOUBLE{}, CHAR{} ).
  897.  
  898. CASE       See SELECT.
  899.  
  900. CFLOAT(x)  Changes  the integer x into a floating point  number.  (See 
  901.            also CINT).
  902.  
  903. CHAIN
  904. Syntax:    CHAIN f$
  905. Action:    Loads a GFA  Basic  program file into memory  and starts it 
  906.            immediately it is loaded.  If no extension is given  '.GFA' 
  907.            is assumed.
  908.  
  909. Example:   CHAIN "A:\EXAMPLE.GFA"
  910.  
  911. CHAR{x}    Reads  a string of bytes until a null byte is  encountered, 
  912.            or writes the specified string of bytes and appends a  null 
  913.            byte. 
  914.  
  915. Example:   PRINT CHAR{BASEPAGE+129} prints the command line.
  916.  
  917. CHDIR
  918. Syntax:    CHDIR "directory name"
  919. Action:    Changes the current directory. 
  920.  
  921. Example:   CHDIR "B:\TEST"
  922.  
  923. CHDRIVE
  924. Syntax:    CHDRIVE n or n$
  925. Action:    Sets the default disk drive 0=current, 1=A, 2=B etc.
  926.  
  927. Example:   CHDRIVE 1
  928.            PRINT DFREE(0)
  929.            PRINT DIR$(2)
  930.            CHDRIVE "C:\"
  931.  
  932. CHR$(x)    Returns the character from a specified ASCII code.
  933.  
  934. Example:   PRINT CHR$(65)     !PRINTS A
  935.  
  936. CINT(x)    Changes  a  floating point number into a  rounded  integer. 
  937.            (See also CFLOAT).
  938.  
  939. CIRCLE
  940. HOW:       CIRCLE x,y,r[,w1,w2]
  941. Action:    Draws a circle with centre coordinates at x,y and a  radius 
  942.            r.  Additional  start  and  end angles w1  and  w2  can  be 
  943.            specified to draw a circular arc.
  944.  
  945. Example:   CIRCLE 320,200,100   
  946.  
  947. CLEAR
  948. Syntax:    CLEAR
  949. Action:    Clears all variables and fields.
  950.  
  951. CLEARW
  952. Syntax:    CLEARW n
  953. Action:    Clears the contents of the window numbered 'n'
  954.  
  955. CLIP x,y,w,h [OFFSET x0,y0]
  956. CLIP x1,y1 TO x2,y2 [OFFSET x0,y0]
  957. CLIP #n [OFFSET x0,y0]
  958. CLIP OFFSET x,y
  959. CLIP OFF
  960.  
  961.            This group of commands provide 'Clipping' functions,ie. the 
  962.            limiting of graphic display within a specified  rectangular 
  963.            screen area.
  964.            The  command  CLIP x,y,w,h defines the  clipping  rectangle 
  965.            starting  at upper left coordinates x,y and extends w  wide 
  966.            and h high.
  967.            The  next  command  CLIP ..  TO  ..  allows  input  of  the 
  968.            diagonally opposite corners of the clipping rectangle.
  969.            The third variant makes it possible to dfine the limits  of 
  970.            the  window  'n'.  The optional additional  command  OFFSET 
  971.            x0,y0  makes  it  possible to redefine the  origin  of  the 
  972.            graphic display. If used in its own right this command sets 
  973.            the origin for graphic display at x0,y0.
  974.            The command CLIP OFF turns clipping off.
  975.  
  976. CLOSE
  977. Syntax:    CLOSE [#n]
  978. Action:    Close a data channel or a channel to a  previously   OPENed 
  979.            device.  If  the  channel number  is  omitted,  all  opened 
  980.            channels are closed.
  981.  
  982. CLOSEW
  983. Syntax:    CLOSEW n
  984. Action:    Closes the window numbered n.
  985.  
  986. CLR
  987. Syntax:    CLR var [ ,var ]
  988. Action:    Deletes and sets specified variables (not arrays) to 0.
  989.  
  990. CLS
  991. Syntax:    CLS [#n]
  992. Action:    Clears the screen [numbered n].
  993.  
  994. COLOR
  995. Syntax:    COLOR color
  996. Action:    Sets the colour for drawing/text. (0-15).
  997.  
  998. COMBIN
  999. Syntax:    z=COMBIN(n,k)
  1000. Action:    Calculates the number of combinations of n elements to  the 
  1001.            kth class without repetitions. Defined as z=n!/((n-k)!*k!).
  1002.  
  1003. CONT
  1004. Syntax:    CONT
  1005. Action:    Resumes execution of a program.
  1006.            Continue the execution of a program after interruption.
  1007.  
  1008. CONTRL     Address of the VDI control table.
  1009.            With  an  index  after  this  function,   the   appropriate 
  1010.            parameter block is accessed directly.
  1011.            CONTRL(2)=x is the same as
  1012.            DPOKE CONTRL+4,x
  1013.  
  1014. COS
  1015. Syntax:    COS(x)
  1016. Action:    Returns the cosine of value x (radians)
  1017.            
  1018. COSQ(x)    Returns the cosine of value x  from  an internal  table  in 
  1019.            steps  of 16th of a degree so is 10 times faster than  COS. 
  1020.            (in degrees).
  1021.  
  1022. CRSCOL  CRSLIN
  1023. Syntax:    CRSCOL
  1024.            CRSLIN
  1025. Action:    Returns current cursor line and column. (see also PRINT
  1026.            AT).
  1027.  
  1028. CURVE
  1029. HOW:       CURVE x0,y0,x1,y1,x2,y2,x3,y3
  1030. Action:    The  BEZIER-Curve starts at x0,y0,  and ends at  x3,y3.  
  1031.            The curve  at  x0,y0 is at a tangent with a line from  
  1032.            x0,y0  to x1,y1;  and  at  x3,y3 is at a tangent with 
  1033.            a  line  between x3,y3 and x2,y2.
  1034.  
  1035. Example:
  1036.           x0=10
  1037.           y0=10
  1038.           x1=50
  1039.           y1=110
  1040.           x2=150
  1041.           y2=200
  1042.           x3=350
  1043.           y3=300
  1044.           LINE x0,y0,x1,y1
  1045.           LINE x2,y2,x3,y3
  1046.           CURVE x0,y0,x1,y1,x2,y2,x3,y3
  1047.  
  1048.  
  1049. CVI   CVL   CVS   CVF   CVD
  1050. Syntax:    CVI(x$) .... CVD(x$)
  1051. Action:    Changes character strings into numeric variables.
  1052.       CVI  Changes a 2-byte string into an integer
  1053.       CVL     "    " 4-byte    "    "   "    "
  1054.       CVS     "    " 4-byte basic string into a floating  point number
  1055.       CVF     "    " 6-byte    "      "    "  a GFA 1 or 2    "
  1056.       CVD     "    " 8-byte    "      "    "  a GFA 3 floating point.
  1057.  
  1058. *******************************************************************
  1059.  
  1060.  
  1061. DATA
  1062. Syntax:    DATA [CONST[,CONST] ...]
  1063. Action:    Used as memory variables which can be read by the READ
  1064.            command. The constants are separated by commas.
  1065.  
  1066. Example:   For i=1 to 3
  1067.                READ A
  1068.                PRINT A
  1069.            Next i
  1070.            DATA 1,2,3,4
  1071.  
  1072. DATE$
  1073. Syntax:    DATE$
  1074. Action:    Returns the system date.
  1075.  
  1076.            DATE$=date$        Sets the system date.  (either  DD.MM.YY 
  1077.                               (UK) orMM.DD.YY (US)
  1078.                               The format depends on MODE setting.
  1079.  
  1080. DEC
  1081. Syntax:    DEC var
  1082. Action:    Reduces the value of 'var' by 1
  1083.  
  1084. DEFAULT    See SELECT
  1085.  
  1086. DEFBIT
  1087. DEFBYT
  1088. DEFWRD
  1089. DEFFLT 
  1090. DEFSTR 
  1091.            The  instruction  DEFxxx  sets the varaible  type  to  that 
  1092.            specified. 
  1093.  
  1094. Example:   DEFBIT "a-z"       defines all variables as boolean.
  1095.  
  1096. DEFFILL
  1097. Syntax:    DEFFILL [col],[style],[pattern] or  DEFFILLL [col],A$
  1098. Action:    Sets fill colour and pattern, or allows user-defined
  1099.            patterns.
  1100.            'style' - 0=empty, 1=filled, 2=dots, 3=lines, 4=user
  1101.            24 dotted patterns and 12 lined can by chosen.
  1102.            A user-defined fill pattern is defined in the second
  1103.            variation - DEFFILL col,A$ by defining a 16 x 16 bit
  1104.            pattern array.
  1105.  
  1106. DEFFN
  1107. Syntax:    DEFFN func [(x1,x2,..)]=expression
  1108. Action:    Allows  the definition of single line functions.  The  term 
  1109.            'expression' can be any numeric or string expression.
  1110.            
  1111. Example:   DEFFN test(y,a$)=x-y+LEN(a$)
  1112.            x=2
  1113.            PRINT @test(4,"abcdef")
  1114.            See also FN
  1115.  
  1116. DEFLINE
  1117. Syntax:    DEFLINE [style],[thickness],[begin_s,end_s]
  1118. Action:    Sets line style, width & type of line start and end.
  1119.            'style' determines the style of line:
  1120.            1 Solid line
  1121.            2 Long dashed line
  1122.            3 Dotted
  1123.            4 Dot-dashed
  1124.            5 Dashed
  1125.            6 Dash dot dot ..
  1126.            7 User defined
  1127.            'thickness' sets width in pixels (odd numbers only).
  1128.            The  start  and  end  symbols  are  defined  by  the   last 
  1129.            parameter, and can be:
  1130.            0 Square
  1131.            1 Arrow
  1132.            2 Round
  1133.  
  1134.  
  1135. DEFLIST    
  1136. Syntax:    DEFLIST x
  1137. Action:    Defines the program listing format.
  1138.            x   Command   Variable
  1139.            0   PRINT     abc
  1140.            1   Print     Abc
  1141.            2   PRINT     abc#
  1142.            3   Print     Abc#
  1143.  
  1144. DEFMARK
  1145. Syntax:    DEFMARK [C],[A],[G]
  1146. Action:    Sets colour,type and size of the corner points to be
  1147.            mark using the command polymark
  1148.            'C' is the colour register number
  1149.            'A' defines the type of mark. the following types
  1150.            are possible :-
  1151.            1=dot
  1152.            2=plus sign
  1153.            3=asterisk
  1154.            4=square
  1155.            5=cross
  1156.            6=hash
  1157.            all other values return the asterisk symbol
  1158.            'G' sets the size of mark
  1159.  
  1160. DEFMOUSE
  1161. Syntax:    DEFMOUSE n or  DEFMOUSE a$
  1162. Action:    Chooses a pre-defined mouse form or defines a new one
  1163.            the following mouse forms are available :-
  1164.  
  1165.            0=arrow             1=expanded (rounded) X
  1166.            2=bee               3=pointing hand
  1167.            4=open hand         5=thin crosswire
  1168.            6=thick crosswire   7=bordered crosswire
  1169.  
  1170.            A mouse can be defined by the command defmouse a$
  1171.            16*16 dots are available to create a shape. Also
  1172.            a 'mask' must be defined so that the cursor remains
  1173.            visible when it is the same colour as the background
  1174.            one of the 256 dots must be defined as the starting
  1175.            point to which the mouse functions will relate.
  1176.  
  1177. Example:
  1178.            DEFMOUSE 2
  1179.            PAUSE 1
  1180.            m$=MKI$(0)+MKI$(0)+MKI$(1)+MKI$(0)+MKI$(1)
  1181.            FOR i%=1 TO 16
  1182.               m$=m$+MKI$(65535)
  1183.            NEXT I%
  1184.            FOR i%=1 TO 16
  1185.               m$=m$+MKI$(1)
  1186.            NEXT i%
  1187.            PBOX 200,150,400,250
  1188.            DEFMOUSE m$
  1189.            REPEAT
  1190.            UNTIL MOUSEK
  1191. DEFNUM
  1192. Syntax:    DEFNUM n
  1193. Action:    Affects  output  of numbers by the PRINT  command  and  its 
  1194.            variants.  All numbers are outputted to occupy n  character 
  1195.            positions, not counting the decimal point.
  1196.  
  1197.  
  1198. DEFTEXT
  1199. Syntax:    DEFTEXT [colour],[attr],[angle],[height],[fontnr]
  1200. Action:    Defines the colour,style,rotation and size of text
  1201.            to be printed using the text command.
  1202.  
  1203.            'colour' colour register number (0-15).
  1204.            'attr' text style - 0=normal 1=bold 2=light 4=italic
  1205.            8=underlined 16=outlined (can be combined).
  1206.            'angle'= rotation only the following  are possible :-
  1207.            0 deg (0), 90 deg (900), 180 deg (1800), 270 deg (2700)
  1208.            'height' size of text - 4=icon, 6=8*8, 13=std, 32=enlarged.
  1209.            'fontnr' - the number of a desired character set. This font 
  1210.            must  have  been  previously  installed  (See  also   GDOS, 
  1211.            VST_LOAD_FONT, VQT_NAME).
  1212.  
  1213. Example:
  1214.            FOR i%|=0 TO 5
  1215.               DEFTEXT 1,2^i|,0,13
  1216.               TEXT 100,i|*16+100,"This is text attribute "+STR$(i|)
  1217.            NEXT i|
  1218.  
  1219.  
  1220. DEG(x)     Converts x from radians to degrees. See also RAD.
  1221.  
  1222. DELAY x    Suspends   program   operation  for  x  seconds   (with   a 
  1223.            theroetical resolution in milliseconds). See aslo PAUSE.
  1224.  
  1225. DELETE
  1226. Syntax:    DELETE x(i)
  1227. Action:    Removes  the ith element of array x.  All elements  with  a 
  1228.            larger  index  are  shifted down  one  position.  See  also 
  1229.            INSERT.
  1230.  
  1231. DFREE
  1232. Syntax:    DFREE(n)
  1233. Action:    Locates free space on a disc 'n' = drive number (0-15)
  1234.  
  1235. DIM
  1236. Syntax:    DIM var(indices)[,var(indices),.....]
  1237. Action:    Sets the dimensions of an array or string array.
  1238.  
  1239. DIM?       
  1240. Syntax:    DIM?(field())
  1241. Action:    Determines the number of elements in an array.
  1242.            Note - arrays have an element '0'.
  1243.  
  1244. DIR
  1245. Syntax:    DIR "filespec" [TO "file"]
  1246. Action:    Lists the files on a disc.  The output can be directed to a 
  1247.            file or other device.
  1248.  
  1249. Example:   "LST:" See also FILES.
  1250.  
  1251. DIR$
  1252. Syntax:    DIR$(n)
  1253. Action:    Names the active directory for drive 'n'
  1254.            'n' is drive number (1=A:, 2=B: ...).
  1255.  
  1256. DIV
  1257. Syntax:    DIV var,n
  1258. Action:    Divides the value of var by n. As var=var/n but 30% faster.
  1259.  
  1260. DIV()
  1261. Syntax:    a%=DIV(x,y)
  1262. Action:    See DIV above.
  1263.  
  1264.  
  1265. DMACONTROL
  1266. Syntax:    DMACONTROL ctrlvar
  1267. Action:    Controls the DMA sound on the STE.
  1268.            cntrlvar = 0 - stop sound
  1269.                       1 - Play sound once
  1270.                       2 - Play sound in a loop
  1271.  
  1272. DMASOUND
  1273. Syntax:    DMASOUND beg,end,rate[,ctrl]
  1274. Action:    Output of DMA sampled sound on the STE.
  1275.            beg  - Sample start address.
  1276.            end  - Sample end address.
  1277.            rate - Sample rate 0=6.25 kHz,  1=12.5 kHz, 2=25 kHz, 
  1278.                   3=50kHz.
  1279.            ctrl - See DMACONTROL above.
  1280.            
  1281. Example:   'Try each of the DMASOUND lines below.
  1282.            n%=360*32
  1283.            DIM a|(n%)
  1284.            'DMASOUND V:a|(0),V:a|(n%),0
  1285.            'DMASOUND V:a|(0),V:a|(n%),1
  1286.            'DMASOUND V:a|(0),V:a|(n%),2
  1287.            DMASOUND V:a|(0),V:a|(n%),3,3
  1288.            FOR i%=0 TO n%
  1289.             a|(i%)=128+SINQ(i%*i%/7200)*127
  1290.            NEXT i%
  1291.            REPEAT
  1292.            UNTIL MOUSEK
  1293.            DMACONTROL 0
  1294.  
  1295.  
  1296. DO....LOOP
  1297. Syntax:    DO
  1298.            (instructions)
  1299.            LOOP
  1300. Action:    Creates an endless loop, exit only with EXIT IF or GOTO.
  1301.  
  1302. DO UNTIL condition
  1303. DO WHILE condition
  1304.          
  1305.            The  commands DO and LOOP can be extended using  UNTIL  and 
  1306.            WHILE.  The  loop  DO WHILE causes a loop as  long  as  the 
  1307.            condition is true. See also LOOP WHILE, LOOP UNTIL.
  1308.  
  1309. DOUBLE{x}  Reads/writes  an  8-byte floating point  variable  in  IEEE 
  1310.            double precision format.  (See also BYTE{},  CARD{}, INT{}, 
  1311.            LONG{}, {}, FLOAT{}, SINGLE{}, CHAR{} )
  1312.  
  1313.  
  1314. DOWNTO     Used within a FOR..NEXT loop as a counter. Instead of using 
  1315.            step -1,  the command DOWNTO is used,  however STEP is  not 
  1316.            possible with DOWNTO. eg:
  1317.            FOR c=100 DOWNTO 1
  1318.            is the same as FOR c=100 TO 1 STEP -1
  1319.  
  1320.  
  1321. DPEEK(x)   Reads 2 bytes from address x (a word).  Works in supervisor 
  1322.            mode.
  1323.  
  1324. DPOKE x,y  Writes  y  as  a 2 byte word to  address  x.  To  work  in 
  1325.            supervisor mode use SDPOKE ..
  1326.  
  1327.  
  1328. DRAW
  1329. Syntax:    DRAW [TO] [x,y]
  1330.            DRAW [x1,y1][TO x2,y2][TO x3,y3][TO..]
  1331. Action:    Draws points and connects two or more points with
  1332.            straight lines. DRAW x,y is the same as PLOT x,y.
  1333.            DRAW TO x,y connects the point to the last set 
  1334.            point (set by PLOT, LINE or DRAW).
  1335.  
  1336. DRAW expression
  1337. DRAW(i)
  1338. SETDRAW
  1339.            These instructions give a turtle like approach to  drawing. 
  1340.            An  imaginary  pen  is  moved over  the  screen  and  draws 
  1341.            relative to the last point. The 'expression' is a LOGO type 
  1342.            of  convention  controlled by  graphic  commands.  The  pen 
  1343.            leaving  a trail over the 'paper' leaves a  graphic  image. 
  1344.            The statement below is an wxample of how these commands can 
  1345.            be used.
  1346.  
  1347. Example:   DRAW  "PU FD 40 PD FD 40"
  1348.  
  1349.            The available commands are:
  1350.  
  1351. FD n       ForwarD            Moves the 'pen' n pixels forward
  1352.  
  1353. BK n       BacKward           Moves the 'pen' n pixels backwards
  1354.            
  1355. SX x       Scale x            Scales the 'pen' movement for FD and BK
  1356.  
  1357. SY y       Scale y            by the specified factor.  Use SX0 or SY0 
  1358.                               to turn off scaling.
  1359.  
  1360. LT a       Left turn          Turns   the  'pen'  left   through   the 
  1361.                               specified angle a, given in degrees.
  1362.  
  1363. RT a       Right turn         As LT but turns right.
  1364.  
  1365. TT a       Turn To            Turns  the 'pen' to the  absolute  angle 
  1366.                               'a' in degrees. (see below)
  1367.  
  1368.                                0
  1369.                                |
  1370.                                |
  1371.                      270 -- zero point -- 90
  1372.                                |
  1373.                                |
  1374.                               180
  1375.  
  1376.  
  1377. MA x,y     Move Absolute      Moves  the  'pen'  to   the   absolute 
  1378.                               coordinates x,y
  1379.  
  1380. DA x,y     Draw Absolute      Moves  the  'pen'  to   the   absolute 
  1381.                               coordinates x,y and draws a line in  the 
  1382.                               current colour from the last position to 
  1383.                               the point x,y
  1384.  
  1385. MR xr,yr   Move Relative      Moves the 'pen' position in the x and  y 
  1386.                               directions   relative   to   the    last 
  1387.                               position.
  1388.  
  1389. DR xr,yr   Draw  Relative     Moves  the  'pen'  by   the   specified 
  1390.                               displacement   relative  to   its   last 
  1391.                               position and draws a line in the current 
  1392.                               colour  from the last position  to  this 
  1393.                               point.
  1394.  
  1395. The  command SETDRAW x,y,w is an abbreviation for the expression  
  1396. DRAW "MA",x,y,"TT",w.
  1397.  
  1398. CO  c      Colour             Sets 'c' as the character  colour  (see 
  1399.                               parameters for COLOR command).
  1400.  
  1401. PU         Pen Up             Lifts the 'pen' from the 'paper'.
  1402.  
  1403. PD         Pen Down           Lowers the 'pen' onto the 'paper'.
  1404.  
  1405. Additionally the following interrogation functions are available:
  1406.  
  1407. DRAW(0)    returns the x position.
  1408. DRAW(1)    returns the y position.
  1409. DRAW(2)    returns angle in degrees.
  1410. DRAW(3)    returns the X axis scale factor.
  1411. DRAW(4)    returns the Y axis scale factor.
  1412. DRAW(5)    returns the pen flag (-1=PD, 0=PU).
  1413.  
  1414. All these functions return floating point values.
  1415.  
  1416. Example:
  1417.  
  1418.            DRAW "ma 160,200 tt 0"
  1419.            FOR i&=3 TO 10
  1420.              polygon(i&,90)
  1421.            NEXT i&
  1422.  
  1423.            PROCEDURE polygon(n&,r&)
  1424.            LOCAL i&
  1425.            FOR i&=1 TO n&
  1426.              DRAW "fd",r&," rt ",360/n&
  1427.            NEXT i&
  1428.            RETURN
  1429.  
  1430. EDIT
  1431. Syntax:    EDIT
  1432. Action:    Returns to the editor.
  1433.            When used in direct mode the command allows a return
  1434.            to the editor. In a program, is the same as END but
  1435.            without the program end alert box.
  1436.  
  1437. ELLIPSE
  1438. Syntax:    ELLIPSE x,y,rx,ry [,phi0,phi1]
  1439. Action:    Draws an ellipse at x,y, having 'rx' as length of the
  1440.            horizontal axis and 'ry' as length of the vertical axis
  1441.            The optional angles 'phi0' & 'phi1' give start and end
  1442.            angles in tenths of a degree, to create an elliptical arc.
  1443.  
  1444. ELSE       See command IF.
  1445. ELSE IF     "     "    "
  1446.  
  1447.  
  1448. END
  1449. Syntax:    END
  1450. Action:    Closes all files and terminates program execution.
  1451.  
  1452.  
  1453. ENDFUNC    See command FN.
  1454.  
  1455. ENDIF      See command IF.
  1456.  
  1457. ENDSELECT  See command SELECT.
  1458.  
  1459.  
  1460. EOF
  1461. Syntax:    EOF (#n)
  1462. Action:    Determines whether the file pointer for the file with
  1463.            channel number 'n' is at End Of the File.  Returns -1 if it 
  1464.            is, otherwise 0.
  1465.  
  1466.  
  1467. EQV
  1468. Syntax:    x EQV y
  1469. Action:    The operator EQV (equivalence) produces a TRUE result  only 
  1470.            if  the  arguments of both are either TRUE or  both  FALSE. 
  1471.            (same as NOT(x XOR y)).
  1472.  
  1473. EQV(x,y)
  1474. Syntax:    EQV(x,y)
  1475. Action:    Sets a bit of the result if the appropraite bits in x and y 
  1476.            are both set, or both reset. eg:
  1477.            PRINT BIN$(EQV(15,6),4) prints 0110
  1478.  
  1479.  
  1480. ERASE
  1481. Syntax:    ERASE field()
  1482. Action:    Deletes an array and releases the dimensioned area.
  1483.  
  1484.  
  1485. ERR
  1486. Syntax:    ERR
  1487. Action:    Returns the error code of any error that has occurred.
  1488.  
  1489. ERR$
  1490. Syntax:    ERR$(x)
  1491. Action:    Returns, as a string, the GFA Basic error mesage x. 
  1492.  
  1493. ERROR
  1494. Syntax:    ERROR n
  1495. Action:    Simulates the occurrence of the error with the error
  1496.            code 'n' and the appropriate error message is then
  1497.            displayed.
  1498.  
  1499.  
  1500.  
  1501. EVEN
  1502. Syntax:    EVEN n
  1503. Action:    Determines if a number is even.   Returns  TRUE  (-1)   and 
  1504.            FALSE(0). Also see ODD
  1505.  
  1506.  
  1507. EVERY
  1508. EVERY CONT
  1509. EVERY STOP
  1510.  
  1511. Syntax:    EVERY ticks GOSUB proc
  1512. Action:    The command EVERY causes the procedure 'proc' to be  called 
  1513.            every 'ticks' clock units. The clock unit is defined as one 
  1514.            two-hundredth  of a second.  But a branch can only be  done 
  1515.            every  fourth clock unit,  resulting in an  effective  time 
  1516.            resolution of one fiftieth of a second.
  1517.            Using  EVERY  STOP,  the  calling of a   procedure  can  be 
  1518.            prevented.  With EVERY CONT this is again allowed. See also 
  1519.            AFTER.
  1520.  
  1521.  
  1522. EVNT_BUTTON
  1523. Syntax:    EVNT_BUTTON(clicks,mask,state[,mx,my,button,k_state])
  1524. Action:    Waits for one or more mouse clicks,  and returns the number 
  1525.            of clicks.
  1526.            INPUTS
  1527.            clicks - Maximum allowable clicks.
  1528.            mask   - Mask for the desired mouse key:
  1529.                     Bit 0 = 1 : Left Button
  1530.                     Bit 1 = 1 : Right Button
  1531.            state  - Desired status,  in order to terminate the  event. 
  1532.                     Bit allocation as for mask.
  1533.            RETURNED VALUES:
  1534.            mx     - x coordinate of mouse pointer on event termination
  1535.            my     - y coordinate of mouse pointer on event termination
  1536.            button - state of mouse button, bit allocation as for mask.
  1537.  
  1538.            k_state- Condition of keyboard shift keys:
  1539.                     Bit 0 = Right shift key
  1540.                     Bit 1 = Left shift key
  1541.                     Bit 2 = Control key
  1542.                     Bit 3 = Alternate key
  1543.  
  1544. EVNT_DCLICK
  1545. Syntax:    EVNT_DCLICK(new,get_set)
  1546. Action:    Sets the speed for double-clicks of a mouse button.
  1547.            Returns the speed.
  1548.            new - new speed (0-4)
  1549.            get_set - determine whether to set or read. 0=read,1=set.
  1550.  
  1551.  
  1552. EVNT_KEYBD
  1553. Syntax:    EVNT_KEYBD()
  1554. Action:    Waits  for  a key to be pressed and  returns  a  word-sized 
  1555.            value. The low order byte contains the ASCII code, the high 
  1556.            byte contains the keyboard scan code.
  1557.  
  1558.  
  1559. EVNT_MESAG
  1560. Syntax:    EVNT_MESAG(adr_buffer)
  1561. Action:    Waits for the arrival of a message in the event buffer. The 
  1562.            returned value is always 1.
  1563.            adr_buffer  is  the  address of a 16 byte  buffer  for  the 
  1564.            message.  If  0 is used,  then the sytem message buffer  is 
  1565.            used, ie. MENU(1) to MENU(8).
  1566.  
  1567.  
  1568. EVNT_MOUSE
  1569. Syntax:    EVNT_MOUSE(flag,mx,my,mw,mh,mcur_x,mcur_y,button,k_state)
  1570. Action:    Waits  for  the  mouse pointer to  be  located  inside  (or 
  1571.            optionally,  outside)  a specified rectangular area of  the 
  1572.            screen.
  1573.            The returned value is always 1.
  1574.            INPUTS:
  1575.            flag  - Presence inside(0) or outside(1) the desired area.
  1576.            mx,my - Coordinates of top left corner of recatngle.
  1577.            mw    - Width of rectangle.
  1578.            mh    - Height of rectangle.
  1579.            OUTPUTS:
  1580.            mcur_x   x coordinate of mouse when event occurs.
  1581.            mcur_y   y coordinate of mouse when event occurs.
  1582.            button   same as for mask in EVNT_BUTTON.
  1583.            k_state  same as for k_state in EVNT_BUTTON.
  1584.  
  1585.  
  1586. EVNT_MULTI
  1587. HOW:       EVNT_MULTI(flag,clicks,mask,state,m1_flags,m1_x,
  1588.            m1_y,m1_w,m1_h,m2_flags,m2_x,m2_y,m2_w,m2_h,adr_buffer,
  1589.            count[,mcur_x,mcur_y,button,k_state,key,num_clicks])
  1590. Action:    Waits  for the occurence of selected  events.  Returns  the 
  1591.            event  which actually occured,  with bit allocation as  for 
  1592.            'flag' below:
  1593.            INPUT:
  1594.            flag     Sets the event(s) to be waited for as follows:
  1595.                     BIT 0 keyboard           MU_KEYBD
  1596.                     BIT 1 mouse button       MU_BUTTON
  1597.                     BIT 2 first mouse event  MU_M1
  1598.                     BIT 3 second mouse event MU_M2
  1599.                     BIT 4 report event       MU_MESAG
  1600.                     BIT 5 timer              MU_TIMER
  1601.            OUTPUT:
  1602.            num_clicks: number of expected mouse clicks
  1603.  
  1604.            The parameters are already described for EVNT_MESAG, etc..
  1605.            With  ON  MENU,  which uses this  routine  internally,  the 
  1606.            parameters  are installed for the instruction ON  MENU  xxx 
  1607.            GOSUB.
  1608.            MENU(1) to MENU(8)  Message buffer.
  1609.            MENU(9)             Returned value.
  1610.            MENU(10)=mcur_x     x mouse position.
  1611.            MENU(11)=mcur_y     y mouse pos.
  1612.            MENU(12)=button     Mouse state button.
  1613.            MENU(13)=k_state    Shift key status.
  1614.            MENU(14)=key        ASCII and scan code.
  1615.            MENU(15)=num_clicks Number of mouse clicks.              
  1616.  
  1617.  
  1618. EVNT_TIMER
  1619. Syntax:    EVNT_TIMER(count)
  1620. Action:    The  function  waits  for a period  of  time  expressed  in 
  1621.            'count' millisecondes.
  1622.            The returned value is always 1.
  1623.  
  1624.  
  1625. EXEC
  1626. Syntax:    EXEC flg,name,cmd,env
  1627.            EXEC (flg,name,cmd,env)
  1628. Action:    Loads and executes machine code programs or compiled
  1629.            programs from disc.                 
  1630.            flg=0 - load and go.
  1631.            flg=3 - load only.
  1632.            'name' - the name of the program.
  1633.            'cmd'  - command line (see BASEPAGE).
  1634.            'env'  - environment string (usually just "").
  1635.            The named program is loaded from disc, the absolute
  1636.            addresses are relocated, a basepage is created, and if
  1637.            required the program run.
  1638.  
  1639.  
  1640. EXIST
  1641. Syntax:    EXIST ("filespec")
  1642. Action:    Determines whether a particular file is present on
  1643.            a disc. If present -1 is returned, else 0 is returned.
  1644.  
  1645.  
  1646. EXIT
  1647. Syntax:    EXIT IF Condition
  1648. Action:    Enables the exit from a loop.
  1649.            If the EXIT command is met within a loop and the exit
  1650.            condition is met, the program continues from the first
  1651.            command after the loop.
  1652.            This command allows any loop to be left ie: FOR...NEXT
  1653.            DO...LOOP,  REPEAT...UNTIL AND  WHILE...WEND.
  1654.  
  1655.  
  1656. EXP
  1657. Syntax:    EXP(X)
  1658. Action:    Calculates the value of an exponent x.
  1659.  
  1660.  
  1661. FACT
  1662. Syntax:    x=FACT(n)
  1663. Action:    Calculates  the factorial (n!) of n and returns the  result 
  1664.            in x. (0!=1).
  1665.  
  1666.  
  1667. FALSE
  1668. Syntax:    FALSE
  1669. Action:    Constant 0. This is simply another way of expressing
  1670.            the value of a condition when it is false and is equal
  1671.            to zero (see also TRUE).
  1672.  
  1673.  
  1674. FATAL
  1675. Syntax:    FATAL
  1676. Action:    Returns the value 0 or -1 according to the type of
  1677.            error.
  1678.            On normal errors the function returns 0. The value -1
  1679.            is returned on all errors where the address of the
  1680.            last executed command is no longer known.
  1681.            Normally this is an operating system error which
  1682.            would lead to the 'bomb' errors and the breakdown of
  1683.            the program.
  1684.  
  1685.  
  1686.  
  1687. FGETDTA
  1688. Syntax:    n%=FGETDTA()
  1689. Action:    Returns the DTA (Disk Transfer Address).
  1690.  
  1691.  
  1692. FIELD
  1693. Syntax:    FIELD #n,num AS svar$ [,num AS svar$,...]
  1694.            FIELD #n,num AT(x)[,num AT(x),...]
  1695. Action:    Divides records into fields.
  1696.            'n' is the channel number of a file previously OPENed.
  1697.            The integer expression 'num' determines the field length.
  1698.            'Svar' is a string variable containing  data for one  field 
  1699.            of a data record.
  1700.            The section 'num AS svar$' can be repeated if the
  1701.            record is to be divided into several fields. The sum of
  1702.            the fields should equal the record length.
  1703.            By using AT() instead of AS,  numeric variables can be read 
  1704.            and  written.  'num'  contains the length of  the  varaible 
  1705.            type. The brackets contain a pointer to the variable.
  1706.            eg:
  1707.            FIELD #2,4 AS a$,2 AT(*b&),8 AT(*c#),6 AS d$
  1708.  
  1709.  
  1710. FILES
  1711. Syntax:    FILES p$ [TO name$]
  1712. Action:    Lists the files on a disk.
  1713.            Like DIR but more detailed data listing.
  1714.  
  1715.  
  1716. FILESELECT
  1717. Syntax:    FILESELECT [#title$],path$,default$,name$
  1718. Action:    Creates a fileselect box on the screen.
  1719.            Title$  can  be a string of max  30  characters.  Allows  a 
  1720.            header  to  be placed in the fileselect box  (TOS  1.4  and 
  1721.            above).
  1722.            path$  is the drive and path - if none specified  then  the 
  1723.            default drive is assumed.
  1724.            default$  contains the name of the file to apppear  in  the 
  1725.            selection line. ("" for no default).
  1726.            name$ contains the selected file, either an empty string if 
  1727.            CANCEL is selected, or the file name selected.
  1728.            See also FSEL_INPUT
  1729.  
  1730. Example: 
  1731.                    FILESELECT #"LOAD File","A:\*.PRG","GFABASIC.PRG",name$
  1732.  
  1733.  
  1734.  
  1735. FILL
  1736. Syntax:    FILL x,y
  1737. Action:    Fills a bordered area with a pattern commencing at
  1738.            the co-ordinates 'x,y'.            
  1739.            Fill pattern can be chosen with the command DEFFILL.
  1740.  
  1741.  
  1742. FIX
  1743. Syntax:    FIX(x)
  1744. Action:    Returns the integer of 'x' after it has been rounded.
  1745.            Same as INT(x) for positive numbers but for negative
  1746.            numbers INT(-1.99)=-2 AND FIX(-1.99)=1.
  1747.            FIX is identical to the function TRUNC and complements
  1748.            FRAC.
  1749.  
  1750.  
  1751. FLOAT{x}   Reads/writes an 8-byte variable in Basic v3 floating  point 
  1752.            format.   (See  also  BYTE{},   CARD{},  INT{},LONG{},  {}, 
  1753.            SINGLE{}, DOUBLE{}, CHAR{} )
  1754.  
  1755. FN
  1756. Syntax:    FN func[(y1,y2...)]
  1757. Action:    Call  to a defined DEFFN function or a FUNCTION.  (you  can 
  1758.            also use @). See also DEFFN, FUNCTION.
  1759.  
  1760.  
  1761. FOR...NEXT
  1762. Syntax:    FOR c=b TO e [STEP s]
  1763.            instructions
  1764.            NEXT c
  1765. Action:    Creates a loop which is executed as many times as specified 
  1766.            at the beginning of the loop.
  1767.  
  1768.  
  1769. FORM INPUT
  1770. Syntax:    FORM INPUT n,a$
  1771. Action:    Enables the insertion of a character string (limited
  1772.            to 255 characters in length) during program execution.
  1773.            'n' = the maximum length of the character string.
  1774.            a$ is the name of the string variable.
  1775.       
  1776. FORM INPUT AS
  1777. Syntax:    FORM INPUT n AS a$
  1778. Action:    Similar  to FORM INPUT,  except the current value of a$  is 
  1779.            displayed, and can be edited.
  1780.  
  1781.  
  1782. ***  the  following  7  commands are part  of  the  AES  FORM  Library 
  1783. commands,  and  are  similar  to  C bindings  for  calling  these  AES 
  1784. functions ***
  1785.  
  1786. FORM_ALERT
  1787. Syntax:    a%=FORM_ALERT(button,string$)
  1788. Action:    Creates an alert box.
  1789.            button  = number of the default button (0-3).
  1790.            string$ = string defining the message in the alert.  (in  C 
  1791.            format)  -  note that the square brackets are part  of  the 
  1792.            string:
  1793.            [i][Message][Buttons]
  1794.            where i = the required alert symbol - see ALERT.
  1795.            Message is a string max 30 characters.
  1796.            Buttons = the name of the 3 buttons.
  1797.            A good use of this command is in trapping errors:
  1798.            
  1799. Example:   ~FORM_ALERT(1,ERR$(ERR))
  1800.  
  1801.  
  1802. FORM_BUTTON
  1803. Syntax:    FORM_BUTTON(tree,obj,clicks,new_obj)
  1804. Action:    Make inputs in a form possible using the mouse.
  1805.            INPUTS:
  1806.            tree   -  address of the object tree
  1807.            obj    -  current object number
  1808.            clicks -  max expected number of mouse clicks
  1809.            OUTPUT:
  1810.            new_obj-  next object to be edited.
  1811.            Returns 0 if the FORM was exited, otherwise >0.
  1812.  
  1813. FORM_CENTER
  1814. Syntax:    FORM_CENTER(tree,fx,fy,fw,fh)
  1815. Action:    Centers the tree, and returns its coordinates.
  1816.            INPUT: tree  - address of the object tree.
  1817.            OUTPUTS:
  1818.            fx,fy    coordinates of top left corner
  1819.            fw,fh    form width and height.
  1820.            returns a reserved value (always 1).
  1821.  
  1822.  
  1823. FORM_DIAL
  1824. HOW:       FORM_DIAL(flag,mi_x,mi_y,mi_w,mi_h,ma_x,ma_y,ma_w,ma_h)
  1825. Action:    Release (or reserve) a rectangular screen area and draw  an 
  1826.            expanding/shrinking rectangle.
  1827.            Returns 0 if an error occured.
  1828.            flag     function
  1829.            0        FMD_START   reserve a display area.
  1830.            1        FMD_GROW    draw expanding box.
  1831.            2        FMD_SHRINK  draw shrinking box.
  1832.            3        FMD_FINISH  release reserved display area.
  1833.            mi_x,mi_y  top left corner of rectangle at min size
  1834.            mi_w,mi_h  width & height  "     "       "  "    "
  1835.            ma_x,ma_y  top left corner of rectangle at max size
  1836.            ma_w,ma_h  width & height   "     "      "  "    "
  1837.  
  1838.  
  1839. FORM_DO
  1840. Syntax:    FORM_DO(tree,start_obj)
  1841. Action:    Pass  management  of FORM over to the AES until  an  object 
  1842.            with EXIT or TOUCH EXIT status is clicked on.
  1843.            Returns  the number of the object whose clicking or  double 
  1844.            clicking  caused the function to end.  If it was  a  double 
  1845.            click, bit 15 will be set.
  1846.            tree      = address of the object tree.
  1847.            start_obj = Number of the first editable field (if there is 
  1848.            one). 
  1849.  
  1850.  
  1851. FORM_ERROR
  1852. Syntax:    FORM_ERROR(err)
  1853. Action:    Displays the ALERT associated with the error numbered err.
  1854.            
  1855. Example:   PRINT FORM_ERROR(10)
  1856.  
  1857.    
  1858. FORM_KEYBD
  1859. Syntax:    FORM_KEYBD(tree,obj,next_obj,char,new_obj,next_char)
  1860. Action:    Allows a form to be edited via the keyboard.
  1861.            Returns 0 if the FORM was exited, otherwise >0.
  1862.            tree     address of the object tree
  1863.            obj      number of the object to be edited
  1864.            next_obj number of the next EDITable object in the tree
  1865.            char     input character
  1866.            new_obj  object to be EDITed on the next call
  1867.            returns next_char - next character (derived from keyboard)
  1868.            
  1869.            This function is a subroutine of FORM_DO.
  1870.  
  1871.  
  1872. FRAC
  1873. Syntax:    FRAC(x)
  1874. Action:    Returns the digits after the decimal point in a number.
  1875.            'x' can be any numeric expression. if 'X' is an integer
  1876.            then a zero is returned,  therefore FRAC(x)=x-TRUNC(x)
  1877.  
  1878.  
  1879. FRE
  1880. Syntax:    f%=FRE(X) or f%=FRE()
  1881. Action:    Returns the amount of memory free (in bytes).
  1882.            The parameter 'x' is disregarded, but if present a 'Garbage 
  1883.            Collection' is carried out.  (non current strings are freed 
  1884.            from memory).
  1885.  
  1886.  
  1887. FSEL_INPUT
  1888. Syntax:    n%=FSEL_INPUT(path$,name$,[button])
  1889. Action:    Calls   the   AES  fileselect   library,   to   provide   a 
  1890.            fileselector.
  1891.            The optional parameter 'button':
  1892.            Returns  a  1 or 0 depending whether 'OK' or  'Cancel'  was 
  1893.            clicked on.
  1894.            ON ENTRY:
  1895.            path$    = initial directory path
  1896.            name$    = Default name
  1897.            ON EXIT:
  1898.            path$    = final directory path
  1899.            name$    = chosen filename.
  1900.            button   = 1 if 'OK'
  1901.                     = 0 if 'Cancel'
  1902.  
  1903.  
  1904. FSETDTA
  1905. Syntax:    ~FSETDTA(addr)
  1906. Action:    Sets the address of the DTA. (See also FGETDTA).
  1907.  
  1908.  
  1909. FSFIRST
  1910. Syntax:    FSFIRST(p$,attr)
  1911. Action:    Searches  for  the  first file on a  disk  to  fulfill  the 
  1912.            criteria specified in p$ (eg:  "C:\*.GFA").  If found,  the 
  1913.            filename and attributes are to be found in the DTA.
  1914.            The parameter 'attr' is the file atributes to search on.
  1915.  
  1916. FSNEXT
  1917. Syntax:    FSNEXT()
  1918. Action:    Search  for the next file which fulfills the conditions  of 
  1919.            FSFIRST.
  1920.            
  1921. Example:
  1922.            ~FSETDTA(BASEPAGE+128)
  1923.            e%=FSFIRST("\*.GFA",-1)           ! all bits set
  1924.            DO UNTIL e%
  1925.              IF BYTE{BASEPAGE+149} AND 16    !if its a folder
  1926.                PRINT "*";CHAR{BASEPAGE+158}  ! indicate by a star
  1927.              ELSE                            ! otherwise
  1928.                PRINT 'CHAR{BASEPAGE+158}     ! a space before
  1929.            '                                 ! the filename
  1930.              ENDIF
  1931.              e%=FSNEXT()                     ! continue search
  1932.            LOOP
  1933.   
  1934.  
  1935. FULLW
  1936. Syntax:    FULLW [#]n
  1937. Action:    Enlarges window 'n' to full screen size.
  1938.            'n' is the window number. If the window has not
  1939.            yet been opened, this takes place automatically.
  1940.  
  1941.  
  1942. FUNCTION
  1943.            The commands FUNCTION and ENDFUNC form a subroutine,  in  a 
  1944.            similar  manner to PROCEDURE.  The name of  the  subroutine 
  1945.            and,  optionally,  the  list of varaibles are  given  after 
  1946.            FUNCTION command. Calling the subroutine is done by the use 
  1947.            of  @  or FN and the function name followed by  a  list  of 
  1948.            parameters if necessary.
  1949.            If the command RETURN is met during program execution,  the 
  1950.            the value given after it or the value of the named variable 
  1951.            is  returned.  In a function,  RETURN can be  used  several 
  1952.            times, with IF or the like. A function cannot be terminated 
  1953.            without a RETURN command being before the ENDFUNC  command. 
  1954.            In a function name ending with the $ character the function 
  1955.            returns a string result.
  1956. Example:
  1957.            f1%=@fac_loop(15)
  1958.            PRINT "loop: fac(15) = ";f1%
  1959.            '
  1960.            FUNCTION fac_loop(f%)
  1961.             w=1
  1962.             FOR J%=1 TO f%
  1963.               MUL w,j%
  1964.             NEXT j%
  1965.             RETURN w
  1966.            ENDFUNC
  1967.  
  1968.  
  1969. GB         Address of the AES Parameter Block
  1970.            This  (unlike the other AES address blocks) cannot be  used 
  1971.            with index.
  1972.  
  1973.  
  1974. GCONTRL    Address of the AES control block.  With index  (GCONTRL(2)) 
  1975.            the elements can be accessed directly.
  1976.  
  1977.  
  1978. GDOS?      Returns  TRUE  (-1)  if GDOS is  resident  and   FALSE  (0) 
  1979.            otherwise.
  1980.  
  1981.  
  1982. GEMDOS
  1983. Syntax:    GEMDOS(n[,x,y])
  1984. Action:    To  call the GEMDOS routines.  The optional parameter  list 
  1985.            can be prefixed with W:  or L:  to denote word or  longword 
  1986.            parameters. (if non given, default is W:)
  1987.            
  1988. Example:
  1989.            DO UNTIL GEMDOS(17)
  1990.              ALERT 1,"Printer not ready",1,"retry|break",d%
  1991.            LOOP UNTIL d%=2
  1992.  
  1993.  
  1994. GEMSYS
  1995. Syntax:    GEMSYS n
  1996. Action:    Calls the AES routine 'n'. The parameters necessary for the 
  1997.            operation  of  the  routine must first  be  placed  in  the 
  1998.            appropriate AES parameter blocks.
  1999.  
  2000.  
  2001.  
  2002. GET
  2003. Syntax:    GET x1,y1,x2,y2,sections$
  2004. Action:    GET  puts  a section of the screen into a  string  variable 
  2005.            'section$'  (x1,y1 and x2,y2 are coordinates of  diagonally 
  2006.            opposite corners). See also PUT.
  2007.  
  2008.  
  2009. GET #
  2010. Syntax:    GET #n[,r]
  2011. Action:    Reads a record from a random access file.
  2012.            'n' is the channel number (1 to 99)
  2013.            'r' is number of the record to be read (1 to 65535)
  2014.            If 'r' is not given then the next record in the file
  2015.            will be read. (See also PUT #).
  2016.  
  2017.  
  2018. GETSIZE
  2019. Syntax:    bytes%=GETSIZE(x1,y1,x2,y2)
  2020. Action:    The  TT  does not have a constant screen  memory  of  32000 
  2021.            Bytes like  the ST. A screen could require much more memory 
  2022.            (153600  Bytes).  The commands GET and PUT are  limited  to 
  2023.            32000  Bytes and therefore  a function has been  introduced 
  2024.            to support the larger screen  resolutions that require more 
  2025.            than 32000 Bytes. 
  2026.            This  function will return the number of Bytes required  by 
  2027.            the   screen between the coordinates  x1,y1,x2,y2.  Several 
  2028.            GET  or PUT  commands could be used to address  the  entire 
  2029.            screen.
  2030.  
  2031.  
  2032. GINTIN     Address of the AES Integer input block.  (Can be used  with 
  2033.            index GINTIN(0)).
  2034.  
  2035. GINTOUT    Address of the AES Integer output block. (Can be used  with 
  2036.            index GINTOUT(0)).
  2037.  
  2038.  
  2039. GOSUB
  2040. Syntax:    GOSUB name [ (LIST OF EXPRESSIONS) ]
  2041. Action:    Branches to the procedure called 'name'.
  2042.            A procedure name can begin with a digit and contain
  2043.            letters, numbers, dots and the underline dash.
  2044.            '(list of expressions)' contains the values of any
  2045.            local variables to be passed to the procedure.
  2046.            When the interpreter comes across a GOSUB command,
  2047.            it branches to the procedure named in the gosub.
  2048.            It is possible to call further procedures whilst in
  2049.            a procedure. It is even possible to call the procedure
  2050.            one is in at the time (recursive call).
  2051.  
  2052.  
  2053. GOTO
  2054. Syntax:    GOTO label            
  2055. Action:    allows an unconditional jump to a label.
  2056.            'label' must end in a colon and can consist of letters,
  2057.            numbers, dots, dashes and can begin with a digit.
  2058.  
  2059.  
  2060. *** The following 10 functions form the Graphics library calls to  the 
  2061. AES.
  2062.  
  2063. GRAF_DRAGBOX
  2064. Syntax:    GRAF_DRAGBOX(iw,ih,ix,iy,rx,,ry,rw,rh[,last_ix,last_iy])
  2065. Action:    Allows  a rectangle to be moved about the screen  with  the 
  2066.            mouse.  Its  movement  is restricted to the interior  of  a 
  2067.            larger  specified rectangle.  This function should only  be 
  2068.            called  when  the left mouse button is  held  down,  as  it 
  2069.            terminates when the button is released.
  2070.            Returns 0 if an error occurs.
  2071.            INPUTS:
  2072.            iw,ih    width & height of the moving rectangle
  2073.            ix,iy    initial  coords  of  top  left  corner  of  moving 
  2074.                     rectangle
  2075.            rx,ry    coords of top left corner of limiting rectangle
  2076.            rw,rh    width & height of limiting rectangle
  2077.            OUTPUTS:
  2078.            last_ix  coords of top left corner of inside rectangle
  2079.            last_iy  when the function terminated.
  2080.  
  2081.  
  2082. GRAF_GROWBOX
  2083. Syntax:    GRAF_GROWBOX(sx,sy,sw,sh,dx,dy,dw,dh)
  2084. Action:    Draws an expanding rectangle.
  2085.            Returns 0 if error occurs.
  2086.            sx,sy    Initial coords of top left corner of rectangle
  2087.            sw,sh    Initial width & height of rectangle
  2088.            dx,dy    Final coords of top left corner
  2089.            dw,dh    Final width & height
  2090.  
  2091. GRAF_HANDLE
  2092. Syntax:    GRAF_HANDLE(char_w,char_h,box_w,box_h)
  2093. Action:    Returns  the ID number of the current VDI  workstation  and 
  2094.            supplies the size of a character from the system set.
  2095.            OUTPUTS:
  2096.            char_w   width in pixels of a character
  2097.            char_h   height
  2098.            box_w    width of a character cell
  2099.            box_h    height
  2100.  
  2101.  
  2102. GRAF_MKSTATE
  2103. Syntax:    GRAF_MKSTATE(mx,my,m_state,k_state)
  2104. Action:    This  function supplies the current mouse  coordinates  and 
  2105.            status of tht mouse buttons and shift keys.
  2106.            Returns a reserved value (always 1)
  2107.            OUTPUTS:
  2108.            mx,my    mouse coordinates
  2109.            m_state  mouse button status
  2110.                     bit 0 left button
  2111.                     bit 1 right button
  2112.            k_state  see k_state in function EVNT_BUTTON
  2113.  
  2114.  
  2115. GRAF_MOUSE
  2116. Syntax:    GRAF_MOUSE(m_form,pattern_adr)
  2117. Action:    This  function  allows  the  mouse  shape  to  be  changed. 
  2118.            (similar command to DEFMOUSE)
  2119.            Returns 0 if an error occurs.
  2120.            m_form   number of the mouse pointer shape
  2121.                0    = Arrow
  2122.                1    = Double curly brackets
  2123.                2    = Busy bee
  2124.                3    = Pointing finger
  2125.                4    = Open hand
  2126.                5    = Thin cross hairs
  2127.                6    = Thick cross hairs
  2128.                7    = Outlined cross hairs
  2129.                255  = User defined
  2130.                256  = Hide mouse
  2131.                257  = Show mouse
  2132.  
  2133.            pattern_adr = address of bit information defining the mouse 
  2134.                          pointer. 37 word-sized values as follows:
  2135.                     1 =  x coordinate of the action point
  2136.                     2 =  y     "      "   "    "      "
  2137.                     3 =  number of colour levels, always 1
  2138.                     4 =  mask colour, always 0
  2139.                     5 =  pointer colour, always 1
  2140.               6 to 21 =  Mask definition (16 words ie.16x16 bits)
  2141.              22 to 37 =  Pointer def              "
  2142.  
  2143.  
  2144. GRAF_MOVEBOX
  2145. Syntax:    GRAF_MOVEBOX(w,h,sx,sy,dx,dy)
  2146. Action:    Draws a moving rectangle with constant width & height.
  2147.            Returns 0 on error.
  2148.            INPUTS:
  2149.            w,h      width & height of rectangle
  2150.            sx,sy    Initial coords of top left corner of rectangle
  2151.            dx,dy    Final coords of top left corner
  2152.  
  2153.  
  2154. GRAF_RUBBERBOX
  2155. Syntax:    GRAF_RUBBERBOX(tx,ty,min_w,min_h[,last_w,last_h])
  2156. Action:    This function draws an outline of a rectangle while the the 
  2157.            left  mouse  button is held down.  The top left  corner  is 
  2158.            fixed,  but the width & height of the rectangle change with 
  2159.            the  position of the mouse.  This function should  only  be 
  2160.            called  when  the left mouse button is  held  down,  as  it 
  2161.            terminates when the button is released.
  2162.            Returns 0 if an error occurs.
  2163.            INPUTS:
  2164.            tx,ty         coords of top left corner
  2165.            min_w,min_h   minimum width & height of rectangle
  2166.            OUTPUTS:
  2167.            last_w        width of rectangle when function terminates
  2168.            last_h        height "     "       "     "          "
  2169.  
  2170.  
  2171. GRAF_SHRINKBOX
  2172. Syntax:    GRAF_SHRINKBOX(sx,sy,sw,sh,dx,dy,dw,dh)
  2173. Action:    Draws an shrinking rectangle.
  2174.            Returns 0 if error occurs.
  2175.            sx,sy    Final coords of top left corner
  2176.            sw,sh    Final width & height
  2177.            dx,dy    Initial coords of top left corner of rectangle
  2178.            dw,dh    Initial width & height of rectangle
  2179.  
  2180.  
  2181.  
  2182. GRAF_SLIDEBOX
  2183. Syntax:    GRAF_SLIDEBOX(tree,parent_obj,slider_obj,flag)
  2184. Action:    This function (really belongs to the OBJECT library)  moves 
  2185.            one rectangular object within another,  in a similar manner 
  2186.            to GRAF_DRAGBOX. The object can only be moved vertically or 
  2187.            horizontally, and must be a 'child' of the limiting object. 
  2188.            This  function  should only be called when the  left  mouse 
  2189.            button  is held down,  as it terminates when the button  is 
  2190.            released.  Commonly  used  in movement of  slider  bars  in 
  2191.            windows.
  2192.            Returns  the position of the moving rectangle  relative  to 
  2193.            the limiting one:
  2194.            Horizontally: 0 = far left    1000 = far right
  2195.            Vertically:   0 = top         1000 = bottom
  2196.            INPUTS:
  2197.            tree          address of oobject tree
  2198.            parent_obj    object number of the 'limiting rectangle'
  2199.            slider_obj       "     "    "   "   moving rectangle
  2200.            flag          direction (0=horizontal, 1=vertical)
  2201.      
  2202.  
  2203.  
  2204. GRAF_WATCHBOX
  2205. Syntax:    GRAF_WATCHBOX(tree,obj,in_state,out_state)
  2206. Action:    This  function  (really  belongs  to  the  OBJECT  library) 
  2207.            monitors  an object tree while a mouse button  is  pressed, 
  2208.            checking  whether the mouse pointer is inside  or  outside. 
  2209.            When the mouse button is released, the status of the object 
  2210.            takes one of two specified values (normal selected/normal), 
  2211.            depending  on whether the pointer was inside the object  or 
  2212.            outside.
  2213.            Returns  1 if the mouse pointer was inside the object  when 
  2214.            the button was released, or 0 if it was outside.
  2215.            INPUTS:
  2216.            tree       address of the tree
  2217.            obj        number of the object to be monitored
  2218.            in_state   Status (OB_STATE) to be given to the  object  if 
  2219.                       the mouse pointer is found within it.
  2220.            out_state  Status (OB_STATE) to be given to the  object  if 
  2221.                       the mouse pointer is found outside it.
  2222.  
  2223.  
  2224. GRAPHMODE
  2225. Syntax:    GRAPHMODE n
  2226. Action:    Sets the graphic mode 1 to 4.
  2227.            1=replace     2=transparent
  2228.            3=xor         4=reverse transparent
  2229.  
  2230.  
  2231. HARDCOPY
  2232. Syntax:    HARDCOPY
  2233. Action:    Prints the screen (same as pressing <ALT> & <HELP>).
  2234.  
  2235.  
  2236. HEX$
  2237. Syntax:    HEX$(x[,y])
  2238. Action:    Changes the value of 'x' into a string expression
  2239.            which contains the value of 'x' in hexadecimal form.
  2240.            The optional parameter y specifies the number of  character 
  2241.            positions (1 to 8) to be used.
  2242.  
  2243.  
  2244. HIDEM
  2245. Syntax:    HIDEM
  2246. Action:    Switches off the mouse pointer. (see also SHOWM).
  2247.  
  2248.  
  2249. HIMEM
  2250. Syntax:    HIMEM
  2251. Action:    Returns the address of the area of memory which is  not
  2252.            required by GFA Basic.   Normally  16384  bytes  below  the 
  2253.            screen.
  2254.  
  2255.  
  2256. HLINE
  2257. Syntax:    HLINE x1,y,x2,f,m,addr,num_pattern
  2258. Action:    Similar to ALINE,  but only horizontal lines can be  drawn. 
  2259.            x1  and x2 contain the x coordinates of the line start  and 
  2260.            end points and y the common y coordinate.  f is the  colour 
  2261.            (0-15).  m  is the graphic mode.  addr is the address of  a 
  2262.            block of memory which contains bit information for  several 
  2263.            line  styles  each of 16 bits.  Which style is used  for  a 
  2264.            given  line  depends  on  both the  y  coordinate  and  the 
  2265.            parameter  num_pattern.  They  are ANDed together  and  the 
  2266.            resulting number used as an index to the style table.
  2267.  
  2268.  
  2269. HTAB       Positions  the cursor to the  specified  column.  (Counting 
  2270.            from 0). See also VTAB
  2271.  
  2272.  
  2273. IF
  2274. Syntax:    IF condition [ THEN ]
  2275.              program block
  2276.            ELSE
  2277.              program block
  2278.            ENDIF
  2279. Action:    Divides a program up into different blocks depending
  2280.            on how it relates to the 'condition'.
  2281.  
  2282. ELSE IF condition
  2283.            Enables  nested  IF's  to be more clearly  expressed  in  a 
  2284.            program.
  2285.  
  2286. Example:   'the following code has no ELSE IF's
  2287.            DO
  2288.              t$=CHR$(INP(2))
  2289.              IF t$="l"
  2290.                PRINT "Load text"
  2291.              ELSE
  2292.                IF t$="s"
  2293.                  PRINT "Save text"
  2294.                ELSE
  2295.                  IF t$="e"
  2296.                    PRINT "Enter text"
  2297.                  ELSE
  2298.                     PRINT "unknown command"
  2299.                  ENDIF
  2300.                ENDIF
  2301.              ENDIF
  2302.            LOOP
  2303.            
  2304.            The use of ELSE IF produces shorter code:
  2305.  
  2306.            DO
  2307.              t$=CHR$(INP(2))
  2308.              IF t$="l"
  2309.                  PRINT "Load text"
  2310.              ELSE IF t$="s"
  2311.                  PRINT "Save text"
  2312.              ELSE IF t$="e"
  2313.                  PRINT "Enter text"
  2314.              ELSE 
  2315.                  PRINT "unknown command"
  2316.              ENDIF
  2317.            LOOP
  2318.  
  2319.  
  2320. IMP
  2321. Syntax:    x IMP y
  2322. Action:    The  operator  IMP (implication) corresponds to  a  logical 
  2323.            consequence.   The   result  is  only  FALSE  if  a   FALSE 
  2324.            expression follows a TRUE one. The sequence of the argument 
  2325.            is important.
  2326.  
  2327. IMP()
  2328. Syntax:    IMP(x,y)
  2329. Action:    This  function resets a bit if the appropriate bit in x  is 
  2330.            set and y is reset, otherwise the bit is set.
  2331.  
  2332.  
  2333.  
  2334. INC
  2335. Syntax:    INC var
  2336. Action:    Increases the value of 'var' by 1. the same as
  2337.            var=var+1 but executes aprox 3.5 times faster
  2338.  
  2339.  
  2340.  
  2341. INFOW
  2342. Syntax:    INFOW n,"string$"
  2343. Action:    Allocates the (NEW) information line to the window with the
  2344.            number 'n'.If the string is empty then the line is removed
  2345.            altogether. As the info line cannot be switched off and on
  2346.            when the window is opened, infow has to be used in
  2347.            front of OPENW when an information line is required.
  2348.            If the command INFOW,n,"" is used ("" = null string)
  2349.            before OPENW then the window will have no info line.
  2350.  
  2351.  
  2352. INKEY$
  2353. Syntax:    INKEY$
  2354. Action:    Reads a character from the keyboard.
  2355.            This function returns a string which is 2, 1 or 0
  2356.            characters long.
  2357.            Normal keys, return the ASCII code.
  2358.            Function keys, HELP, UNDO etc. return two characters:
  2359.            The ASCII code zero and then the key code.
  2360.  
  2361. Example:
  2362.            DO
  2363.                t$=INKEY$
  2364.                IF t$<>""
  2365.                    IF LEN(t$)=1
  2366.                       PRINT "Character: ";t$,"ASCII code:";ASC(t$)
  2367.                    ELSE
  2368.                       PRINT "CHR$(0)+Scan code ";CVI(t$)
  2369.                    ENDIF
  2370.                ENDIF
  2371.            LOOP
  2372.  
  2373.  
  2374. INLINE
  2375. Syntax:    INLINE var,length
  2376. Action:    Reserves an area of memory within a program.
  2377.            var is any integer variable
  2378.            length is how much memory to reserve, less than 32700 bytes
  2379.            The  reserved area always starts at an even address and  is 
  2380.            initially filled with zeros.  When implementing INLINE this 
  2381.            address  is written to the integer variable adr.  When  the 
  2382.            program is loaded or saved, the reserved area is also.
  2383.  
  2384.            Placing  the  cursor  on the line  containing  the  command 
  2385.            INLINE  and  pressing  the HELP key causes a  new  menu  to 
  2386.            appear with the entries: LOAD SAVE DUMP CLEAR. Load is used 
  2387.            to  load a machine code program or data into  the  reserved 
  2388.            area,  save  saves  the  reserved  area  to  disk  (default 
  2389.            filename extension .INL).  DUMP printsout the reserved area 
  2390.            in hex to the printer and CLEAR clears the araea of memory.
  2391.  
  2392. INP    INP&(#)   INP%(#)
  2393. OUT    OUT&      OUT%
  2394. Syntax:    INP(#n)
  2395.            OUT #n,a[,b,c...]
  2396. Action:    Reads one byte from a file previously opened with OPEN.
  2397.            Similarly  OUT#n  sends a byte to  a  file.  The  numerical 
  2398.            expression n is the channel number under which the  channel 
  2399.            was opened.
  2400.            INP  and  OUT without the # can be used  for  communicating 
  2401.            with the screen,  keyboard etc. eg INP(2) takes a character 
  2402.            from the keyboard.
  2403.            These  functions cater for 16 and 32 bit input and  output. 
  2404.            
  2405. Example:   a%=CVL(INPUT$(4,#1)) is replaced by a%=INP%(#1)
  2406.  
  2407.  
  2408. INP(n)
  2409. INP?(n)
  2410. OUT[#]n,a[,b..]
  2411. OUT?(n)
  2412.  
  2413. INP        reads  a  byte  from a  peripheral  device.  The  numerical 
  2414.            expression  n can accept values 0-5 (see table  below),  or 
  2415.            contains a channel number(#n). The command OUT sends a byte 
  2416.            to a peripheral device. You can send several bytes with one 
  2417.            OUT command.  
  2418.            INP?  and  OUT?  determine the input or output status of  a 
  2419.            device. TRUE(-1) is device is ready ortherwise FALSE(0).
  2420.            n        Device
  2421.            0   LST: (list)             Printer
  2422.            1   AUX: (Auxiliary)        RS232
  2423.            2   CON: (Console)          Keyboard/screen
  2424.            3   MID: (MIDI)             MIDI Interface
  2425.            4   IKB: (Intelligent kbd)  Keyboard processor 
  2426.            5   VID: (Video)            Screen
  2427.  
  2428.  
  2429. INPAUX$
  2430. INPMID$
  2431.            Using these two commands,  data can be read from the serial 
  2432.            and MIDI interfaces.
  2433. Example:
  2434.            DO
  2435.              PRINT INPAUX$;
  2436.            LOOP
  2437.  
  2438.  
  2439.  
  2440. INPUT
  2441. Syntax:    INPUT ["text",]x{,y,...]
  2442.            INPUT ["text";]x[,y,...]
  2443. Action:    Allows entry of data during program execution.
  2444.            If "text" is given, then a string prompt is displayed.
  2445. Example:
  2446.            INPUT a$
  2447.            INPUT "",b$
  2448.            INPUT "enter two numbers: ";x,y
  2449.  
  2450.  
  2451. INPUT$
  2452. Syntax:    INPUT$(count[,#n]))
  2453. Action:    Reads 'count' characters from the keyboard and assigns them 
  2454.            to  a  string.  Optionally,  if  the channel  number  n  is 
  2455.            specified,  the  characters are read in from  a  previously 
  2456.            OPENed channel.
  2457.  
  2458.  
  2459. INPUT #n,var1[,var2,var3,...]
  2460. LINE INPUT #n,a1$[,a2$,a3$,...]
  2461.            
  2462.            These  commands  make  it  possible to  take  data  from  a 
  2463.            previously OPENed device.  Individual variables or variable 
  2464.            lists  (where  the  vars are separated by  commas)  can  be 
  2465.            input.
  2466.  
  2467.  
  2468. INSERT
  2469. Syntax:    INSERT x(i)=y
  2470. Action:    Inserts  an  element  into  an  array.  The  value  of  the 
  2471.            expression  y  is  inserted into  the  position  x(i).  All 
  2472.            elements of the array are shifted up by one  position,  and 
  2473.            the last element lost. See also DELETE.
  2474.  
  2475.  
  2476.  
  2477. INSTR
  2478. Syntax:    INSTR([n,]a$,b$)      OR       INSTR(a$,b$[,n])
  2479. Action:    Searches to see if b$ is present in a$ and returns
  2480.            its position.
  2481.            'n' is a numeric expression indicating the position in a$
  2482.            at which the search is to begin.  If 'n' is not given 
  2483.            the search begins at the first character of A$.
  2484.            If b$ is found in a$ the start position is returned.
  2485.       
  2486.  
  2487.  
  2488. INT
  2489. Syntax:    INT(x)
  2490. Action:    Determines the largest integer that is less than or
  2491.            equal to 'x'.
  2492.  
  2493.  
  2494.  
  2495. INTIN      Address  of the VDI integer input block.  Also works  with 
  2496.            index INTIN(2).
  2497.  
  2498. INTOUT     Address  of the VDI integer output block.  Also works  with 
  2499.            index INTOUT(2).
  2500.  
  2501.  
  2502.  
  2503. INT{x}     Reads/writes a 2 byte signed integer from/to address x.
  2504.            (See also BYTE{},  CARD{},  LONG{},  {}, FLOAT{}, SINGLE{}, 
  2505.            DOUBLE{}, CHAR{} ).
  2506.  
  2507.  
  2508. KEYDEF
  2509. Syntax:    KEYDEF n,s$
  2510. Action:    Assign a string to a Function Key.  The number n (1-20)  is 
  2511.            the  function  key (for 11 and above use shift  +  function 
  2512.            key).  The  string is any string.  Whilst using  the  Basic 
  2513.            Editor,   you  must  also  hold  down  the  Alternate  key, 
  2514.            otherwise the normal menu commands would not work!
  2515.  
  2516.  
  2517.  
  2518. KEYGET n
  2519. KEYLOOK n
  2520. KEYTEST n
  2521.  
  2522.            KEYTEST is simialr to INKEY$ and reads a character from the 
  2523.            keyboard. If no key was pressed since the last input (apart 
  2524.            from Alternate,  Control, Shift and Caps Lock) the returned 
  2525.            value is zero,  otherwise its value corresponds to the  key 
  2526.            in the fashion shown below for KEYGET.
  2527.  
  2528.            KEYGET  waits  for a key to be pressed and then  returns  a 
  2529.            long word value corresponding to the key.  This 32 bit word 
  2530.            is constructed as follows:
  2531.            Bits 0-8    the ASCII code
  2532.            Bits 8-15   Zero
  2533.            Bits 16-23  the scan code
  2534.            Bits 24-31  status of Shift,  Control, Alternate, Caps lock 
  2535.            as follows:           
  2536.            Bit  Key
  2537.            24   Right shift
  2538.            25   Left shift
  2539.            26   Control
  2540.            27   Alternate
  2541.            28   Caps Lock
  2542.  
  2543.            KEYLOOK  allows  a character to be read from  the  keyboard 
  2544.            buffer,  without  changing the buffer's contents,  as  with 
  2545.            KEYGET or INKEY$.
  2546.  
  2547.  
  2548. KEYPAD n   Sets  the  usage of the  numerical  keypad.  The  numerical 
  2549.            expression n is evaluated bit by bit and has the  following 
  2550.            meaning:
  2551.            Bit Meaning             0              1
  2552.            0   NUMLOCK             On             Off
  2553.            1   NUMLOCK             Not Switchable Switchable
  2554.            2   CTRL-KEYPAD         Normal         Cursor
  2555.            3   ALT_KEYPAD          Normal         ASCII
  2556.            4   KEYDEF without ALT  Off            On
  2557.            5   KEYDEF with ALT     Off            On
  2558.            
  2559.            With  bit 0 set the keypad will act as a 'PC'  keypad  with 
  2560.            numlock off ie. it responds with cursor movements.
  2561.  
  2562.            With  bit 1 set the 'PC' numlock mode can be  toggled  with 
  2563.            Alternate and '-', otherwise it can't.
  2564.  
  2565.            With  bit 2 set,  numlock is effecively switched off  while 
  2566.            the  Control  key  is held down.  Thus  Control-4  (on  the 
  2567.            keypad) produces cursor movements.
  2568.  
  2569.            With bit 3 set ASCII values for characters can be typed  in 
  2570.            with the Alternate key held down.  When ALT is released the 
  2571.            character appears.
  2572.  
  2573.            With bit 4 set,  the character strings assigned with KEYDEF 
  2574.            to  the function keys are output when the key  is  pressed. 
  2575.            With bit 5 set, the Alternate key must aslo be held down.
  2576.  
  2577.            The deafult when the ST is turned on is KEYPAD 0.  with GFA 
  2578.            Basic in operation it is 46.
  2579.  
  2580.            
  2581.  
  2582. KEYPRESS n
  2583.            This  simulates the pressing of a key.  The character  with 
  2584.            the  ASCII  code contained in the lowest 8 bits of  'n'  is 
  2585.            added  to the keyboard buffer.  Additionally the status  of 
  2586.            the Shift,  Control and Alternate keys may be passed in the 
  2587.            high  order bits as defined in KEYGET.  If the  ASCII  code 
  2588.            given is zero, a scan code may be passed in bits 16-23.
  2589. Example: 
  2590.            KEYPRESS &H3B0000 presses F1.
  2591.            
  2592. Example:
  2593.            FOR i&=65 TO 90                   ! Simulates the pressing
  2594.              KEYPRESS i&                     ! of keys A-Z
  2595.            NEXT i&
  2596.            KEYPRESS 13                       !followed by Carriage Ret
  2597.            INPUT a$                          !Characters are taken up
  2598.            '                                 !to  the first CR.
  2599.            PRINT a$
  2600.  
  2601.  
  2602.  
  2603. KILL
  2604. Syntax:    KILL "filespec"
  2605. Action:    Deletes a file off disk (only one at a time).
  2606.  
  2607.  
  2608.  
  2609. L:         Enable  the passing of numerical expressions  to  Operating 
  2610.            system functions or to machine code routines.  L: is a long 
  2611.            word.
  2612.            
  2613. Example:   ~XBIOS(5,L:log_base%,L:phys_base%,-1)
  2614.  
  2615.  
  2616. LEFT$
  2617. Syntax:    LEFT$(a$[,x])
  2618. Action:    Returns the first [or first 'x'] character[s] of a string.
  2619.  
  2620.  
  2621.  
  2622. LEN
  2623. Syntax:    LEN(x$)
  2624. Action:    Returns the length of a string.
  2625.  
  2626.  
  2627.  
  2628. LET
  2629. Syntax:    [LET] var=expression
  2630. Action:    Assigns a variable with the value of an expression.
  2631.  
  2632.  
  2633.  
  2634. LINE
  2635. Syntax:    LINE x,y,xx,yy
  2636. Action:    Connects two points ('x,y' & 'xx,yy') with a straight
  2637.            line, and is identical to DRAW x,y TO xx,yy.
  2638.  
  2639.  
  2640.  
  2641. LINE INPUT
  2642. Syntax:    LINE INPUT ["text",]var$ [,var$... ]
  2643.            LINE INPUT ["text";]var$ [,var$... ]
  2644. Action:    Makes it possible to enter a string during program
  2645.            execution.
  2646.            This command is the same as INPUT except that a comma
  2647.            is taken as part of the entered string and not as a
  2648.            separator. Only <RETURN> is regarded as a separator.
  2649.  
  2650. LINE INPUT#  See INPUT#
  2651.  
  2652.  
  2653.  
  2654. LIST
  2655. Syntax:    LIST "filename"
  2656. Action:    stores the program currently in memory to disk in ASCII 
  2657.            format. If the 'filename' is an empty string (eg. "") then 
  2658.            the listing is shown on the screen.
  2659.            In all other cases this command is the same as the editor 
  2660.            menu option SAVE,A.            
  2661.            Programs to be joined together using the command MERGE
  2662.            must be saved using LIST (or SAVE,A from the menu bar)
  2663.  
  2664.  
  2665. LLIST
  2666. Syntax:    LLIST
  2667. Action:    Prints out the listing of the current program.  The setting 
  2668.            for the type of output is controlled by the '.' commands in 
  2669.            the editor.
  2670.  
  2671.  
  2672.  
  2673.  
  2674. LOAD
  2675. Syntax:    LOAD "filespec"
  2676. Action:    Loads a program into memory.
  2677.  
  2678.  
  2679.  
  2680. LOC
  2681. Syntax:    LOC(#n)
  2682. Action:    Returns the location of the file pointer for the file with 
  2683.            the channel number 'n'
  2684.            The location is given in number of bytes from the start of 
  2685.            the file.
  2686.  
  2687.  
  2688.  
  2689. LOCAL
  2690. Syntax:    LOCAL var [ ,var.... ]
  2691. Action:    Declares 'var' to be a local variable.
  2692.            
  2693.  
  2694.  
  2695. LOCATE
  2696. Syntax:    LOCATE row,column
  2697. Action:    Positions the cursor to the specified location.
  2698.  
  2699.  
  2700.  
  2701. LOF
  2702. Syntax:    LOF(#n)
  2703. Action:    Returns length of file OPENed for channel number 'n'.
  2704.  
  2705.  
  2706.  
  2707. LOG  LOG10
  2708. Syntax:    LOG(x)
  2709.            LOG10(x)
  2710. Action:    Determines the natural logarithm (log) or the logarithm
  2711.            base 10 (log10) of 'x'.
  2712.  
  2713.  
  2714.  
  2715. LONG{x}    Reads/writes a 4 byte integer from/to address x.
  2716. or         (See  also  BYTE{},   CARD{},   INT{},  FLOAT{},  SINGLE{}, 
  2717. {x}        DOUBLE{}, CHAR{} ).
  2718.  
  2719.  
  2720. LOOP       See DO
  2721.  
  2722. LOOP UNTIL condition
  2723. LOOP WHILE condition
  2724.            The  commands DO and LOOP can be extended using  UNTIL  and 
  2725.            WHILE. LOOP WHILE causes the program to jump back to the DO 
  2726.            command  as  long  as the condition  is  true.  LOOP  UNTIL 
  2727.            requires the condition to be false to cause the loop back.
  2728.  
  2729.  
  2730.  
  2731. LPEEK(x)   Reads a 4 byte integer from address x. (In supervisor mode)
  2732.  
  2733.  
  2734. LPENX      For the STE. Returns the x coordinate of a light pen.
  2735. LPENY      For the STE. Returns the y coordinate of a light pen.
  2736.  
  2737.  
  2738.  
  2739. LPOKE n,x  Writes a 4 byte ineger 'x' to address n.  Not in supervisor 
  2740.            mode. (Add an 'S' to do in super mode ie. SLPOKE n,x).
  2741.  
  2742.  
  2743.  
  2744. LPOS
  2745. Syntax:    LPOS(n)
  2746. Action:    Returns the column in which the printer head (in the printer 
  2747.            buffer) is located.
  2748.  
  2749.  
  2750. LPRINT
  2751. Syntax:    LPRINT [expressions [,][;][']] 
  2752. Action:    prints data on the printer.
  2753.            'expression' is any number of expressions separated by 
  2754.            commas or semicolons or apostrophes. If none of these is 
  2755.            given a semicolon is assumed.
  2756.  
  2757.  
  2758. LSET
  2759. Syntax:    LSET var=string
  2760. Action:    Puts the 'string' in the string variable 'var'    justified
  2761.            to the left.
  2762.  
  2763.  
  2764. L~A        Returns the base address of the LINE-A variables.
  2765.  
  2766. MALLOC(x)  Allocates an area of memory.  (GEMDOS 72) If x is -1,  then 
  2767.            the  function  returns the largest contiguous  free  memory 
  2768.            block.  If x is positive, then MALLOC reserves that area of 
  2769.            memory and returns its base address.  If 0 is returned then 
  2770.            there was a fault with the allocation.
  2771.            See also RESERVE, MFREE, MSHRINK.
  2772.  
  2773.  
  2774. The following 33 commands are for the handling of MATRIXES
  2775.  
  2776.  
  2777. MAT ADD
  2778. MAT ADD a(),b()
  2779. MAT ADD a(),x
  2780. MAT ADD a()=b()+c()
  2781. MAT BASE
  2782. MAT CLR a()
  2783. MAT CPY
  2784. MAT CPY a([i,j])=b([k,l])[,h,w]
  2785. MAT DET x=a([i,j])[,n]
  2786. MAT INPUT #i,a()
  2787. MAT INV a()=b()
  2788. MAT MUL
  2789. MAT MUL a(),x
  2790. MAT MUL a()=b()*c()
  2791. MAT MUL x=a()*b()
  2792. MAT MUL x=a()*b()*c()
  2793. MAT NORM a(),0
  2794. MAT NORM a(),1
  2795. MAT ONE a()
  2796. MAT PRINT
  2797. MAT PRINT [#i]a[,g,n]
  2798. MAT QDET x=a([i,j])[,n]
  2799. MAT RANG x=a([i,j])[,n]
  2800. MAT READ
  2801. MAT READ a()
  2802. MAT SET a()=x
  2803. MAT SUB
  2804. MAT SUB a(),b()
  2805. MAT SUB a(),x
  2806. MAT SUB a()=b()-c()
  2807. MAT TRANS a()[=b()]
  2808. MAT XCPY
  2809. MAT XCPY a([i,j])=b([k,l])[,h,w]
  2810.  
  2811. Linear operations with vectors and matrices.
  2812. All THE  MAT   functions described relate only to one and/or two-
  2813. dimensional fields with floating point variables.
  2814.  
  2815. System commands
  2816.  
  2817. MAT BASE 0
  2818. MAT BASE 1
  2819.  
  2820. The MAT BASE command can only sensibly be used when OPTION BASE 0 
  2821. has been activated.  In this case,  MAT BASE 1 can be used to set 
  2822. the offset for the start of the row and column indexing of one or 
  2823. two-dimensional fields with floating point variables to 1 for the 
  2824. matrix operations. MAT BASE 0 resets this offset to 0 after a MAT 
  2825. BASE 1.
  2826.  
  2827. The setting made with MAT BASE n affects the following commands
  2828.  
  2829. MAT READ
  2830. MAT PRINT
  2831. MAT CPY
  2832. MAT XCPY
  2833. MAT ADD
  2834. MAT SUB 
  2835. MAT MUL
  2836.  
  2837. The default is MAT BASE 1.
  2838.  
  2839. Generating commands
  2840.  
  2841. MAT CLR a()
  2842. MAT SET a()=x
  2843. MAT ONE a()
  2844.  
  2845. a: Name of field with numeric variables
  2846. x: aexp
  2847.  
  2848. MAT CLR a() corresponds to an ARRAYFILL a(),0,  i.e.  the command 
  2849. sets all elements in the field (matrix or vector) a() to a  value 
  2850. of 0.
  2851.  
  2852. MAT SET a()=x corresponds to an ARRAYFILL a(),x, i.e. the command 
  2853. sets  all  elements in the field a() (matrix or  vector)  to  the 
  2854. value x.
  2855.  
  2856.  
  2857. MAT ONE a() generates from a square matrix a() a uniform  matrix, 
  2858. i.e.  a square matrix in which elements  a(1,1),a(2,2),...,a(n.n) 
  2859. are all equally 1 and all other elements equally 0.
  2860.  
  2861. Write and Read commands
  2862.  
  2863. MAT READ a()
  2864. MAT PRINT [#i]a[,g,n]
  2865. MAT INPUT #i,a()
  2866.  
  2867. i,g,n:  iexp
  2868. a:      Name of field with numerical variables
  2869.  
  2870. MAT READ a() reads a previously dimensioned matrix or vector from 
  2871. DATA rows.
  2872.  
  2873. MAT  PRINT [#i,]a()[,g,n] outputs a matrix or a  vector.  Vectors 
  2874. are  output on one row,  the elements being separated by  commas. 
  2875. With matrix, each row is followed by a rowfeed.
  2876.  
  2877. The output can optionally be redirected with #i, as with PRINT.
  2878.  
  2879. If  g  and n are specified,  the numbers are  formatted  as  with 
  2880. STR$(x,g,n).
  2881.  
  2882.  
  2883. MAT  INPUT #1,a() reads a matrix or vector from a file  in  ASCII 
  2884. format  (the format being the reverse of MAT  PRINT,  commas  and 
  2885. rowfeeds may be varied as with INPUT #).
  2886.  
  2887. Copy and Transposition commands
  2888.  
  2889. MAT CPY a([i,j])=b([k,l])[,h,w]
  2890. MAT XCPY a([i,j])=b([k,l])[,h,w]
  2891. MAT TRANS a()[=b()]
  2892.  
  2893. a,b:    Name of fields with numerical variables
  2894. i,j,k,l,h,w:    iexp
  2895.  
  2896. MAT  CPY  a([i,j])=b([k,l])[,h,w] copies h rows with  w  elements 
  2897. each  from  matrix  b to the row and column offset  of  matrix  a 
  2898. defined by i,j, starting from the row and column offset of matrix 
  2899. b defined by l,k.
  2900.  
  2901.  
  2902. Special cases
  2903.  
  2904. MAT  COPY a()=b() copies the complete matrix b into matrix  a  if 
  2905. the matrix are of the same order.
  2906.  
  2907. Only those elements are copied in this process for which  identi-
  2908. cal  indices  are given in both the source  and  the  destination 
  2909. matrix.
  2910.  
  2911.  
  2912. MAT  COPY a(i,j)=b() copies matrix b,  starting from the row  and 
  2913. column offset defined by MAT BASE,  to the row and column  offset 
  2914. of  matrix a defined by i,j.  Only those elements are copied  for 
  2915. which  identical  indices are given in both the  source  and  the 
  2916. destination matrix.
  2917.  
  2918.  
  2919. MAT  COPY a()=b(i,j) copies matrix b,  starting from the row  and 
  2920. column  offset defined by i,j,  to the offset of matrix a defined 
  2921. by MAT BASE.  Only those elements are copied for which  identical 
  2922. indices are given in both the source and the destination matrix.
  2923.  
  2924. MAT COPY a(i,j)=b(k,l) copies matrix b, starting from the row anumn offset  of  matrix  a 
  2925. defined by i,j, starting from the row and column offset of matrix 
  2926. b defined by l,k.
  2927.  
  2928.  
  2929. Special cases
  2930.  
  2931. MAT  COPY a()=b() copies the complete matrix b into matrix  a  if 
  2932. the matrix are of the same order.
  2933.  
  2934. Only those elements are copied in this process for which  identi-
  2935. cal  indices  are given in both the source  and  the  destination 
  2936. matrix.
  2937.  
  2938.  
  2939. MAT  COPY a(i,j)=b() copies matrix b,  starting from the row  and 
  2940. column offset defined by MAT BASE,  to the row and column  offset 
  2941. of  matrix a defined by i,j.  Only those elements are copied  for 
  2942. which  identical  indices are given in both the  source  and  the 
  2943. destination matrix.
  2944.  
  2945.  
  2946. MAT  COPY a()=b(i,j) copies matrix b,  starting from the row  and 
  2947. column  offset defined by i,j,  to the offset of matrix a defined 
  2948. by MAT BASE.  Only those elements are copied for which  identical 
  2949. indices are given in both the source and the destination matrix.
  2950.  
  2951. MAT COPY a(i,j)=b(k,l) copies matrix b, starting from the row and 
  2952. column offset defined by k,l, to the offset i,j of matrix a. Only 
  2953. those  elements are copied for which identical indices are  given 
  2954. in both the source and the destination matrix.
  2955.  
  2956.  
  2957. MAT  COPY  a()=b() copies h rows with w elements  each  from  the 
  2958. matrix b,  starting from the row and column offset defined by MAT 
  2959. BASE,  the row and column offset of matrix a defined by MAT BASE. 
  2960. Only  those elements are copied for which identical  indices  are 
  2961. given in both the source and the destination matrix.
  2962.  
  2963.  
  2964. MAT  XCPY  a([i,j])=b([k,l])[,h,w] works basically  in  the  same 
  2965. manner as MAT CPY a([i,j])=b([k,l])[,h,w],  except that matrix  b 
  2966. is being transposed while being copied to matrix a, i.e. the rows 
  2967. and columns of matrix b are swapped while it is copied to  matrix 
  2968. a.  Array b remains unchanged,  however.  Only those elements are 
  2969. copied  for which identical indices are given in both the  source 
  2970. and the destination matrix.
  2971.  
  2972.  
  2973. Further special cases
  2974.  
  2975. As with MAT CPY a(i,j)=b(k,l),w,h.
  2976.  
  2977. If  MAT CPY or MAT XCPY are applied to vectors,  j and l  may  be 
  2978. ignored.  Following a DIM a(n),b(m),  a() and b() are interpreted 
  2979. as row vectors, i.e. as matrix of the (1,n) or (1,m) types.
  2980.  
  2981. For  a  and  b to be treated as  column  vectors,  they  must  be 
  2982. dimensioned  as  matrix  of the (n,1)  or  (m,1)  type,  ie.  DIM 
  2983. a(n,1),b(n,1).
  2984.  
  2985. If  both  vectors are of the same order (both are row  or  column 
  2986. vectors),  MAT  CPY  must be used.  Irrespective of the  type  of 
  2987. vectors a and b, MAT CPY always treats both vectors syntactically 
  2988. as column vectors,  so that the correct syntax to be used for MAT 
  2989. CPY is always
  2990.  
  2991. MAT CPY a(n,1)=b(m,1)!
  2992. MAT CPY a(3,1)=b(1,1) ! interprets a() and b() as column vectors
  2993.  
  2994. For MAT XCPY,  one of the two vectors a and b must be  explicitly 
  2995. dimensioned as a row vector,  the other as a column  vector.
  2996.  
  2997. Since MAT XCPY first transposes the second vector before  copying 
  2998. it to the first.  For this reason,  MAT XCPY can only be used for 
  2999. DIM  a(1,n),b(m,1)d 
  3000. column offset defined by k,l, to the offset i,j of matrix a. Only 
  3001. those  elements are copied for which identical indices are  given 
  3002. in both the source and the destination matrix.
  3003.  
  3004.  
  3005. MAT  COPY  a()=b() copies h rows with w elements  each  from  the 
  3006. matrix b,  starting from the row and column offset defined by MAT 
  3007. BASE,  the row and column offset of matrix a defined by MAT BASE. 
  3008. Only  those elements are copied for which identical  indices  are 
  3009. given in both the source and the destination matrix.
  3010.  
  3011.  
  3012. MAT  XCPY  a([i,j])=b([k,l])[,h,w] works basically  in  the  same 
  3013. manner as MAT CPY a([i,j])=b([k,l])[,h,w],  except that matrix  b 
  3014. is being transposed while being copied to matrix a, i.e. the rows 
  3015. and columns of matrix b are swapped while it is copied to  matrix 
  3016. a.  Array b remains unchanged,  however.  Only those elements are 
  3017. copied  for which identical indices are given in both the  source 
  3018. and the destination matrix.
  3019.  
  3020.  
  3021. Further special cases
  3022.  
  3023. As with MAT CPY a(i,j)=b(k,l),w,h.
  3024.  
  3025. If  MAT CPY or MAT XCPY are applied to vectors,  j and l  may  be 
  3026. ignored.  Following a DIM a(n),b(m),  a() and b() are interpreted 
  3027. as row vectors, i.e. as matrix of the (1,n) or (1,m) types.
  3028.  
  3029. For  a  and  b to be treated as  column  vectors,  they  must  be 
  3030. dimensioned  as  matrix  of the (n,1)  or  (m,1)  type,  ie.  DIM 
  3031. a(n,1),b(n,1).
  3032.  
  3033. If  both  vectors are of the same order (both are row  or  column 
  3034. vectors),  MAT  CPY  must be used.  Irrespective of the  type  of 
  3035. vectors a and b, MAT CPY always treats both vectors syntactically 
  3036. as column vectors,  so that the correct syntax to be used for MAT 
  3037. CPY is always
  3038.  
  3039. MAT CPY a(n,1)=b(m,1)!
  3040. MAT CPY a(3,1)=b(1,1) ! interprets a() and b() as column vectors
  3041.  
  3042. For MAT XCPY,  one of the two vectors a and b must be  explicitly 
  3043. dimensioned as a row vector,  the other as a column  vector.
  3044.  
  3045. Since MAT XCPY first transposes the second vector before  copying 
  3046. it to the first.  For this reason,  MAT XCPY can only be used for 
  3047. DIM  a(1,n),b(m,1):  a()=row vector,  b()=column vector  and  DIM 
  3048. a(n,1),b(1,m): a()=column vector, b()=row vector.
  3049.  
  3050. Optionally,  the parameters h and w can also be used when copying 
  3051. vectors   with  MAT  CPY or  MAT  XCPY.  However,  the  following 
  3052. applies:  with MAT CPY, only the h parameter is used for w=>1. No 
  3053. copying takes place with w=0.
  3054.  
  3055. With MAT XCPY, only h is used for w=>1 if b is a column vector to 
  3056. be copied into a row vector after transposition. No copying takes 
  3057. place when w=0.  On the other hand,  only w is used for h=>1 if b 
  3058. is  a row vector which is to be copied to a column  vector  after 
  3059. transposition. In this case, no copying takes place if h=0.
  3060.  
  3061. MAT TRANS a()=b() copies the transposed from matrix b to matrix a 
  3062. if a and b are dimensioned accordingly,  i.e.  the number of rows 
  3063. from  a must correspond to the number of columns in  b,  and  the 
  3064. number of columns from a to the number of rows of n.
  3065.  
  3066. In the case of a square matrix,  i.e.  one with equal numbers  of 
  3067. rows and columns,  MA:  a()=row vector,  b()=column vector  and  DIM 
  3068. a(n,1),b(1,m): a()=column vector, b()=row vector.
  3069.  
  3070. Optionally,  the parameters h and w can also be used when copying 
  3071. vectors   with  MAT  CPY or  MAT  XCPY.  However,  the  following 
  3072. applies:  with MAT CPY, only the h parameter is used for w=>1. No 
  3073. copying takes place with w=0.
  3074.  
  3075. With MAT XCPY, only h is used for w=>1 if b is a column vector to 
  3076. be copied into a row vector after transposition. No copying takes 
  3077. place when w=0.  On the other hand,  only w is used for h=>1 if b 
  3078. is  a row vector which is to be copied to a column  vector  after 
  3079. transposition. In this case, no copying takes place if h=0.
  3080.  
  3081. MAT TRANS a()=b() copies the transposed from matrix b to matrix a 
  3082. if a and b are dimensioned accordingly,  i.e.  the number of rows 
  3083. from  a must correspond to the number of columns in  b,  and  the 
  3084. number of columns from a to the number of rows of n.
  3085.  
  3086. In the case of a square matrix,  i.e.  one with equal numbers  of 
  3087. rows and columns,  MAT TRANS a() may be used.  This command swaps 
  3088. the  rows  and  columns of matrix a and writes  the  matrix  thus 
  3089. changed back to a.
  3090.  
  3091. (The original matrix is lost in the process (but can be  restored 
  3092. with another MAT TRANS a()).
  3093.  
  3094. Operation commands
  3095.  
  3096. MAT ADD a()=b()+c()
  3097. MAT ADD a(),b()
  3098. MAT ADD a(),x
  3099.  
  3100. MAT SUB a()=b()-c()
  3101. MAT SUB a(),b()
  3102. MAT SUB a(),x
  3103.  
  3104. MAT MUL a()=b()*c()
  3105. MAT MUL x=a()*b()
  3106. MAT MUL x=a()*b()*c()
  3107. MAT MUL a(),x
  3108.  
  3109. MAT NORM a(),0
  3110. MAT NORM a(),1
  3111.  
  3112. MAT DET x=a([i,j])[,n]
  3113. MAT QDET x=a([i,j])[,n]
  3114. MAT RANG x=a([i,j])[,n]
  3115. MAT INV a()=b()
  3116.  
  3117. a,b,c: Names of numerical floating point fields
  3118. x:     aexp; scalar value
  3119. i.j,n: aexp
  3120.  
  3121. MAT  ADD a()=b()+c() is only defined for matrix (vectors) of  the 
  3122. same order,  e.g. DIM a(n,m),b(m,m),c(n,m) or DIM a(n),b(n),c(n). 
  3123. Array c is added to matrix b,  element by element, and the result 
  3124. is written to matrix a.
  3125.  
  3126. MAT ADD a(),b() is only defined for matrix (vectors) of the  same 
  3127. order,  e.g. DIM a(n,m),b(n.m) or DIM a(n),b(n). Array bT TRANS a() may be used.  This command swaps 
  3128. the  rows  and  columns of matrix a and writes  the  matrix  thus 
  3129. changed back to a.
  3130.  
  3131. (The original matrix is lost in the process (but can be  restored 
  3132. with another MAT TRANS a()).
  3133.  
  3134. Operation commands
  3135.  
  3136. MAT ADD a()=b()+c()
  3137. MAT ADD a(),b()
  3138. MAT ADD a(),x
  3139.  
  3140. MAT SUB a()=b()-c()
  3141. MAT SUB a(),b()
  3142. MAT SUB a(),x
  3143.  
  3144. MAT MUL a()=b()*c()
  3145. MAT MUL x=a()*b()
  3146. MAT MUL x=a()*b()*c()
  3147. MAT MUL a(),x
  3148.  
  3149. MAT NORM a(),0
  3150. MAT NORM a(),1
  3151.  
  3152. MAT DET x=a([i,j])[,n]
  3153. MAT QDET x=a([i,j])[,n]
  3154. MAT RANG x=a([i,j])[,n]
  3155. MAT INV a()=b()
  3156.  
  3157. a,b,c: Names of numerical floating point fields
  3158. x:     aexp; scalar value
  3159. i.j,n: aexp
  3160.  
  3161. MAT  ADD a()=b()+c() is only defined for matrix (vectors) of  the 
  3162. same order,  e.g. DIM a(n,m),b(m,m),c(n,m) or DIM a(n),b(n),c(n). 
  3163. Array c is added to matrix b,  element by element, and the result 
  3164. is written to matrix a.
  3165.  
  3166. MAT ADD a(),b() is only defined for matrix (vectors) of the  same 
  3167. order,  e.g. DIM a(n,m),b(n.m) or DIM a(n),b(n). Array b is added 
  3168. to  matrix a,  element by element,  and the result is written  to 
  3169. matrix a. The original matrix a is lost in the process.
  3170.  
  3171. MAT  ADD a(),x is defined for all  matrix  (vectors).  Here,  the 
  3172. scalar x is added to matrix a, element by element, and the result 
  3173. is  written  to matrix a.  The original matrix a is lost  in  the 
  3174. process.
  3175.  
  3176. MAT  SUB a()=b()+c() is only defined for matrix (vectors) of  the 
  3177. same order,  e.g. DIM a(n,m),b(n,m),c(n,m) or DIM a(n),b(n),c(n). 
  3178. Array c is subtracted from matrix b, element by element, and the
  3179. result is written to matrix a.
  3180.  
  3181. MAT SUB a(),b() is only defined for matrix (vectors) of the same
  3182. order,  e.g.  DIM  a(n,m),b(n,m)  or DIM a(n),b(n).  Array  b  is 
  3183. subtracted  from  matrix a,  element by element,  and  the  result 
  3184. written to matrix a. The original matrix a is lost in the process.
  3185.  
  3186. MAT  SUB a(),x is defined for all  matrix  (vectors).  Here,  the 
  3187. scalar x is subtracted from matrix x, element by element, and the 
  3188. result is written to mat is added 
  3189. to  matrix a,  element by element,  and the result is written  to 
  3190. matrix a. The original matrix a is lost in the process.
  3191.  
  3192. MAT  ADD a(),x is defined for all  matrix  (vectors).  Here,  the 
  3193. scalar x is added to matrix a, element by element, and the result 
  3194. is  written  to matrix a.  The original matrix a is lost  in  the 
  3195. process.
  3196.  
  3197. MAT  SUB a()=b()+c() is only defined for matrix (vectors) of  the 
  3198. same order,  e.g. DIM a(n,m),b(n,m),c(n,m) or DIM a(n),b(n),c(n). 
  3199. Array c is subtracted from matrix b, element by element, and the
  3200. result is written to matrix a.
  3201.  
  3202. MAT SUB a(),b() is only defined for matrix (vectors) of the same
  3203. order,  e.g.  DIM  a(n,m),b(n,m)  or DIM a(n),b(n).  Array  b  is 
  3204. subtracted  from  matrix a,  element by element,  and  the  result 
  3205. written to matrix a. The original matrix a is lost in the process.
  3206.  
  3207. MAT  SUB a(),x is defined for all  matrix  (vectors).  Here,  the 
  3208. scalar x is subtracted from matrix x, element by element, and the 
  3209. result is written to matrix a.  The original matrix a is lost  in 
  3210. the process.
  3211.  
  3212. MAT  MUL  a()=b()*c() is defined for matrix of  an  "appropriate" 
  3213. order. Arrays  b and c are multiplied with each other. The result 
  3214. of this multiplication is written to matrix a.  In order for  the 
  3215. result  to be defined,  the matrix on the left (matrix b in  this 
  3216. case)  must have the same number of columns as the matrix on  the 
  3217. right (c in this case) has rows. Array a, in this case, must have 
  3218. as many rows as b and as many columns as c.
  3219.  
  3220. Arrays are multiplied as "row by column",  i.e. element a(i.j) is 
  3221. obtained by multiplying the elements in the ith row of matrix   b 
  3222. with  the  elements in the jth column of  matrix  c,  element  by 
  3223. element, and then adding up the individual products.
  3224.  
  3225. With  vectors instead of matrix,  MAT MUL a()=b()*c() results  in 
  3226. the dyadic (or external) product of two vectors.
  3227.  
  3228. MAT  MUL  x=a()*b()  is only defined for vectors  with  an  equal 
  3229. number of elements.  The result x is the scalar product (the  so-
  3230. called interior product) of vectors a and b.  The scalar  product 
  3231. of   two   vectors  is  defined  as  the  sum   of   n   products 
  3232. a(i)*b(i),i=1,...,n.
  3233.  
  3234. MAT  MUL x=a()*b()*c() is defined for  qualified Vectors a and  c 
  3235. as  well  as qualified Matrix b(). 
  3236.  
  3237. MAT  NORM  a(),0  or MAT NORM a(),1 are defined  for  matrix  and 
  3238. vectors.  MAT NORM a(),0 normalises a matrix (a vector) by  rows, 
  3239. MAT NORM a(),1 by columns.  This means that after a normalisation 
  3240. by  rows (by columns) the sum of the squares of all  elements  in 
  3241. each row (column) is identical at 1.
  3242.  
  3243. MAT  DET x=a([i,j])[,n] calculates the determinants of  a  square 
  3244. matrix of the (n,n) type.  The row and column offsets are  preset 
  3245. to  a(0,0)  or a(1,1),  depending on MAT BASE 0 or  MAT  BASE  1, 
  3246. assuming  that  OPTION BASE 1 is enabled.  It is  also  possible, 
  3247. however, to calculate the determinant of a square part matrix. To 
  3248. do this, the row and column offsets of a() must be specified as i 
  3249. and j, and the number of elements in the part matrix as n. A part 
  3250. matrix of the (n,n) type is then created internally starting from 
  3251. the "position" ith row, jth column.
  3252.  
  3253. MAT  QDET  x=a([i,j])[,n]  works in the same manner  as  MAT  DET 
  3254. x = a([i,j])[,n],  except  that it has been optimised  for  speed 
  3255. rather  than accuracy.  Both will normally produce identical  re-
  3256. sults.  With "critical" matrix,  whose determinant is close to 0, 
  3257. you should always use MAT DET, though.
  3258.  
  3259.  
  3260. MAT RANG x=a([i,j])[,n] outputs the rank of a square  matrix.  As 
  3261. with  MAT  DET or MAT QDET,  you can select any  row  and  column 
  3262. offset.  The  number  of  elements in the  part  matrix  must  be 
  3263. specified with n.  This creates  a part matrix of the (n,n)  type 
  3264. internally, starting from the "position ith row, jth column.
  3265.  
  3266.  
  3267. MAT  INV  b()=a() is used to determine the inverses of  a  square 
  3268. matrix. The inverse of matrix a() is written to matrix b(), hence 
  3269. b() must be of the same type as a().
  3270.  
  3271.  
  3272.  
  3273. MAX
  3274. Syntax:    MAX(x [,y,z,...])  or  MAX(a$[,y$,z$....])
  3275. Action:    Returns the greatest value (or largest string) from
  3276.            a list of expressions.
  3277.  
  3278.  
  3279. MENU(x)    Returns the information about an event in the variable 
  3280.            'x' (-2 to 15). In the case where an item in a menu is 
  3281.            selected, the index of that item is found in MENU(0).
  3282.            MENU(-2) is the address of the message buffer.
  3283.            MENU(-1) is the address of the menu object tree.
  3284.            The  Message Buffer lies in the the variables  MENU(1) 
  3285.            to MENU(8) and the AES Integer Output Block in MENU(9) 
  3286.            to MENU(15).
  3287.            The Identification number of the event is in  MENU(1). 
  3288.            The  other  elements of the  message  bufffer  contain 
  3289.            various  values,  depending on the type of event  that 
  3290.            occured.
  3291.            
  3292.            MENU(1)=10         A Menu Item was selected.
  3293.                MENU(0)        Menu item index in the item list
  3294.                MENU(4)        Object number of the menu title
  3295.                MENU(5)        Object  number of the  chosen  menu 
  3296.                               item
  3297.                      
  3298.            MENU(1)=20         A window redraw is required
  3299.                MENU(4)        ID number (handle) of the window
  3300.                MENU(5),(6)    Coordinates  of top left corner  of 
  3301.                               the window
  3302.                MENU(7),(8)    Width & height of the window area
  3303.  
  3304.            MENU(1)=21         A window was clicked (activated)
  3305.                MENU(4)        ID number (handle) of the window
  3306.  
  3307.            MENU(1)=22         The  close  box  of  a  window  was 
  3308.                               clicked on
  3309.                MENU(4)        ID number (handle) of the window
  3310.  
  3311.            MENU(1)=23         The full box was clicked on
  3312.                MENU(4)        ID number (handle) of the window
  3313.  
  3314.            MENU(1)=24         One of the four arrow boxes,  or  a 
  3315.                               slider  bar area was  clciked.  The 
  3316.                               movement of a slider is detected as 
  3317.                               below,  MENU(1)=24  only  when  the 
  3318.                               grey area is clicked on.
  3319.                MENU(4)        ID number (handle) of the window
  3320.                MENU(5)        The  area  of the window  that  was 
  3321.                               clicked:
  3322.                               0: Above the vertical slider   
  3323.                               1: Below  "     "       "
  3324.                               2: Up arrow
  3325.                               3: Down arrow
  3326.                               4: Left of the horizontal slider
  3327.                               5: Right "  "      "        "
  3328.                               6: Left arrow
  3329.                               7: Right arrow
  3330.  
  3331.            MENU(1)=25         The horizontal slider was moved
  3332.                MENU(4)        ID number (handle) of the window
  3333.                MENU(5)        Position of the moved slider (1  to 
  3334.                               1000)
  3335.  
  3336.            MENU(1)=26         The vertical slider was moved
  3337.                MENU(4)        ID number (handle) of the window
  3338.                MENU(5)        Position of the moved slider (1  to 
  3339.                               1000)
  3340.  
  3341.            MENU(1)=27         The size of the window was  changed 
  3342.                               (using the size box)
  3343.                MENU(4)        ID number (handle) of the window
  3344.                MENU(5),(6)    New x and y coordinates of top left
  3345.                MENU(7),(8)    New width & height
  3346.  
  3347.            MENU(1)=28         The window's position was changed
  3348.                same parameters as above
  3349.  
  3350.            MENU(1)=29         A new GEM window was activated. 
  3351.                MENU(4)        ID number (handle) of the window
  3352.  
  3353.            MENU(1)=40         An  Accessory  was  selected.  This 
  3354.                               value  can only be received  by  an 
  3355.                               accessory,  which should chech  the 
  3356.                               value  in MENU(5) to see if  it  is 
  3357.                               that one being referred to.
  3358.                MENU(5)        ID of the accessory
  3359.  
  3360.            MENU(1)=41         An accessory was closed. This value 
  3361.                               can   only  be  received  from   an 
  3362.                               accessory.
  3363.                MENU(5)        ID of the accessory
  3364.  
  3365.            The varaible MENU(9) contains bit information on which 
  3366.            kind  of  event  has occurred.  If  the  bit  for  the 
  3367.            appropriate  event is set,  the variables  MENU(9)  to 
  3368.            MENU(15)  and  GINTOUT(0) to GINTOUT(6)  will  contain 
  3369.            information as follows:
  3370.                Bit 0  Keyboard
  3371.                Bit 1  Mouse button
  3372.                Bit 2  Mouse has entered/left rectangle 1
  3373.                Bit 3  Mouse has entered/left rectangle 2
  3374.                Bit 4  A message arrived in the message buffer
  3375.                Bit 5  Timer event
  3376.  
  3377.  
  3378.            MENU(10) x position of mouse when event terminated          
  3379.            MENU(11) y position of mouse when event terminated                      
  3380.            MENU(12) Mouse buttons pressed:
  3381.                     0 = none
  3382.                     1 = left
  3383.                     2 = right
  3384.                     3 = both buttons
  3385.                See also ON MENU BUTTON 
  3386.  
  3387.            MENU(13) supplies  the  status of the  keyboard  shift 
  3388.                     keys in a bit pattern:
  3389.                     Bit 0 = right shift
  3390.                     Bit 1 = left shift
  3391.                     Bit 2 = control
  3392.                     Bit 3 = alternate
  3393.                See also ON MENU KEY
  3394.  
  3395.            MENU(14) Gives  information about a pressed  key.  The 
  3396.                     low order byte contains the ASCII  code,  and 
  3397.                     the high order byte, the keyboard scan code
  3398.  
  3399.            MENU(15) Returns  the  number  of  mouse  clicks  that 
  3400.                     caused the event
  3401.  
  3402.  
  3403. MENU
  3404. Syntax:    MENU m$()
  3405. Action:    Displays  a menu bar.  The string array m$()  contains 
  3406.            the   headings,   entries  and  reserved   space   for 
  3407.            accessories  for the menu bar.  The  following  format 
  3408.            must be adhered to:
  3409.            m$(0)        Name of the accessory menu heading
  3410.            m$(1)        Name of the first entry in the first menu
  3411.            m$(2)        A line of minus signs
  3412.            m$(3)-m$(8)  Reserved  space  for  accessories.  These 
  3413.                         elements need only be 1 character long.
  3414.            m$(9)        An empty string,  which marks the end  of 
  3415.                         the first menu.
  3416.            All further menu entries have the following format:
  3417.            1. Heading of the menu
  3418.            2. List of menu entries
  3419.            3. An empty string which marks the end of the menu.
  3420.  
  3421.            After the last entry, a further empty string signifies 
  3422.            the end of the entire pull down menu.
  3423.  
  3424.            eg:
  3425.  
  3426. DIM entry$(20)
  3427. DATA "  Desk  ","  Test  "
  3428. DATA ----------,1,2,3,4,5,6,""
  3429. DATA "  File  ","  Load  ","  Save  "
  3430. DATA --------,"  Quit  ",""
  3431. DATA "  Titles  ","  Entry 1  ","  Entry 2  ",""
  3432. DATA End
  3433. i%=-1
  3434. REPEAT
  3435.   INC i%
  3436.   READ entry$(i%)
  3437. UNTIL entry$(i%)="End"
  3438. entry$(i%)=""
  3439. MENU entry$()
  3440. ON MENU GOSUB evaluate
  3441. '
  3442. REPEAT
  3443.   ON MENU
  3444. UNTIL MOUSEK AND 2
  3445. '
  3446. PROCEDURE evaluate
  3447.   MENU OFF
  3448.   ' MENU(0) contains array index of selected item
  3449.   m%=MENU(0)
  3450.   PRINT entry$(m%)
  3451.   '
  3452.   ALERT 0,"Tick before item ?",0,"YES|NO",a%
  3453.   IF a%=1
  3454.     MENU m%,1
  3455.   ELSE
  3456.     MENU m%,0
  3457.   ENDIF
  3458.   '
  3459.   ALERT 0,"Lightened characters | (Not selectable)",0,"YES|NO",a%
  3460.   IF a%=1
  3461.     MENU m%,2
  3462.   ELSE
  3463.     MENU m%,3
  3464.   ENDIF
  3465. RETURN
  3466.  
  3467.  
  3468. MENU x,y
  3469. Action:    The  x-th  entry of a menu can be  given  certain  (y) 
  3470.            attributes:
  3471.                0  remove tick from in front of menu entry
  3472.                1  install tick     "    "    "   "    "
  3473.                2  make menu entry non selectable (light text)
  3474.                3  make menu entry selectable (normal text)
  3475.                See MENU example.
  3476.  
  3477.  
  3478.  
  3479. MENU KILL
  3480. Action:    Deactivates  a menu,  but does not remove it from  the 
  3481.            screen. Also turns off the ON MENU GOSUB options.
  3482.  
  3483. MENU OFF
  3484. Action:    Returns  a menu title to 'normal' display.  (After  an 
  3485.            item  is  chosen from a menu,  the title is  shown  in 
  3486.            reverse video).
  3487.  
  3488.  
  3489. MENU_BAR
  3490. Syntax:    a%=MENU_BAR(tree%,flag)
  3491. Action:    Displays/erases a menu bar (from a resource file)
  3492.            Returns 0 if an error occurred.
  3493.            tree = address of the menu object tree
  3494.            flag - 1 display bar
  3495.                 - 2 erase bar
  3496.            See also MENU x$ and MENU KILL
  3497.  
  3498. MENU_ICHECK
  3499. Syntax:    a%=MENU_ICHECK(tree,item,flag)
  3500. Action:    Deletes/displays a tick against a menu item.
  3501.            tree = address of the menu object tree
  3502.            item = object number of the menu item
  3503.            flag - 1 delete tick
  3504.                 - 2 display tick
  3505.            See also MENU x,0 and MENU x,1
  3506.  
  3507.  
  3508.  
  3509. MENU_IENABLE
  3510. Syntax:    a%=MENU_IENABLE(tree,item,flag)
  3511. Action:    Enables/disables a menu entry.
  3512.            tree = address of the menu object tree
  3513.            item = object number of the menu entry
  3514.            flag - 1 disable
  3515.                 - 2 enable
  3516.            See also MENU x,2 and MENU x,3
  3517.  
  3518.  
  3519. MENU_REGISTER
  3520. Syntax:    a%=MENU_REGISTER(ap_id,m_text$)
  3521. Action:    Give a desk accessory a name,  and insert it into  the 
  3522.            accessory menu entries.  (provided the number of  Accs 
  3523.            is less than 6).
  3524.            Returns  the  object number of  the  appropriate  menu 
  3525.            item:
  3526.            0-5 for a valid result
  3527.            -1  no more entries possible
  3528.            ap_id   = ID number of the accessory
  3529.            m_text$ = name for the Accessory
  3530.  
  3531.  
  3532.  
  3533. MENU_TEXT
  3534. Syntax:    a%=MENU_TEXT(tree,item,new_text$)
  3535. Action:    Changes the text of a menu item.
  3536.            Returns 0 on error.
  3537.            tree = address of the menu object tree
  3538.            item = object number of the menu item
  3539.            new_text$  the  new text for the menu entry  (may  not 
  3540.                       exceed the old text length)  
  3541.  
  3542.  
  3543. MENU_TNORMAL
  3544. Syntax:    a%=MENU_TNORMAL(tree,title,flag)
  3545. Action:    Switches the menu title to normal/inverse video.
  3546.            Returns 0 on error.
  3547.            tree = address of the menu object tree
  3548.            item = object number of the menu item
  3549.            flag - 1 inverse video
  3550.                 - 2 normal video
  3551.            See MENU OFF
  3552.  
  3553.  
  3554. MFREE
  3555. Syntax:    a%=MFREE(y)
  3556. Action:    (GEMDOS  73)  Releases the storage  location  reserved 
  3557.            with MALLOC.  The parameter 'y' specifies the start of 
  3558.            the  area of memory to be released.  Returns 0  if  no 
  3559.            error occurred, otherwise negative result.
  3560.  
  3561.  
  3562.  
  3563. MID$
  3564. Syntax:    MID$(a$,x[,y]) (as a function)
  3565. Action:    Returns 'y' characters in a string from the positon 'x' 
  3566.            of the string 'a$'.  If x is larger than the length of 
  3567.            a$,  then a null string is returned.  If y is omitted, 
  3568.            then the function returns the whole of the string from 
  3569.            position x onwards.
  3570.  
  3571.  
  3572. MID$
  3573. Syntax:    MID$(a$,x[,y]) (as a command)
  3574. Action:    MID$ used as a command,  makes it possible to  replace 
  3575.            part   of  a  string  variable  a$  with  the   string 
  3576.            expression  b$.  So with  MID$(a$,x,y)=b$,  characters 
  3577.            from b$ will overwrite those in a$, starting at the x-
  3578.            th postion of a$.  The optional parameter y determines 
  3579.            how many characters of b$ are used.  If y is  omitted, 
  3580.            then as many characters as possible of a$ are replaced 
  3581.            with those from b$.  The length of a$ is unchanged, so 
  3582.            that  no charatcers will be written beyond the end  of 
  3583.            a$
  3584.            eg:
  3585.            a$="GFA SYSTEMTECHNIK"
  3586.            MID$(a$,5)="BASIC "
  3587.            would result in a$ being "GFA BASIC TECHNIK"
  3588.  
  3589.  
  3590.  
  3591. MIN
  3592. Syntax:    MIN(expression [ ,expression... ])
  3593. Action:    Returns the smallest value (or smallest string) from
  3594.            a list of expressions.
  3595.  
  3596.  
  3597.  
  3598. MKDIR
  3599. Syntax:    MKDIR "directory name"
  3600. Action:    Creates a new directory.
  3601.            'directory name' is the name of the new directory.
  3602.  
  3603.  
  3604.  
  3605.  
  3606. MKI$ MKL$ MKS$ MKF$ MKD$
  3607. Syntax:    MKI$(N)
  3608.            MKL$(N)
  3609.            MKS$(N)
  3610.            MKF$(N)
  3611.            MKD$(N)
  3612. Action:    Transforms a number into a character string.
  3613.            MKI$ 16-bit number into a 2-byte string.
  3614.            MKL$ 32-bit number into a 4-byte string.
  3615.            MKS$ a number into an atari basic 4-byte format.
  3616.            MKF$ a number into GFA Basics own 6-byte format.
  3617.            MKD$ a number into a Mbasic compatible 8-byte format.
  3618.  
  3619.            Every number that is to be stored in a random access
  3620.            file must first be transformed with on of the above
  3621.            functions.
  3622.            The example above shows that GFA Basic stores numbers
  3623.            internally in the 6-byte format which can also be
  3624.            created using the MKF$ function.
  3625.            See also CVI,CVL,CVD,CVF
  3626.  
  3627.  
  3628.  
  3629. MOD
  3630. Syntax:    a=x MOD y    or   a=MOD(x,y)
  3631. Action:    Produces the remainder of the division of x by y.
  3632.            The   command   in  brackets   operates   in   integer 
  3633.            arithmetic.
  3634.  
  3635.  
  3636.  
  3637. MODE
  3638. Syntax:    MODE n
  3639. Action:    With MODE the representation of decimal point and  the 
  3640.            'thousands comma' are interpreted by PRINT USING  (and 
  3641.            also by STR$ with 3 parameters).
  3642.            Also selects the format of date representation used by 
  3643.            DATE$, SETTIME, and FILES.
  3644.            
  3645.            MODE  USING     DATE$
  3646.            0     #,###.##  16.05.1988
  3647.            1     #,###.##  05/16/1988
  3648.            2     #.###,##  16.05.1988
  3649.            3     #.###,##  05/16/1988
  3650.  
  3651.  
  3652.  
  3653.  
  3654. MONITOR
  3655. Syntax:    MONITOR [x]
  3656. Action:    Calls a monitor resident in memory.  This  instruction 
  3657.            causes  an illegal instruction vector.  (address  16). 
  3658.            The parameter x is passed via the register D0.
  3659.  
  3660.  
  3661.  
  3662. MOUSEX  
  3663. MOUSEY  
  3664. MOUSEK
  3665. MOUSE mx,my,mk
  3666. Syntax:    MOUSE x,y,k
  3667.            x=MOUSEX
  3668.            y=MOUSEY
  3669.            k=MOUSEK
  3670. Action:    Determines the mouse position (x,y) and the status of
  3671.            the mouse buttons:
  3672.            k=0 no buttons pressed
  3673.            k=1 left button
  3674.            k=2 right button
  3675.            k=3 both buttons
  3676.  
  3677.  
  3678. MSHRINK
  3679. Syntax:    a%=MSHRINK(y,z)
  3680. Action:    (GEMDOS  74)  Reduces  the  size  of  a  storage  area 
  3681.            previously  allocated  with MALLOC.  y  specifies  the 
  3682.            address of the area,z gives the required size.
  3683.            Returns 0 if no error,  -40 if incorrect address, or -
  3684.            67 if size wrong.
  3685.            See also RESERVE MALLOC MFREE
  3686.  
  3687.  
  3688.  
  3689. MUL
  3690. Syntax:    MUL var,n
  3691. Action:    Multiplies the value 'var' by 'n'.
  3692.            same as var=var*n but executes 30% faster.
  3693.  
  3694. MUL()      Same as for MUL. but integers only.
  3695.  
  3696.  
  3697.  
  3698. MW_OUT
  3699. Syntax:    MWOUT mask,data
  3700.            This  command  controls the  STE-Internal  Micro-Wire-
  3701.            Interface,  and  is  currently  used  for  controlling 
  3702.            sound. 
  3703.  
  3704.                MWOUT &H7FF,x
  3705.  
  3706.                x=&X10 011 ddd ddd       Set Master Volume
  3707.                           000 000       -80 dB
  3708.                           010 100       -40 dB
  3709.                           101 xxx         0 dB
  3710.  
  3711.            The  value of the last 5 Bits is eqivalent to HALF  of 
  3712.            the volume in dB.
  3713.  
  3714.                x=&X10 101 xdd ddd       Set Right Channel Volume
  3715.                            00 000       -40 dB
  3716.                            01 010       -20 dB
  3717.                            10 1xx         0 dB
  3718.  
  3719.                x=&X10 100 xdd ddd       Set Right Channel Volume
  3720.                
  3721.                The last 4 Bits*2 = dB
  3722.  
  3723.                x=&X10 010 xxd ddd       Set Treble
  3724.                x=&X10 001 xxd ddd       Set Bass
  3725.                             0 000       -12dB
  3726.                             0 110       0 dB (flat)
  3727.                             1 100       +12 dB
  3728.  
  3729.                x=&X10 000 xxx xdd       Set Mix
  3730.                                00       -12dB
  3731.                                01       Mix GI Sound (normal ST)
  3732.                                10       Not Mix
  3733.                                11       Reserved
  3734.  
  3735. Example: MWOUT &H7FF,&X10000000010 Switches the ST's sound off.
  3736.  
  3737.  
  3738.     
  3739. NAME
  3740. Syntax:    NAME "oldfile" AS "newfile"
  3741. Action:    Renames an existing file. The contents of the file are
  3742.            not affected.
  3743.  
  3744.  
  3745.  
  3746. NEW
  3747. Syntax:    NEW
  3748. Action:    Deletes the program currently in memory and clears all
  3749.            variables.
  3750.  
  3751. NOT
  3752. Syntax:    NOT x
  3753. Action:    Negates a given logical expression.
  3754.  
  3755.  
  3756. The following 19 commands belong to the AES Object library.
  3757.  
  3758. OBJC_ADD
  3759. Syntax:    a%=OBJC_ADD(tree,parent,child)
  3760. Action:    Adds  an object to a given tree and  pointers  between 
  3761.            the existing objects and the new object are created.
  3762.            Returns 0 on error.
  3763.            tree     address of the object tree
  3764.            parent   object number of the parent object
  3765.            child    object number of the child to be added.
  3766.  
  3767.  
  3768. OBJC_CHANGE
  3769. Syntax:    a%=OBJC_CHANGE(tree,obj,res,cx,cy,cw,ch,new_status,re_draw)
  3770. Action:    Changes the status of an object.
  3771.            Returns 0 on error.
  3772.            tree     address of the object tree
  3773.            obj      number of the object to be changed
  3774.            res      reserved (always 0)
  3775.            cx,cy    coordinates  of top left corner  of  clipping 
  3776.                     rectangle
  3777.            cw,ch    width & height of clipping rectangle
  3778.            new_status   new object status
  3779.            re_draw  1 = redraw object
  3780.                     0 = don't redraw
  3781.  
  3782.  
  3783. OBJC_DELETE
  3784. Syntax:    a%=OBJC-DELETE(tree,del_obj)
  3785. Action:    An  object is deleted from an object tree by  removing 
  3786.            the  pointers.  The object is still there and  can  be 
  3787.            restored by repairing the pointers.
  3788.            Rteurns 0 on error.
  3789.            tree     address of the object tree
  3790.            del_obj  Object number of the object to delete.
  3791.  
  3792.  
  3793.  
  3794. OBJC_DRAW
  3795. Syntax:    a%=OBJC_DRAW(tree,start_obj,depth,cx,cy,cw,ch)
  3796. Action:    Draws  whole objects or part of objects on  screen.  A 
  3797.            clipping rectangle is specified,  to which the drawing 
  3798.            is limited.
  3799.            Returns 0 on error.
  3800.            tree     address of the object tree
  3801.            start_obj  number of the first object to be drawn
  3802.            depth    Number of object levels to be drawn
  3803.            cx,cy    coordinates  of top left corner  of  clipping 
  3804.                     rectangle
  3805.            cw,ch    width & height of clipping rectangle
  3806.  
  3807.  
  3808. OBJC_EDIT
  3809. Syntax:    a%=OBJC_EDIT(tree,obj,char,old_pos,flag,new_pos)
  3810. Action:    Allows  input  and  editing in  G_TEXT  and  G_BOXTEXT 
  3811.            object types.
  3812.            Returns 0 on error.
  3813.            tree     address of the object tree
  3814.            obj      number of the object to be changed
  3815.            char     input character (incl. scan code)
  3816.            old_pos  current cursor position in input string
  3817.            flag     funtion:
  3818.                     0 ED_START     -reserved-
  3819.                     1 ED_INIT      string is formatted & cursor on
  3820.                     2 ED_CHAR      Character processed &  string 
  3821.                                     redisplayed
  3822.                     3 ED_END       Text cursor switched off
  3823.            new_pos  returns  new  pos  of  text  cursor  to  this 
  3824.                     variable.
  3825.  
  3826.  
  3827. OBJC_FIND
  3828. Syntax:    a%=OBJC_FIND(tree,start_obj,depth,fx,fy)
  3829. Action:    Determines  the  object,  if  any,  which  is  at  the 
  3830.            coordinates specified in fx,fy.
  3831.            Returns the object number, or -1 if no object found.
  3832.            tree     address of the object tree
  3833.            start_obj  number of the object from where to search
  3834.            depth    Number of object levels to be searched
  3835.            fx       x coordinate (usually MOUSEX)
  3836.            fy       y coordinate (usually MOUSEY)
  3837.  
  3838.  
  3839. OBJC_OFFSET
  3840. Syntax:    a%=OBJC_OFFSET(tree,obj,x_abs,y_abs)
  3841. Action:    Calculates  the  absolute screen  coordinates  of  the 
  3842.            specified object.           
  3843.            Returns 0 on error.
  3844.            tree     address of the object tree
  3845.            obj      object number 
  3846.            x_abs,y_abs  returns  the  x,y  coordinates  to  these 
  3847.                         variables.
  3848.  
  3849.  
  3850.  
  3851. OBJC_ORDER
  3852. Syntax:    a%=OBJC_ORDER(tree,obj,new_pos)
  3853. Action:    re-positions an object within a tree.
  3854.            Returns 0 on error.
  3855.            tree     address of the object tree
  3856.            obj      object number 
  3857.            new_pos  new level number
  3858.  
  3859.  
  3860.  
  3861. OB_ADR
  3862. Syntax:    adr%=OB_ADR(tree,obj)
  3863. Action:    Gets the address of an individual object.
  3864.            Returns 0 on error.
  3865.            tree     address of the object tree
  3866.            obj      object number
  3867.  
  3868.  
  3869. OB_FLAGS
  3870. Syntax:    a%=OB_FLAGS(tree,obj)
  3871. Action:    Gets the status of the flags for an object.
  3872.            Returns 0 on error.
  3873.            tree     address of the object tree
  3874.            obj      object number
  3875.            OB_FLAGS     Bit No.
  3876.            Normal       -
  3877.            Selectable   0
  3878.            Default      1
  3879.            Exit         2
  3880.            Editable     3
  3881.            Rbutton      4
  3882.            Lastob       5
  3883.            Touchexit    6
  3884.            Hidetree     7
  3885.            Indirect     8           
  3886.  
  3887.  
  3888. OB_H
  3889. Syntax:    h%=OB_H(tree,obj)
  3890. Action:    Returns the height of an object
  3891.            Returns 0 on error.
  3892.            tree     address of the object tree
  3893.            obj      object number
  3894.  
  3895.  
  3896. OB_HEAD
  3897. Syntax:    h%=OB_HEAD(tree,obj)
  3898. Action:    Points to the object's first child, or -1 if none.
  3899.  
  3900.  
  3901. OB_NEXT
  3902. Syntax:    n%=OB_NEXT(tree,obj)
  3903. Action:    Points to the following object on the same level,  or, 
  3904.            if it is the last object on that level,  to the parent 
  3905.            object, or -1 if none.
  3906.            
  3907.  
  3908. OB_SPEC
  3909. Syntax:    a%=OB_SPEC(tree,obj)
  3910. Action:    Returns the address of the the data structure for  the 
  3911.            object.
  3912.  
  3913.  
  3914. OB_STATE
  3915. Syntax:    s%=OB_STATE(tree,obj)
  3916. Action:    returns the status of an object:
  3917.            OB_STATE     Bit No.
  3918.            Normal       -
  3919.            Selected     0
  3920.            Crossed      1
  3921.            Checked      2
  3922.            Disabled     3
  3923.            Outlined     4
  3924.            Shadowed     5
  3925.  
  3926.  
  3927. OB_TAIL
  3928. Syntax:    t%=OB_TAIL(tree,obj)
  3929. Action:    Points to the objects last child, or -1 if none.
  3930.  
  3931.  
  3932. OB_TYPE
  3933. Syntax:    t&=OB_TYPE(tree,obj)
  3934. Action:    Returns the type of object specified.
  3935.  
  3936.  
  3937. OB_W
  3938. Syntax:    w%=OB_W(tree,obj)
  3939. Action:    Returns the width of an object
  3940.  
  3941.  
  3942. OB_X
  3943. OB_Y
  3944. Syntax:    x (or y) =OB_X or OB_Y(tree,obj)
  3945. Action:    Rteurns   the  relative  coordinates  of  the   object 
  3946.            relative  to  its parent (or the screen if it  is  the 
  3947.            parent)
  3948.  
  3949.  
  3950. OCT$
  3951. Syntax:    OCT$(x[,n])
  3952. Action:    Changes the value 'x' into a string containing the
  3953.            value of 'x' in octal form (prefix &O),  the  optional 
  3954.            parameter n, giving the number of characters to print.
  3955.  
  3956.  
  3957. ODD
  3958. Syntax:    ODD(n)
  3959. Action:    Determines whether a number is odd. (see also even)
  3960.  
  3961.  
  3962.  
  3963. ON BREAK Syntax:    ON BREAK
  3964.            ON BREAK CONT
  3965.            ON BREAK GOSUB name
  3966. Action:    ON BREAK CONT makes it impossible to stop a program
  3967.            by pressing break ( <ALT><SHIFT><CNTRL> ).
  3968.            ON BREAK reactivates it.
  3969.            ON BREAK GOSUB makes it possible to jump to the procedure 
  3970.            'name' by the above key combination.
  3971.  
  3972.  
  3973. ON ERROR  
  3974. Syntax:    ON ERROR
  3975.            ON ERROR GOSUB name
  3976. Action:    Performs the procedure 'name' when an error occurs.
  3977.            The program is not interrupted and no error message
  3978.            is given.
  3979.            See also RESUME
  3980.  
  3981.  
  3982. ON...GOSUB
  3983. Syntax:    ON x GOSUB proc1,proc2......
  3984. Action:    Depending on the result of 'x'  one of several   given 
  3985.            procedures is processed.
  3986.            'proc1' ..  is a list of procedure names separated  by 
  3987.            commas. The result of 'x' denotes which procedure is
  3988.            carried out. 
  3989.            Eg: If result = 1 then the first procedure in the 
  3990.            procedure list is processed.
  3991.            If result = 2 then the second procedure in the procedure
  3992.            list is processed.
  3993.            If result = 3 then the third procedure in the procedure
  3994.            list is processed and so on.
  3995.            If the value is not in the  range then no procedure
  3996.            will be executed.
  3997.  
  3998.  
  3999.  
  4000. ON MENU
  4001. Syntax:    ON MENU[t]
  4002. Action:    This  command  handles  EVENTs.   Prior  to  use,  the 
  4003.            required  action should be specified with an  ON  MENU 
  4004.            xxx GOSUB command. For constant supervision of events, 
  4005.            ON MENU is usually found in a loop.
  4006.            The parameter t is the time in thousandths of a second 
  4007.            to elapse before the ON MENU command is terminated.          
  4008.  
  4009.  
  4010.  
  4011.  
  4012. ON MENU xxx GOSUB
  4013. Syntax:    ON MENU BUTTON clicks,but,state GOSUB proc
  4014. Action:    Sets up the action to be taken when one or more  mouse 
  4015.            clicks  are  received.   With  a  subsequent  ON  MENU 
  4016.            command,  the  named procedure will be branched to  if 
  4017.            the condition imposed by the parameters are met.
  4018.            clicks   -   sets  the maximum number of  clicks  that 
  4019.                         will generate a response.
  4020.            button   -   The expected button combination:    
  4021.                         0 - any
  4022.                         1 - left
  4023.                         2 - right
  4024.                         3 - both
  4025.            state    -   Specifies which button state (up or down) 
  4026.                         will cause the event. 0 = up, 1 = down
  4027.            proc     -   The procedure to branch to.
  4028.  
  4029.  
  4030. Syntax:    ON MENU GOSUB proc
  4031. Action:    The  procedure  to  which control will  be  passed  on 
  4032.            selection of  a  menu  entry  is  determined.   If  an 
  4033.            accessory is currently open, the procedure will not be 
  4034.            called.
  4035.            See also MENU(0)
  4036.  
  4037.  
  4038. Syntax:    ON MENU IBOX n,x,y,b,h GOSUB proc
  4039. Action:    Monitors  the mouse coordinates,  and branches to  the 
  4040.            named  procedure  if the mouse  enters Y
  4041.            k=MOUSEK
  4042. Action:    Determines the mouse position (x,y) and the status of
  4043.            the mouse buttons:
  4044.            k=0 no buttons pressed
  4045.            k=1 left button
  4046.            k=2 right button
  4047.            k=3 both buttons
  4048.  
  4049.  
  4050.  
  4051.  
  4052. Syntax:    ON MENU KEY GOSUB proc
  4053. Action:    Monitors the keyboard,  and branches to proc if a  key 
  4054.            was pressed during an ON MENU loop.
  4055.            See MENU(13) & MENU(14) for the keys.
  4056.  
  4057.  
  4058.  
  4059. Syntax:    ON MENU MESSAGE GOSUB proc
  4060. Action:    Brances  to proc if a message arrives in  the  message 
  4061.            buffer during an ON MENU loop. 
  4062.            See MENU(x) for the messages.
  4063.            
  4064.  
  4065. Syntax:    ON MENU OBOX n,x,y,w,h GOSUB proc
  4066. Action:    Monitors  the mouse coordinates,  and branches to  the 
  4067.            named  procedure  if the mouse  leaves  a  rectangular 
  4068.            screen area. It is possible to wait for two such boxes 
  4069.            to  be left (n can be 1 or 2 ).  x and y are  the  top 
  4070.            left  coordinates of the rectangle,  w & h  being  its 
  4071.            width and height.  Continuous monitoring is done  with 
  4072.            ON MENU.
  4073.  
  4074.  
  4075. OPEN
  4076. Syntax:    OPEN mode$,#n,name$[,len]
  4077. Action:    Opens a data channel to a file or a peripheral device.
  4078.            'mode' must always be written in quotes and is one
  4079.            of the following :-
  4080.            'O' (output) opens a write file creating a new file if 
  4081.            needed.
  4082.            'I' (input) opens a read file.
  4083.            'A' (append) enables data to be annexed to an existing 
  4084.            file.
  4085.            'U' (update) read/write, but file must be opened by 'o' 
  4086.            first.
  4087.            'R' stands for random access file.
  4088.            Instead  of  a filename,  a periphral  device  can  ne 
  4089.            specified.  The  expression  'len' is used  only  with 
  4090.            Random Access mode.
  4091.            the following can be used instead of filenames :-
  4092.            'CON:'  for the console. 
  4093.            'LST:'  or 'prn:' for the printer.
  4094.            'AUX:'  for the serial interface.
  4095.            'MID:'  for midi.
  4096.            'VID:'  for the console in transparent mode
  4097.                    (commands are produced but not executed).
  4098.            'IKB:'  for direct access to the keyboard controller.
  4099.            'STD:'. (This is the same as 'Stdin','Stdout' resp. in 
  4100.            C-programs.) So you can use  a shell to redirect the 
  4101.            output of a GFA-BASIC program.
  4102.  
  4103.            GFABASIC TEST >DUMMY
  4104.  
  4105.            This line starts GFA BASIC and the program TEST.PRG 
  4106.            Any output via 'STD:' is redirected to the file  DUMMY. 
  4107.            IMPORTANT: CONTROL-C will cause a hang- up when given 
  4108.            while reading/writing DUMMY. the default for input/output
  4109.            is the keyboard/console.
  4110.            The  numerical  expression 'n'  contains  the  channel 
  4111.            number (0-99), and the variable name$, the access path 
  4112.            and filename.
  4113.  
  4114.  
  4115.  
  4116. OPENW
  4117. Syntax:    OPENW nr[,x a  rectangular 
  4118.            screen  area.  It  is possible to wait  for  two  such 
  4119.            boxes  to be entered (n can be 1 or 2 ).  x and y  are 
  4120.            the top left coordinates of the rectangle, w & h being 
  4121.            its  width and height.  Continuous monitoring is  done 
  4122.            with ON MENU.
  4123.  
  4124.  
  4125.  
  4126. OPTION BASE 
  4127. Syntax:    OPTION BASE 0 (default)
  4128.            OPTION BASE 1
  4129. Action:    This  command  can determine whether an  array  is  to 
  4130.            contain a zero element or not. ie. with OPTION BASE 0, 
  4131.            doing a DIM a%(10) will allow a%(0) to exist.
  4132.  
  4133.  
  4134. OR
  4135. Syntax:    x OR y
  4136. Action:    The  command OR (disjunction) checks whether at  least 
  4137.            one of two logical expressions x and y is  TRUE.  Only 
  4138.            if  x  and y are both FALSE will the result  FALSE  be 
  4139.            produced.
  4140.  
  4141.  
  4142. OR()
  4143. Syntax:    OR(x,y)
  4144. Action:    The  result of OR contains bits set in the  places  in 
  4145.            which bits are set in either x or y or both.
  4146.  
  4147.  
  4148.  
  4149. OTHERWISE  See SELECT
  4150.  
  4151.  
  4152.  
  4153. OUT
  4154. Syntax:    OUT [#]n,a[,b..]
  4155. Action:    Transfers a byte[s] with the value 'a' to a peripheral
  4156.            device or file 'n'.
  4157.            See OPEN for valid peripherals.
  4158.            See also INP
  4159.  
  4160. OUT#       See INP#
  4161.  
  4162.  
  4163. OUT?
  4164. Syntax:    OUT?(n)
  4165. Action:    Determines the output status of a periphery.
  4166.            This function returns 0 if a character can be output.
  4167.            (see also INP?)
  4168.  
  4169.  
  4170. PADT(i)
  4171. Syntax:    a=PADT(i)
  4172. Action:    Reads the paddle buttons on the STE
  4173.  
  4174.  
  4175. PADX(i)
  4176. PADY(i)
  4177. Syntax:    a=PADX(i)  or  PADY(i)
  4178. Action:    Reads the x or y position of the paddles on the STE. i 
  4179.            can be 0 or 1.
  4180.  
  4181.  
  4182.  
  4183. PAUSE
  4184. Syntax:    PAUSE x
  4185. Action:    Interrupts a program for exactly  x/50 seconds.
  4186.            See also DELAY.
  4187.  
  4188.  
  4189.  
  4190. PBOX
  4191. Syntax:    PBOX x,y,x1,y1
  4192. Action:    Draws  a filled rectangle with the coordinates of  the 
  4193.            two opposite corners specified by x,y and x1,y1.
  4194.            See also BOX,PRBOX, RBOX.
  4195.  
  4196.  
  4197. PCIRCLE
  4198. Syntax:    PCIRCLE x,y,r[,w1,w2]
  4199. Action:    Draws a filled circle with centre coordinates  at  x,y 
  4200.            and a radius r.  Additional start and end angles w1 and 
  4201.            w2 can be specified to draw a circular arc.
  4202.  
  4203.  
  4204.  
  4205. PEEK  DPEEK  LPEEK 
  4206. Syntax:    PEEK(x)
  4207.            DPEEK(x)
  4208.            LPEEK(x)
  4209. Action:    Returns the contents of the memory at address 'x'
  4210.            PEEK  returns a 1 byte at address x
  4211.            DPEEK  returns a 2 byte number from x and x+1
  4212.            LPEEK  returns a 4 byte number from x, x+1, x+2 & x+3
  4213.            for DPEEK and LPEEK, 'x' must be an even number.
  4214.  
  4215.  
  4216.  
  4217.  
  4218.  
  4219. PELLIPSE
  4220. Syntax:    PELLIPSE x,y,rx,ry [,phi0,phi1]
  4221. Action:    Draws a filled ellipse at x,y, having 'rx' as length of the
  4222.            horizontal axis and 'ry' as length of the vertical axis
  4223.            The optional angles 'phi0' & 'phi1' give start and end
  4224.            angles in tenths of a degree, to create an elliptical arc.
  4225.  
  4226.  
  4227. PI
  4228. Syntax:    PI
  4229. Action:    Returns the value of PI. The value of PI is
  4230.            3.141592653.....etc.
  4231.  
  4232.  
  4233.  
  4234. PLOT
  4235. Syntax:    PLOT x,y
  4236. Action:    Plots a point on the screen coordinates 'x,y'.
  4237.            This command is the same as draw x,y.
  4238.  
  4239.  
  4240.  
  4241. POINT
  4242. Syntax:    POINT x,y
  4243. Action:    Checks if a graphic dot (at 'x,y') has been set and
  4244.            returns its colour value.
  4245.  
  4246.  
  4247.  
  4248. POKE  DPOKE  LPOKE
  4249. Syntax:    POKE x,n
  4250.            DPOKE x,n
  4251.            LPOKE x,n
  4252. Action:    Writes 1, 2 or 4 bytes into memory at an address which
  4253.            starts at 'x'.
  4254.            The value of 'x' must be an even number for DPOKE and
  4255.            LPOKE.
  4256.            
  4257.  
  4258.  
  4259. POLYLINE   POLYFILL  POLYMARK
  4260. Syntax:    POLYLINE n,x(),y()[OFFSETx_off,y_off]
  4261.            POLYFILL n,x(),y()[OFFSETx_off,y_off]           
  4262.            POLYMARK n,x(),y()[OFFSETx_off,y_off]
  4263. Action:    POLYLINE  draws  a polygon with  n  corners.  The  x,y 
  4264.            coordinates for the corner pointa are given in  arrays 
  4265.            x()   and  y().   The  first  and  last   points   are 
  4266.            automatically connected. The optional parameter OFFSET 
  4267.            can be added to these coordinates. 
  4268.            POLYFILL fills the polygon with the pattern previously 
  4269.            defined by DEFFILL.
  4270.            POLYMARK  marks  the  corner  points  with  the  shape 
  4271.            defined by DEFMARK.
  4272.  
  4273.  
  4274.  
  4275. POS
  4276. Syntax:    POS(n)
  4277. Action:    Returns the column in which the cursor is positioned.
  4278.            'n', a hypothetical argument, is optional.
  4279.            See also CRSCOL, CRSLIN, TAB, HTAB, VTAB.
  4280.  
  4281.  
  4282.  
  4283. PRBOX
  4284. Syntax:    PRBOX x,y,x1,y1
  4285. Action:    Draws a filled rectangle with rounded corners.
  4286.            See also BOX, PBOX, RBOX.
  4287.  
  4288.  
  4289. PRED
  4290. Syntax:    a$=PRED(b$)
  4291. Action:    Supplies  the character with the ASCII code  one  less 
  4292.            than  that  of the first character  of  the  specified 
  4293.            string.
  4294.            See also SUCC.
  4295.  
  4296.  
  4297. PRED()
  4298. Syntax:    i%=PRED(n%)
  4299. Action:    Returns the next lower number of the integer argument.
  4300.            See also SUCC().
  4301.  
  4302.  
  4303.  
  4304. PRINT  
  4305. Syntax:    PRINT 
  4306.            PRINT expression
  4307. Action:    Displays information on the screen. 
  4308.            'expr' can be any number of expressions which must be
  4309.            separated by commas, semicolons or apostrophes.
  4310.            ; -items are printed one after an other in one line.
  4311.            , -items are printed at intervals of 16 columns.
  4312.            ' -each apostrophe causes a space to be printed.
  4313.  
  4314.  
  4315.  
  4316.  
  4317. PRINT AT
  4318. Syntax:    PRINT AT(column,row);expression
  4319. Action:    Prints  'expression'  at a specified row  and  column. 
  4320.            NB. These start at 1, not 0.
  4321.  
  4322.  
  4323.  
  4324.  
  4325. PRINT USING
  4326. Syntax:    PRINT USING format$,expression[;]
  4327.            PRINT AT(column,row);USING format$,expression[;]
  4328. Action:    Prints formatted digits and character strings.
  4329.            format$ is a string expression which sets the printing
  4330.            format using a list of expressions separated by commas.
  4331.  
  4332.            #    reserves space for a digit.
  4333.            .    position of the decimal point.
  4334.            +    executes a plus sign.
  4335.            -    reserves space for a minus sign.
  4336.            *    zeros before the comma are replaced by * otherwise
  4337.                 the same as #.
  4338.            $    prefix $.
  4339.            ,    insertion of a comma.             
  4340.            ^    execution in exponent form  E+
  4341.            !    indicates that the first character of a string is
  4342.                 issued.
  4343.            &    the whole string is issued.
  4344.         \..\    as many characters as the length of \..\ is issued
  4345.                 (including back-slashes).
  4346.            -    prints the proceeding character.
  4347.  
  4348.  
  4349.  
  4350. PRINT TAB
  4351. Syntax:    PRINT TAB(n)
  4352. Action:    Prints  spaces  until  POS(0)  reaches  n.  If  POS(0) 
  4353.            already exceeds n then a Line Feed/Carriage Return  is 
  4354.            executed first.
  4355.  
  4356.  
  4357.  
  4358. PRINT#
  4359. Syntax:    PRINT #n,expression
  4360.            PRINT #n,USING format$,expression
  4361. Action:    Outputs data to a specified channel n  (0-99).  PRINT# 
  4362.            USING allows formatted data to be output.
  4363.  
  4364.  
  4365. PROCEDURE
  4366. Syntax:    PROCEDURE proc[(var1,var2,...)]
  4367. Action:    Marks the beginning of a procedure.
  4368.            Basic will only process a procedure when it is called
  4369.            by the command GOSUB   (or   by  simply   naming   the 
  4370.            procedure, or using  @proc. If it comes across the command
  4371.            procedure during 'normal' running of the program, it
  4372.            considers it to be the end of the program.
  4373.            Not  only  the  values  of  variable,   but  also  the 
  4374.            variable's  address can be passed to procedures  using 
  4375.            the VAR command in the Procedure's header.
  4376.  
  4377.  
  4378.  
  4379. PSAVE
  4380. Syntax:    PSAVE f$
  4381. Action:    Saves the current program to disk with the name f$, it 
  4382.            is saved with protection,  and cannot be  subsequently 
  4383.            listed    on   re-loading;    PSAVEd   programs    RUN 
  4384.            automatically on loading.
  4385.            See also SAVE
  4386.  
  4387.  
  4388.  
  4389. PTSIN      Address of the VDI point input table
  4390. PTSOUT     Address of the VDI point output table
  4391.            These two commands can be used with index,  to address 
  4392.            the array directly. eg. PTSIN(0).
  4393.  
  4394.  
  4395.  
  4396. PTST()
  4397. Syntax:    a=PTST(x,y)
  4398. Action:    Corresponds to the POINT command.  Returns the  colour 
  4399.            of the pixel at x,y.
  4400.  
  4401.  
  4402. PUT
  4403. Syntax:    PUT x,y,section$[,mode]
  4404. Action:    Places a graphics block on the screen at x,y which
  4405.            has been previously grabbed by GET, and stored in 
  4406.            section$.
  4407.            'mode' (optional) sets the way the image is placed.
  4408.            0 -                All points are cleared
  4409.            1 - s AND d        Only points set in both remain set.
  4410.            2 - s AND (NOT d)  Sets  only points which are  set  in 
  4411.                               the   source   and  clear   in   the 
  4412.                               destination.
  4413.            3 - s              Overwrite (default GRAPHMODE 1)
  4414.            4 - (NOT s)AND d   
  4415.            5 - d
  4416.            6 - s XOR d
  4417.            7 - s OR d
  4418.            8 - NOT(s OR d)
  4419.            9 - NOT(s XOR d)
  4420.            10  NOT d
  4421.            11  s OR(NOT d)
  4422.            12  NOT s
  4423.            13  (NOT s)OR d
  4424.            14  NOT(s AND d)
  4425.            15  1              All points set.
  4426.            The important ones are:
  4427.            3   Repalce
  4428.            4   XOR
  4429.            7   Transparent
  4430.            13  Inverse Transparent.
  4431.  
  4432.  
  4433.  
  4434. PUT #
  4435. Syntax:    PUT #n[,r]             
  4436. Action:    Writes a record to a random access file.
  4437.            'n' data channel number (0 to 99).
  4438.            'r' is an integer expression between 1 and the number
  4439.            of records in the file (max 65535) and denotes the
  4440.            record number of the record to be written.
  4441.            See also GET #, RECORD #
  4442.  
  4443.  
  4444.  
  4445.  
  4446. QSORT
  4447. Syntax:    QSORT a(s) [OFFSET o] [WITH i()] [,n[,j%()]]
  4448.            QSORT x$(s) WITH i() [,n[,j%()]]
  4449. Action:    Sorts  the elements of an array.  's' can be  a  minus 
  4450.            sign or a plus sign,  indicating an ascending  sort(+) 
  4451.            or a descending sort(-),  the default being ascending. 
  4452.            The  parameter 'n' specifies that only the  first  'n' 
  4453.            elements  are to be sorted.  (Depends on OPTION  BASE) 
  4454.            whether 0 or 1. If n=-1, then all elements are sorted.
  4455.            When  a further array is specified,  then  that  array 
  4456.            will be sorted along with the first array.
  4457.            OFFSET   determines  how  many  characters   off   the 
  4458.            beginning shall not be considered.
  4459.            During sorting of string arrays a sorting criteria can 
  4460.            be  specified in an array of at least 256 elements  by 
  4461.            using WITH.  Without using this option, a normal ASCII 
  4462.            sort is used.
  4463.            eg:
  4464.            DIM a$(256)
  4465.            FILES "*.*" TO "liste"
  4466.            OPEN "i",#1,"liste"
  4467.            RECALL #1,a$(),-1,x%
  4468.            CLOSE #1
  4469.            QSORT a$() OFFSET 13,x%
  4470.            OPEN "o",#1,"con:"
  4471.            STORE #1,a$(),x%
  4472.            CLOSE
  4473.            Saves the directory as 'LISTE', then reloads the file, 
  4474.            sorts the array, not on name but on file length.
  4475.            DIM x%(20)
  4476.            PRINT "Unsorted:        ";
  4477.            FOR i%=0 TO 10
  4478.              x%(i%)=RAND(9)+1
  4479.              PRINT x%(i%);"  ";
  4480.            NEXT i%
  4481.            PRINT
  4482.            '
  4483.            QSORT x%(),11
  4484.            PRINT "Ascending sort:  ";
  4485.            FOR i%=0 TO 10
  4486.              PRINT x%(i%);"  ";
  4487.            NEXT i%
  4488.            PRINT
  4489.            '
  4490.            QSORT x%(-),11
  4491.            PRINT "Descending sort: ";
  4492.            FOR i%=0 TO 10
  4493.              PRINT x%(i%);"  ";
  4494.            NEXT i%
  4495.            PRINT
  4496.          
  4497.  
  4498.  
  4499. QUIT
  4500. Syntax:    QUIT[n]
  4501. Action:    Terminate the program and leave GFA Basic.
  4502.            Returns  a  two byte integer to  the  calling  routine 
  4503.            (normally the desktop).
  4504.  
  4505.   
  4506.  
  4507. RAD
  4508. Syntax:    RAD(degrees)
  4509. Action:    Converts  from  degrees  to  radians.  (equivalent  to 
  4510.            x*PI/180).
  4511.            See also DEG
  4512.            
  4513.  
  4514.  
  4515. RAND
  4516. Syntax:    RAND(y)
  4517. Action:    Produces a 16 bit random integer in the range 0 to  y-
  4518.            1. Where y is an integer max value &HFFFF.
  4519.  
  4520.  
  4521. RANDOM
  4522. Syntax:    RANDOM(x)
  4523. Action:    Returns a random integer between 0 (inclusive) and
  4524.            'x' (exclusive).
  4525.  
  4526.  
  4527.  
  4528. RANDOMIZE
  4529. Syntax:    RANDOMIZE [y]
  4530. Action:    Initialises  the  random number  generator  [with  the 
  4531.            value y].
  4532.  
  4533.  
  4534.  
  4535. RBOX
  4536. Syntax:    RBOX x,y,x1,y1
  4537. Action:    Draws a rectangle with rounded corners from the two
  4538.            diagonally opposite corner points 'x,y' and 'x1,y1'
  4539.            See also BOX, PBOX, PRBOX.
  4540.  
  4541.  
  4542.  
  4543. RCALL
  4544. Syntax:    RCALL addr,reg%()
  4545. Action:    Calls  an assembler routine (similar to  C:  or  CALL) 
  4546.            with pre-allocated values in the registers.
  4547.            The integer array reg% must have 16 elements and holds 
  4548.            the values.  At the end of the routine, the values are 
  4549.            also returned in the array.
  4550.            Data registers d0 to d7    --->reg%(0) to reg%(7)
  4551.            Address registers a0 to a6 --->reg%(8) to reg%(14)
  4552.            User Stack Pointer (a7)    --->reg%(15)
  4553.  
  4554.  
  4555.  
  4556.  
  4557. RC_COPY
  4558. Syntax:    RC_COPY s_adr,sx,sy,sw,sh TO d_adr,dx,dy[,m]
  4559. Action:    Copies  rectangular screen sections between  areas  of 
  4560.            memory.
  4561.            s_adr    source address
  4562.            sx,sy    top left corner of source rectangle
  4563.            sw,sh    width & height  "   "        "
  4564.            d_adr    destination address
  4565.            dx,dy    destination x and y coordinates
  4566.            m        optional mode (see PUT for modes).
  4567.  
  4568.  
  4569.  
  4570. RC_INTERSECT
  4571. Syntax:    y%=RC_INTERSECT(x1,y1,w1,h1,x2,y2,w2,h2)
  4572. Action:    Detects whether two rectangles overlap. The rectangles 
  4573.            being  specified  by the coordinates of the  top  left 
  4574.            corner(x,y)  and their width & height  (w,h).  
  4575.            Returns TRUE (-1) if they do overlap and the variables 
  4576.            x2,y2,w2,h2 contain the size of the common rectangle.
  4577.  
  4578.  
  4579.  
  4580. READ
  4581. Syntax:    READ var[,var1, ...] 
  4582. Action:    Reads values from a DATA command and assigns them to a
  4583.            variable 'var'. Reading is taken from the last point a 
  4584.            RESTORE was done (if any).
  4585.  
  4586.  
  4587.  
  4588. RECALL
  4589. Syntax:    RECALL #i,x$(),n[TO m],x
  4590. Action:    Inputs n lines from a text file to the array x$().  If 
  4591.            n=-1  all  available lines are read.  x  contains  the 
  4592.            number of lines read.
  4593.  
  4594.  
  4595. RECORD
  4596.       
  4597.  
  4598.  
  4599. RELSEEK
  4600. Syntax:       RELSEEK [#]N,X
  4601. Action:   Moves tINT
  4602.            '
  4603.            QSORT x%(-),11
  4604.            PRINT "Descending sort: ";
  4605.            FOR i%=0 TO 10
  4606.              PRINT x%(i%);"  ";
  4607.            NEXT i%
  4608.            PRINT
  4609.          
  4610.  
  4611.  
  4612. QUIT
  4613. Syntax:    QUIT[n]
  4614. Action:    Terminate the program and leave GFA Basic.
  4615.            Returns  a  two byte integer to  the  calling  routine 
  4616.            (normally the desktop).
  4617.  
  4618.   
  4619.  
  4620. RAD
  4621. Syntax:    RAD(degrees)
  4622. Action:    Converts  from  degrees  to  radians.  (equivalent  to 
  4623.            x*PI/180).
  4624.            See also DEG
  4625.            
  4626.  
  4627.  
  4628. RAND
  4629. Syntax:    RAND(y)
  4630. Action:    Produces a 16 bit random integer in the range 0 to  y-
  4631.            1. Where y is an integer max value &HFFFF.
  4632.  
  4633.  
  4634. RANDOM
  4635. Syntax:    RANDOM(x)
  4636. Action:    Returns a random integer between 0 (inclusive) and
  4637.            'x' (exclusive).
  4638.  
  4639.  
  4640.  
  4641. RANDOMIZE
  4642. Syntax:    RANDOMIZE [y]
  4643. Action:    Initialises  the  random number  generator  [with  the 
  4644.            value y].
  4645.  
  4646.  
  4647.  
  4648. RBOX
  4649. Syntax:    RBOX x,y,x1,y1
  4650. Action:    Draws a rectangle with rounded corners from the two
  4651.            diagonally opposite corner points 'x,y' and 'x1,y1'
  4652.            See also BOX, PBOX, PRBOX.
  4653.  
  4654.  
  4655.  
  4656. RCALL
  4657. Syntax:    RCALL addr,reg%()
  4658. Action:    Calls  an assembler routine (similar to  C:  or  CALL) 
  4659.            with pre-allocated values in the registers.
  4660.            The integer array reg% must have 16 elements and holds 
  4661.            the values.  At the end of the routine, the values are 
  4662.            also returned in the array.
  4663.            Data registers d0 to d7    --->reg%(0) to reg%(7)
  4664.            Address registers a0 to a6 --->reg%(8) to reg%(14)
  4665.            User Stack Pointer (a7)    --->reg%(15)
  4666.  
  4667.  
  4668.  
  4669.  
  4670. RC_COPY
  4671. Syntax:    RC_COPY s_adr,sx,sy,sw,sh TO d_adr,dx,dy[,m]
  4672. Action:    Copies  rectangular screen sections between  areas  of 
  4673.            memory.
  4674.            s_adr    source address
  4675.            sx,sy    top left corner of source rectangle
  4676.            sw,sh    width & height  "   "        "
  4677.            d_adr    destination address
  4678.            dx,dy    destination x and y coordinates
  4679.            m        optional mode (see PUT for modes).
  4680.  
  4681.  
  4682.  
  4683. RC_INTERSECT
  4684. Syntax:    y%=RC_INTERSECT(x1,y1,w1,h1,x2,y2,w2,h2)
  4685. Action:    Detects whether two rectangles overlap. The rectangles 
  4686.            being  specified  by the coordinates of the  top  left 
  4687.            corner(x,y)  and their width & height  (w,h).  
  4688.            Returns TRUE (-1) if they do overlap and the variables 
  4689.            x2,y2,w2,h2 contain the size of the common rectangle.
  4690.  
  4691.  
  4692.  
  4693. READ
  4694. Syntax:    READ var[,var1, ...] 
  4695. Action:    Reads values from a DATA command and assigns them to a
  4696.            variable 'var'. Reading is taken from the last point a 
  4697.            RESTORE was done (if any).
  4698.  
  4699.  
  4700.  
  4701. RECALL
  4702. Syntax:    RECALL #i,x$(),n[TO m],x
  4703. Action:    Inputs n lines from a text file to the array x$().  If 
  4704.            n=-1  all  available lines are read.  x  contains  the 
  4705.            number of lines read.
  4706.            The  optional parameter TO will read in the  start  of 
  4707.            the file to the named elements of the array.
  4708.            eg.
  4709.            DIM a$(20)
  4710.            FOR n=0 TO 19
  4711.              a$(n)="Line # "+STR$(n)
  4712.            NEXT n
  4713.            OPEN "o",#1,"test"
  4714.            STORE #1,a$()
  4715.            CLOSE
  4716.            DIM b$(20)
  4717.            OPEN "i",#1,"test"
  4718.            RECALL #1,b$(),12 TO 15,x
  4719.            'or RECALL #1,b$(),-1,x
  4720.            CLOSE
  4721.            PRINT x
  4722.            FOR n=0 TO 20
  4723.              PRINT b$(n)
  4724.            NEXT n
  4725.  
  4726. See Also:  STORE
  4727.  
  4728.  
  4729.  
  4730. RECORD
  4731. Syntax:    RECORD #n,r
  4732. Action:    Sets  the  number of the next record to br read  or  stored 
  4733.            with GET or PUT.
  4734.  
  4735. Example:   RECORD #1,15
  4736.  
  4737. See Also:  FIELD,GET#, PUT#, SEEK
  4738.  
  4739.  
  4740.       
  4741. RELSEEK
  4742. Syntax:    RELSEEK [#]n,x
  4743. Action:    Moves the random access file pointer forward (+X) or
  4744.            backwards (-X) 'X' number of bytes.
  4745.  
  4746.  
  4747. REM
  4748. Syntax:    REM remark
  4749. Action:    Whatever follows a REM coomand on a particular line
  4750.            is ignored by Basic. ' is synonoymous with REM.
  4751.  
  4752. Example:   REM This is a comment
  4753.  
  4754.  
  4755.  
  4756. RENAME
  4757. Syntax:    RENAME old$ AS new$
  4758. Action:    Renames a file.
  4759.  
  4760.  
  4761.  
  4762. REPEAT...UNTIL
  4763. Syntax:    REPEAT
  4764.            UNTIL end
  4765. Action:    Creates a pre-defined loop. The section of the program
  4766.            between repeat and until is repeated continuously until 
  4767.            the condition is fulfilled.
  4768.  
  4769. Example:   REPEAT 
  4770.            UNTIL MOUSEK       'Waits for mouse key to be pressed.
  4771.  
  4772.  
  4773.  
  4774. RESERVE
  4775. Syntax:    RESERVE n
  4776. Action:    Increases or decreases the memory used by basic
  4777.            'n' is a numeric expression which determines how big
  4778.            FRE(0) should be after this command. (see HIMEM, EXEC)
  4779.  
  4780. Example:   RESERVE 2560
  4781.            EXEC 0,"\PROGRAM.PRG","",""
  4782.            RESERVE
  4783.            
  4784.            2560  bytes  are  reserved and PROGRAM.PRG  is  loaded  and 
  4785.            started. After running the reserved space is restored.
  4786.  
  4787.            Memory can be reserved in blocks of 256 bytes.
  4788.            If  n  is  negative then the whole of the  free  memory  is 
  4789.            reserved.
  4790.  
  4791.  
  4792. RESTORE
  4793. Syntax:    RESTORE [label]
  4794. Action:    Positions the data pointer for READ. 
  4795.            Places the data pointer at the beginning, or behind the
  4796.            label names 'label'
  4797.            'label' can be any list of characters and can contain
  4798.            digits, letters, underscore and full stops.  Unlike
  4799.            other variable names it can begin with a digit.
  4800.  
  4801.  
  4802. RESUME
  4803. Syntax:    RESUME    RESUME NEXT    RESUME label
  4804. Action:    The  RESUME command is only meaningful with  error  capture 
  4805.            (ON ERROR GOSUB) where it allows a reaction to an error.
  4806.  
  4807.            RESUME repeats the erroneous command.  
  4808.            RESUME NEXT resumes program execution after an incorrect 
  4809.            command.
  4810.            RESUME 'label' branches to the 'label'.
  4811.            If a fatal error occurs only RESUME 'label' is possible
  4812.  
  4813. Example:   ON ERROR GOSUB error_trap
  4814.            ERROR 5
  4815.            PRINT "and again..."
  4816.            ERROR 5
  4817.            PRINT "is not reached."
  4818.            '
  4819.            PROCEDURE error_trap
  4820.                PRINT "OK, error intercepted"
  4821.                RESUME NEXT
  4822.            RETURN
  4823.  
  4824.  
  4825.  
  4826. RETURN
  4827. Syntax:    RETURN
  4828. Action:    Terminates a sub-routine
  4829.  
  4830.  
  4831. Syntax:    RETURN x
  4832. Action:    If  the command RETURN is reached during program  ececution 
  4833.            and  is  within a FUNCTION...ENDFUNC  execution,  then  the 
  4834.            value given after it is returned.
  4835.  
  4836.  
  4837. RIGHT$
  4838. Syntax:    RIGHT$(string[,n])
  4839. Action:    Returns the last characters or 'n' number of characters
  4840.            (from the right) of a character string 'string'
  4841. Example:   PRINT RIGHT$"Hello GFA",3)   'PRINTS GFA
  4842.            
  4843.  
  4844.  
  4845. RINSTR
  4846. Syntax:    RINSTR(a$,b$)
  4847.            RINSTR(a$,b$,[x])
  4848.            RINSTR([x],a$,b$)
  4849. Action:    Operates in same way as INSTR except that search begins  at 
  4850.            the right end of a$.
  4851.  
  4852.  
  4853.         
  4854. RMDIR
  4855. Syntax:    RMDIR "directory name"
  4856. Action:    Deletes empty directories
  4857.  
  4858.  
  4859.  
  4860. RND
  4861. Syntax:    RND [(x)]
  4862. Action:    Returns a random number between 0 and 1
  4863.  
  4864.            The optional parameter (x) is disregarded, and  returns
  4865.            a random number between 0 (inclusive) and 1 (exclusive)
  4866.  
  4867. ROL
  4868. Syntax:    ROL(x,y)
  4869.            ROL&(x,y)
  4870.            ROL|(x,y)
  4871. Action:    Rotates a bit pattern left.
  4872.  
  4873.  
  4874. ROR
  4875. Syntax:    ROR(x,y)
  4876.            ROR&(x,y)
  4877.            ROR|(x,y)
  4878. Action:    Rotates a bit pattern right.
  4879.  
  4880.  
  4881. ROUND
  4882. Syntax:    ROUND(x[,n])
  4883. Action:    Rounds off the numeric expression x.
  4884.  
  4885. Example:   y=ROUND(-1.2)
  4886.            PRINT y,ROUND(1.7)
  4887.  
  4888.  
  4889. RSET
  4890. Syntax:    RSET a$=b$
  4891. Action:    Moves a string expression, right justified to a string.
  4892. See Also:  LSET,MID$
  4893.  
  4894.  
  4895. The  following  commands  are part  of  the  Resource  Library.  These 
  4896. routines provide the creation of a graphical user interface.  The full 
  4897. descriptions  of  these  functions  are  beyond  the  scope  of  these 
  4898. abreviated  manual.  A full description is contained within  the  full 
  4899. GFA-BASIC Reference manual and also the GFA-BASIC Software Development 
  4900. Book.
  4901.  
  4902.  
  4903. RSRC_FREE
  4904. Syntax:    ~RSRC_FREE(0)
  4905. Action:    This  function  releases  the  memory  space  reserved   by 
  4906.            RSRC_LOAD. 
  4907.            Returns 0 if an error.
  4908.  
  4909.  
  4910. RSRC_GADDR
  4911. Syntax:    ~RSRC_GADDR(type,index,addr)
  4912. Action:    This   function  determines  the  address  of  a   resource 
  4913.            structure   after  it  has  been  loaded  with   RSRC_LOAD. 
  4914.            Depending  on the version of GEM,  this function  may  only 
  4915.            work for Object trees and Alert boxes.
  4916.            Returns 0 if an error.
  4917.  
  4918.            Type:0   OBJECT TREE
  4919.                 1   OBJECT
  4920.                 2   TEDINFO
  4921.                 3   ICONBLK
  4922.                 4   BITBLK
  4923.                 5   STRING
  4924.                 6   image data
  4925.                 7   obspec
  4926.                 8   te_ptext
  4927.                 9   te_ptmplt
  4928.                10   te_pvalid
  4929.                11   ib_pmask
  4930.                12   ib_pdata
  4931.                13   pb_ptext
  4932.                14   bi_pdata
  4933.                15   ad_frstr
  4934.                16   ad_frimg
  4935.  
  4936.            Index:   The   number  of  the  object  whose  address   is 
  4937.                     required, counting objects of that type one by one 
  4938.                     from the beginning of the resource file.
  4939.  
  4940.            addr:    The required address.
  4941.  
  4942. Example:   ~RSRC_GADDR(0,0,TREE%)
  4943.  
  4944.  
  4945.  
  4946. RSRC_LOAD
  4947. Syntax:    RSRC_LOAD(name$)
  4948. Action:    This  function reserves memory and loads a  resource  file. 
  4949.            Then  internal  pointers are set and  the  co-ordinates  of 
  4950.            characters converted into pixel format.
  4951.  
  4952. Example:   ~RSRC_LOAD("TEST.RSC")
  4953.  
  4954.  
  4955.    
  4956. RSRC_OBFIX
  4957. Syntax:    RSRC_OBFIX(tree,obj)
  4958. Action:    This function converts the coordinates of an object  within 
  4959.            a  tree,  from character coordinates to pixel  coordinates, 
  4960.            taking  into account the current screen resolution.  It  is 
  4961.            automatically called by RSRC_LOAD,  but must be used if the 
  4962.            object is created direct in memory by POKE.
  4963.  
  4964.            tree:    address of the object tree
  4965.            obj:     object number 
  4966.  
  4967.  
  4968.  
  4969. RSRC_SADDR
  4970. Syntax:    RSRC_SADDR(type,index,addr)
  4971. Action:    This function sets the address of an object.
  4972.            Returns 0 if an error.
  4973.  
  4974.            type:    type of structure
  4975.            index:   the number of the object
  4976.            addr     address
  4977.  
  4978.  
  4979.  
  4980. RUN
  4981. Syntax:    RUN(a$)    
  4982. Action:    Runs the program in memory,  or if a file name is  supplied 
  4983.            will load and then run the appropriate program.
  4984.  
  4985. Example:   RUN "A:\PROGRAM.GFA"
  4986.  
  4987.  
  4988.  
  4989. SAVE   
  4990. PSAVE  
  4991. Syntax:    SAVE a$
  4992.            PSAVE a$
  4993. Action:    Saves a program file (psave is with list protection)
  4994.            'file name' is the name of the program.
  4995.            Programs which are saved with psave are not listed but
  4996.            run straight after the command 'load' is given.
  4997.  
  4998.  
  4999. SEEK
  5000. Syntax:    SEEK [#]n,x
  5001. Action:    Sets the file pointer on the byte number 'x' of file #n
  5002.            'n' is an integer expression between 0 and 99 which
  5003.            refers to the channel number.  'x' has a value (total)
  5004.            either greater or smaller than the length of the file
  5005.            addressed.
  5006.  
  5007.  
  5008.  
  5009. SCRP_READ
  5010. Syntax:    SCRP_READ(path$)
  5011. Action:    This  function reads data,  left there by another  program, 
  5012.            from a small internal buffer,  thus allowing  communication 
  5013.            between GEM programs. Returns 0 if an error.
  5014. Example:   SCRP_READ(a$)
  5015. See Also:  SCRP_WRITE
  5016.  
  5017.  
  5018.  
  5019. SCRP_WRITE
  5020. Syntax:    SCRP_WRITE(path$)
  5021. Action:    This  function writes data,  into a small internal  buffer, 
  5022.            thus allowing communication between GEM programs. 
  5023. Example:   SCRP_WRITE("A:\PROGRAM.TXT")
  5024. See Also:  SCRP_READ
  5025.  
  5026.  
  5027.  
  5028. SDPOKE
  5029. Syntax:    SDPOKE x,y
  5030. Action:    Allows  DPOKE  to  operate  in  supervisor  mode,  so  that 
  5031.            protected address (0 to 2047) can be modified.
  5032.  
  5033.  
  5034.  
  5035. SEEK
  5036. Syntax:    SEEK #n,pos
  5037. Action:    Absolute  positioning  of data pointer  within  file.  This 
  5038.            allows  the realisation of indexed sequential file  access. 
  5039.            The  numerical expression n contains the channel number  of 
  5040.            the file.
  5041.  
  5042.  
  5043. SELECT
  5044. Syntax:    SELECT x
  5045.            CASE y [TO z] or CASE y [,z,...]
  5046.            CASE TO y
  5047.            CASE y TO
  5048.            DEFAULT
  5049.            ENDSELECT
  5050.            CONT
  5051. Action:    A conditional command which enables execution of  specified 
  5052.            program segments depending on an integer.
  5053.  
  5054.            The maximum of a CASE is 4 characters (eg CASE "A,B,C,D"
  5055.  
  5056.            The  CONT command provides a method of jumping over a  CASE 
  5057.            or DEFAULT command.
  5058.  
  5059. Example:   REPEAT
  5060.                a%=ASC(INKEY$)
  5061.                SELECT a%
  5062.                CASE 65 TO 90
  5063.                     PRINT "CAPITAL LETTER"
  5064.                CASE 97 TO 122
  5065.                     PRINT "LOWER CASE LETTER"
  5066.                DEFAULT
  5067.                     PRINT "NOT CAPITAL OR LOWER CASE"
  5068.                ENDSELECT
  5069.            UNTIL a%=27
  5070.            
  5071.  
  5072. SETCOLOR
  5073. Syntax:    SETCOLOR i,r,g,b      
  5074.            SETCOLOR i,n
  5075. Action:    Defines the colours red, green and blue for the colour
  5076.            register 'i'.
  5077.            'r,g,b' are the levels of the three primary colours
  5078.            from 0 to 7.
  5079.            Another way of defining colours is to use the value 'n'
  5080.            where n=r*256+g*16+b
  5081. See Also:  COLOR,VSETCOLOR
  5082.  
  5083.  
  5084.  
  5085. SETDRAW    See DRAW command.
  5086.  
  5087. SETMOUSE
  5088. Syntax:    SETMOUSE mx,my,[,mk]
  5089. Action:    The  SETMOUSE command permits the positioning of the  mouse 
  5090.            cursor under program control. Tje optional parameter mk can 
  5091.            simulate the mouse button being pressed or released.
  5092.  
  5093. Example:   FOR i%=0 TO 300
  5094.                HIDEM
  5095.                SETMOUSE i%,i%
  5096.                PLOT MOUSEX,MOUSEY
  5097.                SHOWM
  5098.                PAUSE 2
  5099.            NEXT i%                   
  5100.  
  5101.  
  5102. SETTIME
  5103. Syntax:    SETTIME time$,date$
  5104. Action:    Sets the time and the date.
  5105.            
  5106.            time$ is a string expression which contains the
  5107.            time.  hours, minutes and second can be displayed. The
  5108.            colons are optional as two digits have to be entered.
  5109.            The seconds can also be left out.             
  5110.            
  5111.            date$ is a character string expression for the
  5112.            date.  It must always contain:  day, month and year,
  5113.            each separated by a full stop.
  5114.  
  5115. Example:   PRINT DATE$,TIME$
  5116.            SETTIME "17:30:30","27.10.1952"
  5117.            PRINT DATE$,TIME$
  5118.  
  5119.  
  5120.  
  5121. SGET
  5122. Syntax:    SGET screen$
  5123. Action:    Fast reading of the entire screen area into a string
  5124.            variable. 
  5125. Example:   PCIRCLE 100,100,50
  5126.            SGET b$
  5127.            ~INP(2)
  5128.            CLS
  5129.            ~INP(2)
  5130.            SPUT b$
  5131. See Also:  SPUT, GET, PUT and BMOVE
  5132.  
  5133.  
  5134.  
  5135. SGN
  5136. Syntax:    SGN(x)
  5137. Action:    Ascertains whether 'x' is positive, negative or 0
  5138.            'x' can be any numeric expression.  SGN(x) is the
  5139.            mathematic sign function.
  5140.  
  5141.  
  5142. The  following  commands  are part of the  Shell  Library  and  enable 
  5143. an  application  to  call  another,   preserving  both  the   original 
  5144. application and its environment.
  5145. The full descriptions of these functions are beyond the scope of these 
  5146. abreviated  manual.  A full description is contained within  the  full 
  5147. GFA-BASIC Reference manual.
  5148.  
  5149.  
  5150.  
  5151. SHEL_ENVRN
  5152. Syntax:    SHEL_ENVRN(addr,search$)
  5153. Action:    This function determines the values of variables in the GEM 
  5154.            environment.
  5155.            Returns 1.
  5156.  
  5157.            search$: The string to be sought
  5158.            addr:    address of the byte following the string
  5159.  
  5160. Example:   PRINT SHEL_ENVRN(a%,"PATH")
  5161.            PRINT CHAR{a%-4}
  5162.  
  5163.            ' Displays: PATH=A:\
  5164.  
  5165.  
  5166. SHEL_FIND
  5167. Syntax:    SHEL_FIND(paths$)
  5168. Action:    This  function  searches for a file and supplies  the  full 
  5169.            file specification.  First the path on the current drive is 
  5170.            searched, then the root directory of drive A:.
  5171.  
  5172.            Returns 0 if file not found, or 1 if found.
  5173.  
  5174.            On entry:
  5175.            path$:   String contains sought after filename.
  5176.  
  5177.            On exit:
  5178.            path$:   Contains  the full file specification if the  file 
  5179.                     was found, otherwise it is unchanged.
  5180.  
  5181.  
  5182.  
  5183.  
  5184.  
  5185. SHEL_GET
  5186. Syntax:    SHEL_GET(num,x$)
  5187. Action:    This  function  reads data from  the  GEMDOS  environmental 
  5188.            string  buffer (into which the file DESKTOP.INF is read  on 
  5189.            start up).
  5190.  
  5191.            Returns 0 if an error.
  5192.  
  5193.            num:     number of bytes to be read
  5194.            x$:      string to contain data
  5195.  
  5196. Example:   SHEL_GET(500,x$)
  5197.            PRINT x$
  5198.  
  5199.  
  5200.  
  5201. SHEL_PUT   
  5202. Syntax:    SHEL_PUT(len,x$)
  5203. Action:    This  function  writes data into the  GEMDOS  environmental 
  5204.            string buffer.
  5205.  
  5206.            Returns 0 if an error.
  5207.  
  5208.            x$:      String containing the data to be written
  5209.            len:     number of bytes to be written
  5210.  
  5211. Example:   'Register GFA-BASIC
  5212.            ~SHEL_GET(2000,a$)
  5213.            q%=INSTR(a$,CHR$(26))
  5214.            IF q%
  5215.                a$=LEFT$(a$,q%-1)
  5216.                IF INSTR(a$,"GFABASIC.PRG")=0
  5217.                     a$=s$+"#G 03 04 A:\GFABASIC.PRG@*.GFA
  5218.                               +MKI$(&HDOA)+CHR$(26)
  5219.                     ~SHEL_PUT(LEN(a$),a$)
  5220.                ENDIF
  5221.            ENDIF
  5222.  
  5223.            '  Registers that all .GFA files cause GFABASIC.PRG  to  be 
  5224.            loaded when clicked on.
  5225.  
  5226.  
  5227.  
  5228. SHEL_READ
  5229. Syntax:    SHEL_READ(cmd_string$,tail_string$)
  5230. Action:    This function allows the program to identify the command by 
  5231.            which   it   was  invoked  and  supplies   the   name,   eg 
  5232.            GFABASIC.PRG, and the command line if any.
  5233.  
  5234.            cmd_string$        string  variable to contain the  command 
  5235.                               line.
  5236.  
  5237.            tail_string$       string variable to contain name.
  5238.  
  5239.  
  5240.  
  5241.  
  5242. SHEL_WRITE
  5243. Syntax:    SHEL_WRITE(prg,grf.gem.cmd$,nam$)
  5244. Action:    This  function informs the AES that another application  is 
  5245.            to  be  started after the current one  has  terminated.  In 
  5246.            contrast to p_exec (GEMDOS 75), however the current program 
  5247.            does not remain in memory.
  5248.  
  5249.            prg:     0 Back to desktop
  5250.                     1 Load new program
  5251.            grf:     0 TOS program
  5252.                     1 Graphic application
  5253.            gem:     0 not a GEM application
  5254.                     1 GEM application
  5255.            cmd$     command line string
  5256.            nam$     name of next application
  5257.  
  5258. Example:   ~SHEL_WRITE(1,1,1,"","GFABASIC.PRG")
  5259.            
  5260.  
  5261. SHL
  5262. Syntax:    SHL(x,y)
  5263.            SHL&(x,y)
  5264.            SHL|(x,y)
  5265. Action:    Shifts a bit pattern left
  5266.  
  5267.  
  5268.  
  5269. SHOWM
  5270. Syntax:    SHOWM
  5271. Action:    Makes the mouse pointer appear.
  5272. See Also:  HIDEM
  5273.  
  5274.  
  5275.  
  5276. SHR
  5277. Syntax:    SHR(x,y)
  5278.            SHR&(x,y)
  5279.            SHR|(x,y)
  5280. Action:    Shifts a bit pattern right
  5281.  
  5282.  
  5283. SIN
  5284. Syntax:    SIN(x)
  5285. Action:    Returns the sine value of 'x'
  5286.  
  5287.  
  5288.  
  5289. SINGLE{}
  5290. Syntax:    SINGLE{x}
  5291. Action:    Reads/writes  a  4  byte floating point  variable  in  IEEE 
  5292.            single precision format.
  5293.  
  5294.  
  5295. SINQ
  5296. Syntax:    SINQ(degrees)
  5297. Action:    Returns the extrapolated sine of a numeric expression.
  5298.  
  5299.  
  5300.  
  5301. SLPOKE
  5302. Syntax:    SLPOKE x,y
  5303. Action:    Allows  LPOKE  to  operate  in  supervisor  mode,  so  that 
  5304.            protected address (0 to 2047) can be modified.
  5305.  
  5306.  
  5307. SOUND
  5308. Syntax:    SOUND chn,vol,note,octave[,dur]
  5309.            SOUND chn,vol,note,#period[,dur]
  5310. Action:    GENERATES MUSICAL NOTES
  5311.            'chn' is a 1, 2, or 3 and selects the sound channel.
  5312.            'vol' selects the volume.
  5313.            'note' is a value of 1 to 12 and selects notes:
  5314.                1=C,
  5315.                2=C#
  5316.                3=D
  5317.                4=D#
  5318.                5=E
  5319.                6=F
  5320.                7=F#
  5321.                8=G
  5322.                9=G#
  5323.                10=A
  5324.                11=A#
  5325.                12=B
  5326.            'octave' is between 1 and 8, and determines octave.
  5327.            'dur' is the time in 1/50ths of a second that GFA Basic
  5328.            has to wait before execution of the next command.
  5329.            A further possibility to choose the pitch is to enter
  5330.            'period'  prefixed by '#' instead of 'note' and 'octave'.  
  5331.            The period can be calculated from the
  5332.            frequency with:                      
  5333.  
  5334.            Period = TRUNC(125000/frequency +0.5)
  5335.  
  5336.  
  5337.  
  5338. SPACE$
  5339. Syntax:    SPACE$(x)
  5340. Action:    Creates a character string containing 'x' spaces.
  5341.  
  5342.  
  5343.  
  5344. SPC
  5345. Syntax:    SPC(n)
  5346. Action:    Produces 'n' spaces in a print command
  5347.  
  5348.  
  5349.  
  5350. SPOKE    SDPOKE    SLPOKE
  5351. Syntax:    SPOKE x,n    SDPOKE x,    SLPOKE x,n
  5352. Action:    Writes 1, 2 or 4 bytes into an area of memory which
  5353.            begins with the address 'x'
  5354.  
  5355.  
  5356. SPRITE
  5357. Syntax:    SPRITE A$[,x,y]
  5358. Action:    Puts the sprite defined in a$ at (X,Y) or, if no
  5359.            coordinates are given, deletes it.
  5360.              A$ = MKI$(X POSITION)
  5361.               + MKI$(Y POSITION)
  5362.               + MKI$(0=NORMAL OR 1=XOR MODE)
  5363.               + MKI$(SCREEN COLOUR MOSTLY 0)
  5364.               + MKI$(SPRITE COLOUR MOSTLY 1)
  5365.               + BIT PATTERN OF SCREEN AND SPRITE
  5366.  
  5367.            Unlike defmouse, the bit patterns for screen and sprite
  5368.            are not stored in separate blocks but in alternate
  5369.            words (16 bits).
  5370.            If the same sprite is put onto the screen in another
  5371.            position then the first sprite is deleted.
  5372.  
  5373.  
  5374. SPUT
  5375. Syntax:    SPUT var
  5376. Action:    Fast copying of a 32000 byte string into the screen
  5377.            area. 
  5378. See Also:  SGET, PUT, GET and BMOVE
  5379.  
  5380.  
  5381.  
  5382. SQR
  5383. Syntax:    SQR(X)
  5384. Action:    Calculates the square root of 'X'.
  5385.  
  5386.  
  5387.  
  5388. SSORT
  5389. Syntax:    SSORT a(s) {OFFSET o][WITH i()][,n[,j%()]]
  5390.            SSORT x$(s) WITH i() [,n[,j%{}]]
  5391. Action:    Sorts the elements in an array by its size using the Shell-
  5392.            Metzner method. 
  5393.            
  5394.            a()      array or string array
  5395.            i()      integer array
  5396.            j%       4byte integer array
  5397.            x$()     string array
  5398.            s        + or - or no sign
  5399.  
  5400.  
  5401.  
  5402. STE?
  5403. Syntax:    STE?
  5404. Action:    Returns -1 for STE otherwise 0
  5405.  
  5406.  
  5407.  
  5408. STICK
  5409. Syntax:    STICK m
  5410.            STICK(p)
  5411. Action:    The function STICK(p) returns the position of a joystick.
  5412.            STICK 0 causes port 0 to supply mouse information.
  5413.            STICK 1 causes port 1 to read the joystick.
  5414.  
  5415. Example:   STICK 1
  5416.            REPEAT
  5417.                direction%=STICK(0)
  5418.                fire%=STRIG(0)
  5419.                SELECT direction%
  5420.                CASE 4
  5421.                     PRINT "LEFT"
  5422.                CASE 8
  5423.                     PRINT "RIGHT"
  5424.                CASE 2
  5425.                     PRINT "DOWN"
  5426.                CASE 1
  5427.                     PRINT "UP"
  5428.                ENDSELECT
  5429.            UNTIL fire!
  5430.            WHILE STRIG(0)
  5431.            WEND
  5432.  
  5433.  
  5434.  
  5435. STOP
  5436. Syntax:    STOP
  5437. Action:    Stops execution of a program.
  5438.            Unlike the END command it does not close any files and
  5439.            by typing CONT the program will resume from the line
  5440.            following the STOP command.
  5441.  
  5442.  
  5443.  
  5444. STORE
  5445. Syntax:    STORE #i,x$()[,n[TO m]]
  5446. Action:    Fast save of a string array as a text file. The instruction 
  5447.            STORE  is  used for sending the contents of an array  to  a 
  5448.            file or data channel (elements seperated by CR/LF).
  5449.  
  5450. See Also:  RECALL
  5451.  
  5452.  
  5453.  
  5454. STR $
  5455. Syntax:    STR$(X)
  5456. Action:    Transforms the value 'X' into a character string.
  5457.  
  5458.  
  5459.  
  5460. STRING$
  5461. Syntax:    STRING$(N,string)  OR  STRING$(N,C)
  5462. Action:    Produces a string formed by repeating 'string' or
  5463.            CHR$(C) 'N' times. 'N' is a number from 0 to 32767.
  5464.  
  5465.  
  5466.  
  5467. SUB
  5468. Syntax:    SUB VAR,N
  5469. Action:    Deducts 'N' from 'VAR'. Same as VAR=VAR-N but executes
  5470.            almost twice as fast.
  5471. Example:   x=57
  5472.            SUB x,3*5
  5473.            PRINT x  'PRINTS 42
  5474.  
  5475.  
  5476. SUB()
  5477. Syntax:    SUB(x,y)
  5478. Action:    Corresponds to x-y
  5479.  
  5480. Example:   PRINT SUB(5^3,4*20+3)   'PRINTS 42
  5481.            
  5482.  
  5483.  
  5484. SUCC()
  5485. Syntax:    SUCC(n)
  5486. Action:    Determines the next higher number.
  5487. See Also:  PRED()
  5488.  
  5489.  
  5490.  
  5491. SWAP
  5492. Syntax:    SWAP var1,var2
  5493. Action:    Exchanges the values of 'var1' and 'var2'.
  5494.            The variables must be of the same type.
  5495.            When swapping array fields the dimensions are also swap
  5496.            ped.
  5497.  
  5498.  
  5499. SWAP()
  5500. Syntax:    SWAP(n)
  5501. Action:    Swaps the high and low words of a varaible.
  5502.  
  5503.  
  5504.  
  5505.  
  5506. SYSTEM
  5507. Syntax:    SYSTEM
  5508. Action:    Causes a return to the desktop, same as quit.
  5509.  
  5510.  
  5511.  
  5512.  
  5513. TAB
  5514. Syntax:    TAB(n)
  5515. Action:    Sets the tabulator to the nth column.
  5516.            Tab can only be used in conjunction with the print
  5517.            command.
  5518.            If the current position is already past 'N' then the
  5519.            tab function is set for the next line.
  5520.  
  5521.  
  5522. TAN
  5523. Syntax:    TAN(X)
  5524. Action:    Returns the tangent of 'X' (X is the angle in radians).
  5525.  
  5526.  
  5527.  
  5528. TEXT
  5529. Syntax:    TEXT X,Y, [ L, ]string
  5530. Action:    Puts a text onto the screen at graphics coordinates
  5531.            'X,Y'. The graphics can first be defined by using
  5532.            the command DEFTEXT.
  5533.  
  5534.  
  5535.  
  5536. TIME$
  5537. Syntax:    TIME$
  5538. Action:    Returns the system time as a string.
  5539.            Format: hh:mm:ss and is updated every two seconds.
  5540.  
  5541. Example:   PRINT TIME$
  5542.  
  5543.  
  5544.  
  5545. TIME$=     
  5546. Syntax:    TIME$=a$
  5547. Action:    The time can be set.
  5548.  
  5549. Example:   TIME$="20:15:30"
  5550.  
  5551.  
  5552.  
  5553. TIMER
  5554. Syntax:    t%=TIMER
  5555. Action:    TIMER suuplies the elapsed time in 1/200 seconds since  the 
  5556.            system was started.
  5557.  
  5558. Example:   t%=TIMER
  5559.            FOR i%=1 TO 2500
  5560.            NEXT i%
  5561.            PRINT (TIMER-t%)/200;" Seconds"
  5562.  
  5563.  
  5564.  
  5565. TITLEW
  5566. Syntax:    TITLEW n,"title"
  5567. Action:    Gives the window number 'n', the new title 'title'.
  5568.  
  5569.  
  5570.  
  5571.  
  5572. TOPW
  5573. Syntax:    TOPW #1
  5574. Action:    Activates the windows number n.
  5575.  
  5576.  
  5577.  
  5578.  
  5579. TOUCH
  5580. Syntax:    TOUCH[#]n
  5581. Action:    Updates the date and time stamps od a file,  giving it  the 
  5582.            current system time and date.
  5583.  
  5584. Example    OPEN "u",#1,"TEST.TXT"
  5585.            TOUCH #1
  5586.            CLOSE #1
  5587.  
  5588.  
  5589.  
  5590. TRACE$
  5591. Syntax:    TRACE$
  5592. Action:    The  variable TRACE$ contains the command which is next  to 
  5593.            be processed.
  5594.  
  5595. See Also:  TRON,TROFF
  5596.  
  5597.  
  5598.  
  5599.  
  5600. TRIM$
  5601. Syntax:    TRIM$(a$)
  5602. Action:    Removes spaces at the beginning of a string expression.
  5603.  
  5604.  
  5605.  
  5606.  
  5607. TROFF
  5608. Syntax:    TROFF
  5609. Action:    Switches the trace function off.
  5610.  
  5611.  
  5612.  
  5613. TRON
  5614. Syntax:    TRON
  5615. Action:    Switches the trace function on. This causes each command to 
  5616.            be listed on the screen.
  5617.  
  5618.  
  5619.  
  5620. TRON#
  5621. Syntax:    TRON #1    
  5622. Action:    Switches the trace function on. This causes each command to 
  5623.            be listed to the relevant channel number.
  5624.  
  5625.  
  5626.  
  5627. TRONproc
  5628. Syntax:    TRON tr_proc
  5629. Action:    A  procedure  can be specified which is called  before  the 
  5630.            execution of each command.
  5631.  
  5632.  
  5633.  
  5634. TRUE
  5635. Syntax:    TRUE
  5636. Action:    Constant 0. This is simply another way of expressing
  5637.            the value of a condition when it is true and is equal
  5638.            to zero. (see also FALSE).
  5639.  
  5640.  
  5641.  
  5642. TRUNC
  5643. Syntax:    TRUNC(X)
  5644. Action:    Returns the integer portion of 'X'.
  5645.  
  5646.  
  5647.  
  5648.  
  5649. TT?
  5650. Syntax:    TT?
  5651. Action:    Returns -1 for 68020 or 68030 processeor, otherwise 0.
  5652.  
  5653.  
  5654.  
  5655. TYPE
  5656. Syntax:    TYPE(ptr)
  5657. Action:    Determines the type of the variable at which a pointer
  5658.            is set.
  5659.            
  5660.            'ptr' is an integer expression (usually *var).
  5661.            TYPE(ptr) returns a code according to the type of
  5662.            variable to which 'ptr' is pointing.
  5663.            
  5664.                0=var  
  5665.                1=var$  
  5666.                2=var%  
  5667.                3=var!  
  5668.                4=var()  
  5669.                5=var$()
  5670.                6=var%()  
  5671.                7=var!().
  5672.  
  5673.            On errors -1 is returned.
  5674.  
  5675.  
  5676.  
  5677. UPPER$
  5678. Syntax:    A$="basic"
  5679.            PRINT UPPER$(A$)
  5680.            PRINT UPPER$("1a")
  5681. Action:    Transforms all lower case letters of a string to upper
  5682.            case. Any non letter characters are left unchanged.
  5683.  
  5684.  
  5685.  
  5686. V:
  5687. Syntax:    V:x
  5688. Action:    Returns the address of a variable or strings or elements of 
  5689.            an array.
  5690.  
  5691.  
  5692.  
  5693. VAL
  5694. Syntax:    VAL(X$)
  5695. Action:    Transforms 'X$' into a number, as far as possible.
  5696.            In the case of a purely alphabetical string the value
  5697.            0 is returned.
  5698.  
  5699.  
  5700. VAL?
  5701. Syntax:    VAL?(X$)
  5702. Action:    Determines the number of characters starting at the
  5703.            beginning of a string that can be converted into a
  5704.            numerical value with VAL.
  5705.  
  5706.  
  5707.  
  5708. VAR
  5709. Syntax:    name([a,b,...] VAR x,y..a(),b(),...)
  5710. Action:    Declaration  part of the parameter list for a PROCEDURE  or 
  5711.            FUNCTION.
  5712.  
  5713. Example:   sum(13,12,a)
  5714.            sum(7,9,b)
  5715.            PRINT a,b
  5716.            '
  5717.            PROCEDURE sum(x,y,VAR z)
  5718.                z=x+y
  5719.            RETURN
  5720.  
  5721.  
  5722.  
  5723. VARIAT()
  5724. Syntax:    VARIAT(n,k)
  5725. Action:    Returns the number of permutations of n elements to the kth 
  5726.            order without repitition.
  5727.  
  5728. Example:   PRINT VARIAT(6,2)       'prints 30
  5729.  
  5730. See Also:  FACT(), COMBIN()
  5731.  
  5732.  
  5733.  
  5734.  
  5735. VARPTR
  5736. Syntax:    VAPTR(var)
  5737. Action:    Determines the address or starting address of a
  5738.            variable 'var'.
  5739.  
  5740.  
  5741.  
  5742. VDIBASE
  5743. Syntax:    VDIBASE
  5744. Action:    Dangerous pokes!
  5745.            Determines the address above the area used by basic
  5746.            and the required tables and variables.
  5747.            This is the point from which this version of gem keeps
  5748.            parameters for the vdi (text style, clipping etc.).
  5749.            By use of peek and poke in this area, various effects
  5750.            (and nasty crashes!) can be obtained.
  5751.  
  5752.  
  5753.  
  5754. VDISYS
  5755. Syntax:    VDISYS[opcode [,c_int,c_pts[,subopc]]]
  5756. Action:    The  VDI function with function code opcode is  called.  If 
  5757.            opcode is not specified,  then the function code must, like 
  5758.            other  parameters,  be  placed in the  control  block  with 
  5759.            DPOKE.
  5760.  
  5761.            The  depth  of  this command is betond the  scope  of  this 
  5762.            abbreviated manual.
  5763.  
  5764.  
  5765.  
  5766. VOID
  5767. Syntax:    VOID exp
  5768. Action:    This command performs a calculation and forgets the
  5769.            result. Sounds silly but there are occasions when this
  5770.            command is required, eg. forced garbage collection
  5771.            (fre(0)), waiting for a keystroke (inp(2)), or calling
  5772.            various bios, xbios, gemdos or c: routines which have
  5773.            no parameters.
  5774.  
  5775.  
  5776.  
  5777. VQT_EXTENT
  5778. Syntax:    VQT_EXTENT(text$[,x1,y1,x2,y2,x3,y3,x4,y4])
  5779. Action:    Returns  the corner coordinates of a rectangle  which  will 
  5780.            surround the text in text$.  The coordinates can either  be 
  5781.            found in the variables x1,y1 to x4,y4, or in PTSOUT(7). The 
  5782.            corner pointers are numbered in a clockwise direction.
  5783.  
  5784. Example:   INPUT text$
  5785.            CLS
  5786.            ATEXT 100,25,2,text$
  5787.            ~VQT_EXTENT(text$,x1,y1,x2,y2,x3,y3,x4,y4)
  5788.            BOX x4+100,y4+25,x2+00,y2+25
  5789.  
  5790.  
  5791.  
  5792. VQT_NAME
  5793. Syntax:    VQT_NAME(i,font_name$)
  5794. Action:    Supplies  the handle of the font with  the  indentification 
  5795.            number  i and places the name of the loaded  character  set 
  5796.            into the string variable font_name$.
  5797.  
  5798.  
  5799.  
  5800.  
  5801. VSETCOLOR
  5802. Syntax:    VSETCOLOR colour,red,green,blue
  5803.            VSETCOLOR colour,composite
  5804. Action:    Due to an error in TOS, SETCOLOR does not correspond to the 
  5805.            registers used by COLOR. VSETCOLOR is used to overcome this 
  5806.            problem.
  5807.  
  5808.            Low Resolution
  5809.            SETCOLOR     0 1 2 3 4 5 6 7 8  9 10 11 12 13 14 15
  5810.            VSETCOLOR    0 2 3 6 4 7 5 8 9 10 11 14 12 15 13  1
  5811.  
  5812.            Medium Resolution
  5813.            SETCOLOR     0 1 2 3
  5814.            VSETCOLOR    0 2 3 1
  5815.  
  5816.            High Resolution
  5817.            SETCOLOR 0,even = VSETCOLOR 0,0
  5818.            SETCOLOR 0,odd  = VSETCOLOR 0.&H777
  5819.  
  5820.            The  term  composite  is calculated the same  way  as  with 
  5821.            SETCOLOR: ie rgb=(r*256)+(g*16)+b
  5822.  
  5823.  
  5824.  
  5825. VST_LOAD_FONTS
  5826. Syntax:    VST_LOAD_FONTS(x)
  5827. Action:    Loads   the   additional  character   sets   specified   in 
  5828.            ASSIGN.SYS, and the number of loaded fonts is returned.
  5829.  
  5830. Example:   RESERVE 25600
  5831.            num_fonts%=VST_LOAD_FONTS(0)
  5832.            face%=VQT_NAME(num_fonts%,fonts$)
  5833.            FOR i%=1 to num_fonts%
  5834.                DEFTEXT,,,,face%
  5835.                TEXT 80,80,"This is the "+font$+" font."
  5836.                ~INP(2)
  5837.            NEXT i%
  5838.            ~VST_UNLOAD_FONTS(0)
  5839.            RESERVE
  5840.  
  5841.  
  5842. VST_UNLOAD_FONTS
  5843. Syntax:    VST_UNLOAD_FONTS(x)
  5844. Action:    Removes   the   character  set   previously   loaded   with 
  5845.            VST_LOAD_FONTS from memory.
  5846.  
  5847.  
  5848.  
  5849. VSYNC
  5850. Syntax:    VSYNC
  5851. Action:    Enables synchronization with the screen by waiting
  5852.            until the next vertical sync pulse is received - helps
  5853.            avoid flickering of the screen during animation when  using 
  5854.            GET and PUT.
  5855.  
  5856. Example:   t%=TIMER
  5857.            FOR i%=1 TO 100
  5858.                VSYNC
  5859.            NEXT i%
  5860.            PRINT SUB(TIMER,t%)/200
  5861.            ' PRINTS the time for 100 scans of screen.
  5862.  
  5863.  
  5864. VTAB
  5865. Syntax:    VTAB line
  5866. Action:    VTAB  positions the cursor to the specified column or  line 
  5867.            number . Note that the cursor columns and lines are counted 
  5868.            from 1, not 0.
  5869.  
  5870. See Also:  HTAB, PRINT AT, TAB
  5871.  
  5872.  
  5873. The  following  VDI  Workstation  routines  and  functions  are   only 
  5874. available  if  GDOS  has been booted and a valid  ASSIGN.SYS  file  is 
  5875. available.  In depth documentation on the VDI routines are beyond  the 
  5876. scope of this abbreviated manual.  Further information can be found in 
  5877. the full GFA-BASIC Interpreter Manual or Software Development Book.
  5878.  
  5879.  
  5880.  
  5881. V_CLRWK
  5882. Syntax:    V_CLRWRK()
  5883. Action:    This  function clears the output buffer.  For  example  the 
  5884.            screen or the printer buffer is cleared.
  5885.  
  5886.  
  5887.  
  5888. V_CLSVWK
  5889. Syntax:    V_CLSVWK(id)
  5890. Action:    Closes a virtual workstation opened with V_OPNVWK.
  5891.  
  5892.  
  5893.  
  5894. V_CLSWK
  5895. Syntax:    V_CLSWK()
  5896. Action:    Closes the current workstation opened with V_OPNWK().
  5897.  
  5898.  
  5899.  
  5900. V_OPNVWK
  5901. Syntax:    V_OPNVWK(id,1,1,1,1,1,1,1,1,1,2)
  5902. Action:    Opens  a virtual screen driver and supplies the handle  for 
  5903.            the specified device id.
  5904.  
  5905.  
  5906.  
  5907. V_OPNWK
  5908. Syntax:    V_OPNWK(id)
  5909. Action:    Supplies the handle for the specified device id.
  5910.  
  5911.  
  5912.  
  5913. V_UPDWK
  5914. Syntax:    V_UPDWK()
  5915. Action:    Sends buffered graphic instructions to the attached device.
  5916.  
  5917.  
  5918.  
  5919. V~H
  5920. Syntax:    V~H
  5921. Action:    Returns the internal VDI handle of GFA-BASIC.
  5922.  
  5923.            V~H=x    'Sets internal VDI handle
  5924.  
  5925.            V~H=-1   'Sets VDI handle to value from V_OPNVWK()
  5926.  
  5927.  
  5928. W:
  5929. Syntax:    W:x
  5930. Action:    Allows  passing of numerical expressions to  the  operating 
  5931.            system and C routines as a word (2-byte).
  5932.  
  5933. See Also:  L:
  5934.  
  5935.  
  5936.  
  5937. WAVE
  5938. Syntax:    WAVE voice,env,form,per,del
  5939. Action:    Produces noises from the three sound channels.
  5940.            WAVE 0,0 switches off all sound channels.
  5941.  
  5942.            voice:   Any  channel  or combination of  channels  may  be 
  5943.                     activated  simultaneously.  The value of voice  is 
  5944.                     256 * by the period.
  5945.  
  5946.                     1 Channel 1
  5947.                     2 Channel 2
  5948.                     4 Channel 3
  5949.                     8 Noise (Channel 1)
  5950.                    16 Noise (Channel 2)
  5951.                    32 Noise (Channel 3)
  5952.  
  5953.            env:     Specifies  the channels for which the wnvelope  is 
  5954.                     to be active.
  5955.  
  5956.                     1 Channel 1
  5957.                     2 Channel 2
  5958.                     3 Channel 3
  5959.  
  5960.            form:    Envelope shape
  5961.  
  5962.                     0 - 3     As 9
  5963.                     4 - 7     As 15
  5964.                     8         Falling sawtooth
  5965.                     9         Falling linear
  5966.                     10        Triangle falling
  5967.                     11        Falling linear, then to max
  5968.                     12        Rising sawtooth
  5969.                     13        Rising linear and holding
  5970.                     14        Triangle, then rising
  5971.                     15        Linear rising, then to zero
  5972.  
  5973.            per:     Period of the waveform multiplied by 125000.
  5974.  
  5975.            del:     Delay in 1/59ths second before the next  GFA-BASIC 
  5976.                     command is executed.
  5977.  
  5978. Example:   SOUND 1,15,1,4,20
  5979.            SOUND 2,15,4,4,20
  5980.            SOUND 3,15,8,4,20
  5981.            WAVE 7,7,0,65535,300
  5982.            '  A tone is generated from each channel then modulated  by 
  5983.            '  WAVE.
  5984.  
  5985. See Also:  SOUND
  5986.  
  5987.  
  5988.  
  5989.  
  5990. WHILE....WEND
  5991. Syntax:    WHILE condition
  5992.            WEND
  5993. Action:    Creates a conditional loop between while and wend until
  5994.            the 'condition' is fulfilled. This is checked at the
  5995.            beginning of the loop and so it is possible that the
  5996.            loop is never executed.
  5997.  
  5998.  
  5999. The following functions are all functions of the Window Library
  6000.  
  6001.  
  6002. WINDTAB
  6003. Syntax:    WINTAB
  6004.            WINTAB(i,j)
  6005. Action:    Gives the address of the Window Parameter Table. This table 
  6006.            contains  the  data  that determines the  appearance  of  a 
  6007.            window.
  6008.  
  6009.            Window Parameter Table:
  6010.  
  6011.            Offset
  6012.            0        Handle of Window 1
  6013.            2        Attributes for Window 1
  6014.            4        x coordinates of Window 1
  6015.            6        y coordinates of Window 1
  6016.            8        Width of Window 1
  6017.            10       Height of Window 1
  6018.            12-22    Parameters for Window 2
  6019.            24-34    Parameters for Window 3
  6020.            36-46    Parameters for Window 4
  6021.            48       -1
  6022.            50       0
  6023.            52-58    Coordinates and size of Desktop
  6024.            60-63    Coordinates of the joint of the four windows
  6025.            64-65    Origin for graphic instructions (CLIP OFFSET)
  6026.  
  6027.            Window Attibute element:
  6028.  
  6029.            Bit
  6030.            0        Window Title
  6031.            1        Close box 
  6032.            2        Full box
  6033.            3        Move box
  6034.            4        Information line
  6035.            5        Sizing box
  6036.            6        Up arrow
  6037.            7        Down arrow
  6038.            8        Vertical slider
  6039.            9        Left arrow
  6040.            10       Right arrow
  6041.            11       Horizontal slider
  6042.            
  6043.  
  6044. Example:   OPEN #1,100,120,200,70,&HFFF
  6045.            ' corresponds to:
  6046.            DPOKE WINTAB+2,&HFFF
  6047.            DPOKE WINTAB+4,100
  6048.            DPOKE WINTAB+6,120
  6049.            DPOKE WINTAB+8,200     
  6050.            DPOKE WINTAB+10,70
  6051.            OPENW 1
  6052.            ' or
  6053.            WINTAB(1,1)=&HFFF
  6054.            WINTAB(1,2)=100
  6055.            WINTAB(1,3)=120
  6056.            WINTAB(1,4)=200     
  6057.            WINTAB(1,5)=70
  6058.            OPENw 1
  6059.  
  6060. WIND_CALC
  6061. Syntax:    WIND_CALC(w_type,attr,ix,iy,iw,ih,ox,oy,ow,oh)
  6062. Action:    This function computes the total size of the work area from 
  6063.            the size of the window.
  6064.            Returns 0 if an error.
  6065.  
  6066.            w_type:            0 Compute total size
  6067.                               1 Compute work area size
  6068.  
  6069.            attr:              Bit
  6070.                               0   Title bar with name
  6071.                               1   Close box
  6072.                               2   Full size box
  6073.                               3   Move bar
  6074.                               4   Info line    
  6075.                               5   Size box
  6076.                               6   Up arrow
  6077.                               7   Down arrow
  6078.                               8   Vertical slider
  6079.                               9   Left arrow
  6080.                               10  Right arrow
  6081.                               11  Horizontal slider
  6082.  
  6083.            ix,iy              top left coorinates
  6084.            iw,ih              width and height
  6085.            
  6086.            ox,oy              Calculated top left coordinates
  6087.            ow,oh              Calculated width and height
  6088.  
  6089.  
  6090.  
  6091. WIND_CLOSE
  6092. Syntax:    WIND_CLOSE(handle)
  6093. Action:    Closes the specified window.
  6094.  
  6095.  
  6096.  
  6097. WIND_CREATE
  6098. Syntax:    WIND_CREATE(attr,wx,wy.ww.wh)
  6099. Action:    Allocates  a  new window,  specifying  the  attributes  and 
  6100.            maximum size. The handle of the window is returned.
  6101.  
  6102.            attr:              Bit
  6103.                               0   Title bar with name
  6104.                               1   Close box
  6105.                               2   Full size box
  6106.                               3   Move bar
  6107.                               4   Info line    
  6108.                               5   Size box
  6109.                               6   Up arrow
  6110.                               7   Down arrow
  6111.                               8   Vertical slider
  6112.                               9   Left arrow
  6113.                               10  Right arrow
  6114.                               11  Horizontal slider
  6115.  
  6116.            wx                 Max x position of left edge
  6117.            wy                 Max y position of top edge
  6118.            ww                 Max width of window
  6119.            wh                 Max height of window
  6120.                                  
  6121.  
  6122. WIND_DELETE
  6123. Syntax:    WIND_DELETE(handle)
  6124. Action:    Deletes a window allocation and frees reserved memory.
  6125.  
  6126.  
  6127.  
  6128. WIND_FIND
  6129. Syntax:    WIND_FIND(fx,fy)
  6130. Action:    Determines  the  id  number of a window  within  which  the 
  6131.            specified coordinates lie.
  6132.  
  6133.            fx:                x coordinates
  6134.            fy:                y coordinates
  6135.  
  6136.  
  6137.  
  6138. WIND_GET
  6139. Syntax:    WIND_GET(handle,code,w1,w2,w3,w4)
  6140. Action:    Supplies information about a window determined by the code.
  6141.  
  6142.            handle:            Id number of the window
  6143.  
  6144.            code:              depending upon the code,  information is 
  6145.                               supplied in w1,w2,w3,w4.
  6146.  
  6147.  
  6148.            code: 4            supplies size of window work area
  6149.                     w1:       x coordinates
  6150.                     w2:       y coordinates
  6151.                     w3:       width
  6152.                     w4:       height
  6153.  
  6154.            code: 5            supplies  total  size of  entire  window 
  6155.                               including borders  
  6156.  
  6157.                     w1:       x coordinates
  6158.                     w2:       y coordinates
  6159.                     w3:       width
  6160.                     w4:       height
  6161.  
  6162.            code: 6            supplies total size of previous window
  6163.   
  6164.                     w1:       x coordinates
  6165.                     w2:       y coordinates
  6166.                     w3:       width
  6167.                     w4:       height
  6168.                     
  6169.            code: 7            supplies  the  total  max  size  of  the 
  6170.                               window.  
  6171.  
  6172.                     w1:       x coordinates
  6173.                     w2:       y coordinates
  6174.                     w3:       width
  6175.                     w4:       height
  6176.                     
  6177.            code: 8            supplies the position of the  horizontal 
  6178.                               slider  
  6179.                
  6180.                     w1:       1=far left  1000=far right
  6181.            
  6182.            code: 9            supplies the position of the  vertical 
  6183.                               slider  
  6184.                
  6185.                     w1:       1=top  1000=bottom               
  6186.            
  6187.            code: 10           supplies  the  id  number  of  the   top 
  6188.                               (active) window
  6189.   
  6190.                     w1:       id number of active window
  6191.  
  6192.            code: 11           supplies  the coordinates of  the  first 
  6193.                               rectangle  in the  specified  rectangle 
  6194.                               list.
  6195.           
  6196.                     w1:       x coordinates
  6197.                     w2:       y coordinates
  6198.                     w3:       width
  6199.                     w4:       height
  6200.  
  6201.            code: 12           supplies  the  coordinates of  the  next 
  6202.                               rectangle   in  the  specified   windows 
  6203.                               rectangles list
  6204.  
  6205.                     w1:       x coordinates
  6206.                     w2:       y coordinates
  6207.                     w3:       width
  6208.                     w4:       height
  6209.                     
  6210.  
  6211.            code: 13           reserved
  6212.  
  6213.            code: 15           supplies  the  size  of  the  horizontal 
  6214.                               slide bar compared to its max possible
  6215.  
  6216.                     w1:       -1 = minimum size
  6217.                                1 = small
  6218.                                1000 = full width
  6219.  
  6220.            code: 16           supplies the size of the vertical  slide 
  6221.                               bar compared to its max possible
  6222.                     
  6223.                     w1:       -1 = minimum size
  6224.                                1 = small
  6225.                                1000 = full height
  6226.  
  6227. WIND_OPEN
  6228. Syntax:    WIND_OPEN(handle,wx,wy,ww,wh)
  6229. Action:    Draws  on  the  screen a  window  previously  created  with 
  6230.            WIND_CREATE.
  6231.  
  6232.  
  6233. WIND_SET
  6234. Syntax:    WIND_SET(handle,code,w1,w2,w3,w4)
  6235. Action:    Changes  the parts of a window according to  the  specified 
  6236.            function code.
  6237.  
  6238.            code: 1            Sets  new  windows  components  as  with 
  6239.                               WIND_CREATE.
  6240.  
  6241.                     w1:       new window element
  6242.  
  6243.            code: 2            Gives a window a new title
  6244.                     
  6245.                     w1:       Hi word
  6246.                     w2:       Low word of address of title string
  6247.  
  6248.            code: 3            Specifies a new information line
  6249.                     w1:       Hi word
  6250.                     w2:       Low  word  of  address  of   information 
  6251.                               string
  6252.  
  6253.            code: 5            Sets the window size
  6254.                     
  6255.                     w1:       x coordinates
  6256.                     w2:       y coordinates
  6257.                     w3:       width
  6258.                     w4:       height
  6259.  
  6260.            code: 8            Positions the horizontal slider
  6261.                
  6262.                     w1:       1=far left  1000=far right
  6263.  
  6264.            code: 9            Positions the vertical slider
  6265.                
  6266.                     w1:       1=top  1000=bottom
  6267.  
  6268.            code: 10           Sets top (active) window
  6269.  
  6270.                     w1:       id number
  6271.  
  6272.            code: 14           Sets a new desk top Menu tree
  6273.  
  6274.                     w1:       Low word
  6275.                     w2:       High word of address of new tree
  6276.                     w3:       id  number  of the first  object  to  be 
  6277.                               drawn
  6278.  
  6279.            code: 15           Sets the size of the vertical slide bar
  6280.  
  6281.                     w1        -1=minimum size
  6282.                               1= small
  6283.                               1000 max size
  6284.  
  6285.            code: 16           Sets  the size of the horizontal  slider 
  6286.                               bar
  6287.                     
  6288.                     w1        -1=minimum size
  6289.                               1= small
  6290.                               1000 max size
  6291.  
  6292. WIND_UPDATE
  6293. Syntax:    WIND_UPDATE(flag)
  6294. Action:    Coordinates  all functions concerned with  screen  redraws, 
  6295.            in particular with drop down menus.
  6296.  
  6297.            flag: 0            screen redraw completed
  6298.                  1            screen redraw starting
  6299.                  2            application loses mouse control
  6300.                  3            application takes on mouse control
  6301.  
  6302.  
  6303. WORD()
  6304. Syntax:    WORD(x)
  6305. Action:    Extends  a  word to long word length (32 bits)  by  copying 
  6306.            bits  15  to bit positions 16 to 31,  thus  preserving  the 
  6307.            sign.
  6308.  
  6309.  
  6310. WORK_OUT()
  6311. Syntax:    WORK_OUT(x)
  6312. Action:    Determines  the  values found in INTOUT(0)  to  INTOUT(44), 
  6313.            PTSOUT(0)  and PTSOUT(1) after returning from the  function 
  6314.            OPEN_WORKSTATION.
  6315.  
  6316.  
  6317.  
  6318. WRITE
  6319. Syntax:    WRITE [ expressions ][ ; ]
  6320.            WRITE #n [ expressions ][ ; ]
  6321. Action:    Stores data in a sequential file to be read with input.
  6322.            Unlike the PRINT command the numbers are separated by
  6323.            commas and the strings are enclosed in quotes.
  6324.  
  6325.  
  6326.  
  6327. WRITE#     
  6328. Syntax:    WRITE#n,expression
  6329. Action:    Saves  data  to sequential file,  for  later  reading  with 
  6330.            INPUT#.
  6331.  
  6332. Example:   OPEN "o",#1,"TEST.DAT"
  6333.            WRITE #1,"Version ",3,".6"
  6334.            CLOSE #1
  6335.            OPEN "i",#1,"TEST.DAT"
  6336.            INPUT #1,v1$,v2$,v3$
  6337.            CLOSE #1
  6338.            PRINT v1$+V2$+v3$
  6339.  
  6340.  
  6341.  
  6342. W_HAND
  6343. Syntax:    W_HAND(#n)
  6344. Action:    Returns  the GEM handle of the window whose channel  number 
  6345.            is n.
  6346.  
  6347. Example:   OPENW 2
  6348.            PRINT W_HAND(#2)
  6349.            ~INP(2)
  6350.            CLOSE #2
  6351.  
  6352.  
  6353. W_INDEX
  6354. Syntax:    W_INDEX(#hd)
  6355. Action:    Returns the window number of the specified GEM handle.
  6356.            Reverse of W_HAND().
  6357.  
  6358.  
  6359.  
  6360.  
  6361. XBIOS
  6362.  
  6363. The XBIOS function is used to call XBIOS system routines.
  6364.  
  6365. ~XBIOS(0,t%,l:p%.l:v%)
  6366.  
  6367.            Initialises  the mouse handling routine but not  compatible 
  6368.            with GEM.
  6369.  
  6370.            t%  0    Switches mouse off
  6371.                1    Switches mouse into relative mode
  6372.                2    Switches mouse into absolute mode
  6373.                4    Mouse in keyboard mode
  6374.            p%       Address of information structure
  6375.            v%       Address of the mouse handling routine
  6376.  
  6377. r%=XBIOS(2)
  6378.  
  6379.            Returns the base address of the physical screen memory.
  6380.  
  6381.            r%       Address of the physical screen memory
  6382.  
  6383. r%=XBIOS(3)
  6384.  
  6385.            Returns  the  address  of the logical  screen  memory  when 
  6386.            writing to the screen.
  6387.  
  6388.            r%       Address of the logical screen memory
  6389.  
  6390. r%=XBIOS(4)
  6391.  
  6392.            Returns the current screen resolution
  6393.  
  6394.            r%  0    320 x 200
  6395.                1    640 x 200
  6396.                2    640 x 400
  6397.                
  6398. ~XBIOS(5,l:l%,l:p%,r%)
  6399.  
  6400.            Enables the resolution to be changed from low res and  high 
  6401.            res when using a colour monitor. Can not be used with GEM.
  6402.  
  6403.            l%       New address of logical screen memory
  6404.            p%       New address of the physical screen memory
  6405.            r%       New screen resolution (see XBIOS(4))
  6406.            
  6407. ~XBIOS( 6,L:adr%)
  6408.  
  6409.            Allows all colour registers to be reset at one time.
  6410.  
  6411.            adr%     Address of a table of 16 words, which contains new 
  6412.                     pallete data.
  6413.  
  6414. r%=XBIOS(7,n%,c%)
  6415.  
  6416.            Sets or gets a colour register.
  6417.  
  6418.            r%       For  c%=-1 the previous specified colour  register 
  6419.                     is returned.
  6420.            n%       Colour register
  6421.            c%       New colour, at c%=-1 see r%
  6422.  
  6423. r%=XBIOS(8,L:b%,L:f%,d%,sec%,t%,side%,n%)
  6424.            
  6425.            Reads sectors of a disk
  6426.  
  6427.            r%       0 if no error
  6428.            b%       address of the area from which sectors are read
  6429.            f%       unused
  6430.            d%       drive number (0=A, 1=B etc)
  6431.            sec%     sector number
  6432.            t%       track number
  6433.            side%    disk side (0 or 1)
  6434.            n%       number of sectors to be read
  6435.  
  6436. r%=XBIOS(9,L:b%,L:f%,d%,sec%,t%,side%,n%)
  6437.            
  6438.            Writes sectors to a disk
  6439.  
  6440.            r%       0 if no error
  6441.            b%       address of the area to which sectors are written
  6442.            f%       unused
  6443.            d%       drive number (0=A, 1=B etc)
  6444.            sec%     sector number
  6445.            t%       track number
  6446.            side%    disk side (0 or 1)
  6447.            n%       number of sectors to be written
  6448.  
  6449. r%=XBIOS(10,L:b%,L:f%,d%,sec%,t%,side%,i%,L:m%,v%)
  6450.  
  6451.            A trace of the disk formats
  6452.            
  6453.            r%       0 if no error
  6454.            b%       address of an area for intermediate memory
  6455.            f%       unused
  6456.            d%       drive number (0=A, 1=B etc)
  6457.            sec%     sectors per track
  6458.            t%       track number to be formatted
  6459.            side%    disk side (0 or 1)
  6460.            i%       Interleave factor (normaaly 1)
  6461.            m%       Magic number &H87654321
  6462.            v%       value in sectors of format (normally &HE5E5
  6463.  
  6464. ~XBIOS(12,n%,L:adr%)
  6465.            
  6466.            Outputs the contents of a block of memory to MIDI.
  6467.  
  6468.            n%       number of bytes -1
  6469.            adr%     address of the source storage area
  6470.  
  6471. ~XBIOS(13,n%,L:adr%)
  6472.  
  6473.            Sets the MFP interrupt vector on the ST.  This can only  be 
  6474.            used from assembly language or C and is not available  from 
  6475.            GFA-BASIC.
  6476.  
  6477.            n%       Interrupt number
  6478.            adr%     new address of the interrupt
  6479.  
  6480. r%=XBIOS(14,d%)
  6481.  
  6482.            Returns  the  address of the I/O table used by  the  serial 
  6483.            interface.
  6484.  
  6485.            r%       Address  of  the data buffer for  the  serial  I/O 
  6486.                     table
  6487.            d%       0:        RS232
  6488.                     1:        IKBD
  6489.                     2:        MIDI
  6490.  
  6491. ~XBIOS(15,b%,h%,ucr%,rsr%,tsr%,scr%)
  6492.  
  6493.            Configures  the  serial interface.  The  parameters  remain 
  6494.            unchanged with a value of -1.
  6495.  
  6496.            b%       Baud rate
  6497.            h%       hand shake mode
  6498.                     0: no handshake
  6499.                     1: XON/XOFF
  6500.                     2: RTS/CTS
  6501.                     3: both
  6502.            ucr%     USART control register of MFP
  6503.            rsr%     receiver status register of MFP
  6504.            tsr%     transmitter status register of MFP
  6505.            scr%     synchronous character register of MFP
  6506.  
  6507. r%=XBIOS(16,L:us%,L:sh%,L:cl%)
  6508.  
  6509.            Changes the keyboard translation tables.
  6510.  
  6511.            r%       address of the KEYTAB structure
  6512.            us%      address of the table for keys without shift
  6513.            sh%      address of the table for keys with shift
  6514.            cl%      address of the table for keys with Cap-lock
  6515.  
  6516. r%=XBIOS(17)
  6517.  
  6518.            Returns a random number
  6519.  
  6520.            r%       number with 24 bit accuracy (0 to 16777215)
  6521.  
  6522. ~XBIOS(18,L:b%,L:s%,d%,f%)
  6523.  
  6524.            Creates a boot sector for the disk in memory
  6525.  
  6526.            b%       address  of  a 512 byte buffer for  producing  the 
  6527.                     boot sector
  6528.            s%       serial number that forms part of the boot sector
  6529.                     -1: previous serial retained
  6530.                     >24 bits: random number returned
  6531.            d%       disk type (tracks/sides)
  6532.                     0:40 tracks,single sided (180K)
  6533.                     1:40 tracks,double sided (360K, IBM)
  6534.                     2:80 tracks, single side (360K)
  6535.                     3:80 tracks, double sided (720K)
  6536.            f%       0:non executable boot sector
  6537.                     1:executable
  6538.                     -1:leave unchanged
  6539.  
  6540. r%=XBIOS(19,L:b%,L:f%,d%,sec%,t%,side%,n%)
  6541.  
  6542.            Verifies the disk contents
  6543.  
  6544.            b%       address of the memory area with which a comparison 
  6545.                     is made.
  6546.            f%       not used
  6547.            d%       disk drive number
  6548.            sec%     start sector
  6549.            t%       track number
  6550.            side%    disk side
  6551.            n%       number of sectors
  6552.  
  6553. ~XBIOS(20)
  6554.  
  6555.            Calls  the  hardcopy routine and thus dumps the  screen  to 
  6556.            printer.
  6557.  
  6558. r%=XBIOS(21,c%,s%)
  6559.  
  6560.            Configure cursor.
  6561.  
  6562.            r%       when c%=5 returns the cursor blink rate
  6563.            c%       0: Hide cursor
  6564.                     1: Show cursor
  6565.                     2: blink cursor
  6566.                     3: solid cursor
  6567.                     4: blink rate set in s%
  6568.                     5: see r%
  6569.            s%       when c%=4, blink rate set to s%
  6570.  
  6571. ~XBIOS(22,L:t%)
  6572.  
  6573.            Sets date and time
  6574.  
  6575.            t%       Bits 0-4:   seconds
  6576.                          5-19:  minutes           
  6577.                          11-15: hours
  6578.                          16-20: day
  6579.                          21-24: month
  6580.                          25-31: year - 1980
  6581.  
  6582. r%=XBIOS(23)
  6583.  
  6584.            returns date and time 
  6585.  
  6586.            r%       see XBIOS(22) for bit settings
  6587.  
  6588.  
  6589. ~XBIOS(24)
  6590.  
  6591.            re   installs   the  original  keyboard   allocation   (see 
  6592.            XBIOS(16))
  6593.  
  6594. XBIOS(25,n%,L:adr%)
  6595.  
  6596.            writes bytes from memory to the keyboard processor (IKBD)
  6597.  
  6598.            n%       number bytes-1 to be sent
  6599.            adr%     address where the data to be sent is stored
  6600.  
  6601. ~XBIOS(26,i%)
  6602.  
  6603.            Disables an MFP interrupt.
  6604.  
  6605.            i%       interrupt number (0-15) to be disabled
  6606.  
  6607. ~XBIOS(27,i%)
  6608.  
  6609.            enables an MFP interrupt.
  6610.  
  6611.            i%       interrupt number (0-15) to be enabled
  6612.  
  6613. ~XBIOS(28,d%,reg%)
  6614.  
  6615.            reads and writes from and to the sound chip register
  6616.  
  6617.            r%       returns register value when reading
  6618.            d%       value to be writen (8 bits)
  6619.            r%       register number (0-15),  bit 7 defines write  mode 
  6620.                     when set.
  6621.  
  6622. ~XBIOS(29,b%)
  6623.  
  6624.            sets the bit of port A on the register of the sound chip to 
  6625.            zero
  6626.  
  6627.            b%       bit pattern wicj is OR'ed with existing contents.
  6628.  
  6629. ~XBIOS(30,b%)
  6630.  
  6631.            sets the port A bit of the sound chip register to 1
  6632.  
  6633.            b%       bit  pattern  which  is ANDed  with  the  existing 
  6634.                     contents.
  6635.  
  6636. XBIOS(31,t%,c%,d%,L:adr%)
  6637.  
  6638.            Sets the MFP timers
  6639.  
  6640.            t%       number of the timer (0 to 3)
  6641.            c%       control register
  6642.            d%       data register
  6643.            adr%     address of the timer interrupt routine
  6644.  
  6645. ~XBIOS(32,L:adr%)
  6646.  
  6647.            Starts a sound sequence, whic is processed in the interrupt
  6648.  
  6649.            adr%     address of the staorage area
  6650.  
  6651. r%=XBIOS(33,c%)
  6652.  
  6653.            sets or reads the printer parameters
  6654.  
  6655.            r%       current configuration when c%=1
  6656.            c%       Bit       set            reset
  6657.                     0         Dot Matrix     Daisy Wheel
  6658.                     1         Monochrome     Colour
  6659.                     2         Atari          Epson
  6660.                     3         Parallel       RS-232
  6661.                     4         Continuous     Single sheet
  6662.                
  6663. r%=XBIOS(34)
  6664.  
  6665.            returns  address of table with vectors to the keyboard  and 
  6666.            MIDI processor.
  6667.  
  6668.            r%       returned address
  6669.  
  6670. r%=XBIOS(35,a%,w%)
  6671.  
  6672.            sets and reads keyboard repeat rate
  6673.  
  6674.            r%       current data
  6675.                     bits      0-7  repeat rate
  6676.                               8-15  time of repeat delay
  6677.            a%       repeat delay
  6678.            w%       repeat rate
  6679.  
  6680. ~XBIOS(36,L:adr%)
  6681.  
  6682.            Hardcopy routine returns parameter block address
  6683.  
  6684.            adr%     address  of  a parameter block  for  the  hardcopy 
  6685.                     routine.
  6686.  
  6687. ~XBIOS(37)
  6688.  
  6689.            waits for next vertical blank interrupt.
  6690.  
  6691. ~XBIOS(38,L:adr%)
  6692.  
  6693.            calls an assembler routine in supervisor mode
  6694.  
  6695.            adr%     address of assembler routine
  6696.  
  6697. ~XBIOS(39)
  6698.  
  6699.            turns off AES if not in ROM
  6700.  
  6701. r%=XBIOS(64,b%)
  6702.  
  6703.            contols and interrogates the blitter
  6704.  
  6705.            r%       b%=-1          current blitter status
  6706.                                    bit 1 : blitter there
  6707. XOR
  6708. Syntax:    x XOR y
  6709. Action:    Logical exclusive OR operator
  6710.  
  6711.  
  6712. XOR()
  6713. Syntax:    XOR(x,y)
  6714. Action:    Sets those bits in x that are different in x and y.
  6715.  
  6716.  
  6717. _DATA
  6718. Syntax:    _DATA
  6719.            _DATA=
  6720. Action:    Specifies the position of the DATA pointer.  _DATA is 0  if 
  6721.            the next READ would result in an out of data message.
  6722.  
  6723.  
  6724. ~
  6725. Syntax:    ~function
  6726. Action:    Similar to VOID. Forget the returned value
  6727.  
  6728. End of File
  6729.  
  6730.  
  6731.  
  6732.  
  6733.  
  6734.  
  6735.  
  6736.  
  6737.  
  6738.  
  6739.