Fresh Fish 5/FreshFish_July-August1994.bin/bbs/dev/ace-ag-docs.lha/ACE-AG-Docs/Ref.Guide

Text File | 1994-03-26 | 103.8 KB | 2,452 lines

@ DATABASE "ACEReference.doc"
@ MASTER "ACEReference"

@NODE MAIN "MENU"
  @{" Introduction   " link introduction}   @{" FILEBOX$       " link FILEBOX$}   @{" NOT            " link NOT}   @{" SIZEOF         " link SIZEOF}
  @{" ABS            " link ABS}   @{" FILES          " link FILES}   @{" OCT$           " link OCT$}   @{" SIN            " link SIN}
  @{" ADDRESS        " link ADDRESS}   @{" FIX            " link FIX}   @{" ON..GOTO/GOSUB " link ON..GOTO..GOSUB}   @{" SLEEP          " link SLEEP}
  @{" ALLOC          " link ALLOC}   @{" FOR..NEXT      " link FOR..NEXT}   @{" OPEN           " link OPEN}   @{" SOUND          " link SOUND}
  @{" AND            " link AND}   @{" FORWARD        " link FORWARD}   @{" OPTION         " link OPTION}   @{" SPACE$         " link SPACE$}
  @{" ARG$           " link ARG$}   @{" FRE            " link FRE}   @{" OR             " link OR}   @{" SPC            " link SPC}
  @{" ARGCOUNT       " link ARGCOUNT}   @{" GADGET         " link GADGET}   @{" PAINT          " link PAINT}   @{" SQR            " link SQR}
  @{" AREA           " link AREA}   @{" GADGET CLOSE   " link GADGET_CLOSE}   @{" PALETTE        " link PALETTE}   @{" STICK          " link STICK}
  @{" AREAFILL       " link AREAFILL}   @{" GADGET ON      " link GADGET_ON}   @{" PATTERN        " link PATTERN}   @{" STOP           " link STOP}
  @{" ASC            " link ASC}   @{" GADGET WAIT    " link GADGET_WAIT}   @{" PEEKx          " link PEEKx}   @{" STR$           " link STR$}
  @{" ASSEM          " link ASSEM}   @{" GOSUB..RETURN  " link GOSUB..RETURN}   @{" PENDOWN        " link PENDOWN}   @{" STRIG          " link STRIG}
  @{" ATN            " link ATN}   @{" GOTO           " link GOTO}   @{" PENUP          " link PENUP}   @{" STRING         " link STRING}
  @{" BACK           " link BACK}   @{" HANDLE         " link HANDLE}   @{" POINT          " link POINT}   @{" STRING$        " link STRING$}
  @{" BEEP           " link BEEP}   @{" HEADING        " link HEADING}   @{" POKEx          " link POKEx}   @{" STRUCT         " link STRUCT}
  @{" BIN$           " link BIN$}   @{" HEX$           " link HEX$}   @{" POS            " link POS}   @{" SUB..END SUB   " link SUB..END_SUB}
  @{" BREAK          " link BREAK}   @{" HOME           " link HOME}   @{" POTX           " link POTX}   @{" SWAP           " link SWAP}
  @{" CALL           " link CALL}   @{" IF             " link IF}   @{" POTY           " link POTY}   @{" SYSTEM         " link SYSTEM}
  @{" CASE           " link CASE}   @{" IMP            " link IMP}   @{" PRINT          " link PRINT}   @{" TAB            " link TAB}
  @{" CHDIR          " link CHDIR}   @{" INKEY$         " link INKEY$}   @{" PRINT #        " link PRINT_#}   @{" TAN            " link TAN}
  @{" CHR$           " link CHR$}   @{" INPUTBOX       " link INPUTBOX}   @{" PRINTS         " link PRINTS}   @{" TIME$          " link TIME$}
  @{" CINT           " link CINT}   @{" INPUTBOX$      " link INPUTBOX$}   @{" PSET           " link PSET}   @{" TIMER          " link TIMER}
  @{" CIRCLE         " link CIRCLE}   @{" INPUT$         " link INPUT$}   @{" PTAB           " link PTAB}   @{" TIMER ON       " link TIMER_ON}
  @{" CLNG           " link CLNG}   @{" INPUT          " link INPUT}   @{" RANDOMIZE      " link RANDOMIZE}   @{" TRANSLATE$     " link TRANSLATE$}
  @{" CLOSE          " link CLOSE}   @{" INPUT #        " link INPUT_#}   @{" READ           " link READ}   @{" TURN           " link TURN}
  @{" CLS            " link CLS}   @{" INSTR          " link INSTR}   @{" REM            " link REM}   @{" TURNLEFT       " link TURNLEFT}
  @{" COLOR          " link COLOR}   @{" INT            " link INT}   @{" REPEAT..UNTIL  " link REPEAT..UNTIL}   @{" TURNRIGHT      " link TURNRIGHT}
  @{" CONST          " link CONST}   @{" KILL           " link KILL}   @{" RESTORE        " link RESTORE}   @{" UCASE$         " link UCASE$}
  @{" COS            " link COS}   @{" LEFT$          " link LEFT$}   @{" RIGHT$         " link RIGHT$}   @{" VAL            " link VAL}
  @{" CSNG           " link CSNG}   @{" LEN            " link LEN}   @{" RND            " link RND}   @{" VARPTR         " link VARPTR}
  @{" CSRLIN         " link CSRLIN}   @{" LET            " link LET}   @{" SADD           " link SADD}   @{" WAVE           " link WAVE}
  @{" CSTR           " link CSTR}   @{" LIBRARY        " link LIBRARY}   @{" SAY            " link SAY}   @{" WHILE..WEND    " link WHILE..WEND}
  @{" DATA           " link DATA}   @{" LINE           " link LINE}   @{" SCREEN         " link SCREEN}   @{" WINDOW         " link WINDOW}
  @{" DATE$          " link DATE$}   @{" LINE INPUT     " link LINE_INPUT}   @{" SCREEN CLOSE   " link SCREEN_CLOSE}   @{" WINDOW CLOSE   " link WINDOW_CLOSE}
  @{" DAY            " link DAY}   @{" LOCATE         " link LOCATE}   @{" SCROLL         " link SCROLL}   @{" WINDOW ON      " link WINDOW_ON}
  @{" DECLARE        " link DECLARE}   @{" LOF            " link LOF}   @{" SERIAL         " link SERIAL}   @{" WINDOW OUTPUT  " link WINDOW_OUTPUT}
  @{" DEF FN         " link DEF_FN}   @{" LOG            " link LOG}   @{" SERIAL CLOSED  " link SERIAL_CLOSE}   @{" WRITE          " link WRITE}
  @{" DEFxxx         " link DEFxxx}   @{" LONGINT        " link LONGINT}   @{" SERIAL OPEN    " link SERIAL_OPEN}   @{" XCOR           " link XCOR}
  @{" DIM            " link DIM}   @{" MENU           " link MENU}   @{" SERIAL READ    " link SERIAL_READ}   @{" YCOR           " link YCOR}
  @{" EOF            " link EOF}   @{" MENU CLEAR     " link MENU_CLEAR}   @{" SERIAL WRITE   " link SERIAL_WRITE}   @{" XOR            " link XOR}
  @{" END            " link END}   @{" MENU ON        " link MENU_ON}   @{" SETHEADING     " link SETHEADING}   @{" ACE Document   " alink ace:docs/ace.guide/main}
  @{" ERR            " link ERR}   @{" MENU WAIT      " link MENU_WAIT}   @{" SETXY          " link SETXY}   @{" AIDE Document  " alink ace:docs/aide.guide/main}
  @{" ERROR          " link ERROR}   @{" MID$           " link MID$}   @{" SGN            " link SGN}   @{" A68K Document  " alink ace:docs/a68k.doc/main}
  @{" EQV            " link EQV}   @{" MOD            " link MOD}   @{" SHARED         " link SHARED}   @{" Blink Document " alink ace:docs/blink.doc/main}
  @{" EXIT FOR       " link EXIT_FOR}   @{" MOUSE          " link MOUSE}   @{" SHL            " link SHL}   @{" History        " alink ace:docs/history/main}
  @{" EXIT SUB       " link EXIT_SUB}   @{" MOUSE ON       " link MOUSE_ON}   @{" SHR            " link SHR}   @{"                "}
  @{" EXP            " link EXP}   @{" MSGBOX         " link MSGBOX}   @{" SHORTINT       " link SHORTINT}   @{"                "}
  @{" EXTERNAL       " link EXTERNAL}   @{" NAME           " link NAME}   @{" SINGLE         " link SINGLE}   @{"                "}
@ENDNODE

@NODE INTRODUCTION "Introduction"


                   +--------+
                    |ACE v2.0|
                  +--------+

            +------------------------------+
            |Command and Function Reference|
            +------------------------------+

                 ------------
                 Introduction
                 ------------

This document consists of a description of currently implemented commands
and functions.

As with AmigaBASIC, the case of commands and functions is of no consequence.

NOTES:     - [] means that a parameter or command component is optional.
          - <> surround literals, names and expressions.
          - .. implies that statements are expected to follow.

    - Commands and functions marked with an asterix are found only in
          ACE, not AmigaBASIC.

    - Standard trigonometric functions take their arguments in radians.

    - EOS = end-of-string character (ASCII 0).
    - MAXSTRINGLEN currently equals 1024. The last character in a
          string is EOS, so if you want a string which holds 1024
          characters, you need a 1025 byte string (see @{"STRING" link STRING} command).

    - For boolean operators such as
          @{"AND" link AND},@{"OR" link OR},@{"IMP" link IMP} etc
          the values T and F (TRUE and FALSE) refer to -1 and 0
          respectively.
@ENDNODE
@NODE ABS "ABS"
---------------------------------------------------------------------------
ABS        - syntax: ABS(n)
        - Returns the absolute value of n.
@ENDNODE
@NODE ADDRESS "ADDRESS"
---------------------------------------------------------------------------
ADDRESS    *    - syntax: ADDRESS <identifier>[,..]
        - Declares and initialises one or more variables of type
          address. In fact, this data type is synonymous with the
          long integer (see @{"LONGINT" link LONGINT}) data type.
                  Its main purpose is to make clear just what sort of data
                  is going to be used. This is especially useful when
                  passing addresses as parameters to subprograms.
        - See also @{"SUB" link SUB..END_SUB}, @{"STRUCT" link STRUCT}.
@ENDNODE
@NODE ALLOC "ALLOC"
---------------------------------------------------------------------------
ALLOC *        - syntax: ALLOC(<bytes>,<memory-type>)
        - This is ACE's hassle-free memory allocator.
        - You can call this function to get the address of a block
          of memory at least <bytes> bytes in size.
        - The <memory-type> argument can be one of the following:

            0 = CHIP memory
            1 = FAST memory
            2 = PUBLIC memory
            3 = CLEARED CHIP memory
            4 = CLEARED FAST memory
            5 = CLEARED PUBLIC memory

          and if a value outside this range is specified, ALLOC
          defaults to CLEARED PUBLIC memory.
        - CLEARED memory is filled with zeros.
        - If the requested block of memory can't be allocated
          for whatever reason (eg: memory is too fragmented)
          ALLOC returns zero.
        - The main benefit of ALLOC is that it keeps track of
          all memory allocated by an ACE program and frees it all
          at the end of a program run, saving you from ever having
          to free memory.
        - ALLOC will free allocated memory even if a program aborts
          due to a ctrl-c break or an error (except where a GURU
          results).
        - Specify PUBLIC memory for general use and CHIP memory for
          sound samples or any other data which must be accessible
          by the co-processors.
        - Use of ALLOC assumes that you know what you're doing with
          memory and why you want a chunk of it.
@ENDNODE
@NODE AND "AND"
---------------------------------------------------------------------------
AND        - Boolean operator: X AND Y.

            X Y    Out
            -----------
            T T    T
            T F     F
            F T      F
            F F    F
@ENDNODE
@NODE ARG$ "ARG$"
---------------------------------------------------------------------------
ARG$ *        - syntax: ARG$(n) where n=0..ARGCOUNT.
        - Returns the nth command line argument as a string.
        - If n=0 the name of the command is returned.
        - Note that ARG$ only works for CLI/Shell launched
          programs. See @{"Ace.Guide" alink ace:docs/ace.guide/3clwb} for details about how to access
          Workbench arguments.
        - See also @{"ARGCOUNT" link ARGCOUNT}.
@ENDNODE
@NODE ARGCOUNT "ARGOUNT"
---------------------------------------------------------------------------
ARGCOUNT *    - Returns the number of command line arguments.
        - See also @{"Ace.Guide" alink ace:docs/ace.guide/3clwb} re: Workbench arguments.
@ENDNODE
@NODE AREA "AREA"
---------------------------------------------------------------------------
AREA        - syntax: AREA [STEP](x,y)
        - Functions indentically to AmigaBASIC's AREA command.
        - Defines a set of up to 20 points to be joined
          into a polygon and filled by @{"AREAFILL" link AREAFILL}.
@ENDNODE
@NODE AREAFILL "AREAFILL"
---------------------------------------------------------------------------
AREAFILL    - syntax: AREAFILL [mode]
        - Same as AmigaBASIC's AREAFILL command.
        - The optional mode can be 0 or 1:

            0 = fill polygon with current pattern and
                foreground color.

            1 = fill polygon with current pattern
                but inverse of foreground color
                (max-color-id - fdgnd-color-id).

        - See also @{"PATTERN" link PATTERN} command.
@ENDNODE
@NODE ASC "ASC"
---------------------------------------------------------------------------
ASC        - syntax: ASC(X$)
        - Returns the ASCII code of the first character in X$.
@ENDNODE
@NODE ASSEM "ASSEM"
---------------------------------------------------------------------------
ASSEM *        - syntax: ASSEM
                <line of assembly code>
                <line of assembly code>
                .
                .
              END ASSEM
        - This allows for the inline inclusion of assembly source
          code into the A68K file generated by ACE.
        - ACE does not attempt to check the correctness of the
          inline code, leaving the task of assembly up to A68K.
        - If you use this facility, it is assumed that you know
          what you are doing.
@ENDNODE
@NODE ATN "ATN"
---------------------------------------------------------------------------
ATN        - syntax: ATN(n)
        - Returns the arctangent of n.
@ENDNODE
@NODE BACK "BACK"
---------------------------------------------------------------------------
BACK *        - syntax: BACK n
        - Moves the turtle back n steps.
@ENDNODE
@NODE BEEP "BEEP"
---------------------------------------------------------------------------
BEEP        - Issues a brief pulse from the speaker.
         - BEEP doesn't flash the screen as it does in AmigaBASIC.
        - This command is useful for alerting the user to an error
          or other important event.
@ENDNODE
@NODE BIN$ "BIN$"
---------------------------------------------------------------------------
BIN$ *        - syntax: BIN$(n)
        - Returns a string containing the binary equivalent of n.
        - If n is a single-precision value, ACE coerces it to
                  integer.
@ENDNODE
@NODE BREAK "BREAK"
---------------------------------------------------------------------------
BREAK        - syntax: BREAK ON|OFF|STOP
        - These commands are used for enabling, disabling and
          suspending ON BREAK event trapping.
        - See the Event Trapping section in @{"Ace.Guide" alink ace:docs/ace.guide/3event}.
@ENDNODE
@NODE CALL "CALL"
---------------------------------------------------------------------------
CALL        - Passes control to a user-defined subprogram,
          shared library function, external function,
          or user-defined machine code routine.
        - Subprogram CALLs can be recursive (user SUBs) in ACE.
        - See also sections on subprograms, shared library access,
          external functions and machine code calls in @{"Ace.Guide" alink ace:docs/ace.guide/3subs}.
@ENDNODE
@NODE CASE "CASE"
---------------------------------------------------------------------------
CASE *        - This is ACE's version of the CASE statement and is
                  different from the Pascal CASE and C switch statements.
        - The syntax is:

            CASE
              <expression> : <statement>
              .
              .
             [<expression> : <statement>]
            END CASE

           where <expression> can be any legal expression ranging
           from a constant to a relational or mathematical
                   expression.

        - The expression is used as a boolean such that 0 is false
          and any non-zero value is true.
        - The statement can consist of a single legal ACE statement
          (including block IF and loops) or a multi-statement.
@ENDNODE
@NODE CHDIR "CHDIR"
---------------------------------------------------------------------------
CHDIR        - syntax: CHDIR <dirname>

          where <dirname> is a string corresponding to the name of
          a directory.

        - If <dirname> is a legitimate directory and is accessible
           from the current directory, it will become the new
                  current directory.
        - In short, this is ACE's equivalent of the AmigaDOS "cd"
          command, the only difference being that the path change
          is not reflected in the shell prompt (if the program is
          run from the shell).
@ENDNODE
@NODE CHR$ "CHR$"
---------------------------------------------------------------------------
CHR$        - syntax: CHR$(n)
        - Returns a string consisting of a single character with
                  the ASCII value n.
@ENDNODE
@NODE CINT "CINT"
---------------------------------------------------------------------------
CINT        - syntax: CINT(n)
        - Converts n to a signed short integer by rounding the
          fractional portion.
        - When the fractional portion is exactly .5, CINT *always*
          rounds up in ACE, whereas in AmigaBASIC if the integer
          portion is even, CINT rounds down, and up if the integer
          portion is odd.
@ENDNODE
@NODE CIRCLE "CIRCLE"
---------------------------------------------------------------------------
CIRCLE        - syntax: CIRCLE (x,y),radius[,color-id,start,end,aspect]
        - Start and end angles are specified in DEGREES *not*
                  radians because this is probably more useful when
                  thinking about circles. (Note: this may be changed
                  to radians in the future).
        - If a whole ellipse is to be drawn, the graphics library
          DrawEllipse() function is used. However, if the start
          angle is not 0 or the end angle is not 359 (these are
          the defaults when not specified), a different routine
          is used. The latter is quite slow and may well be changed
          in a future release of ACE.
        - The default ASPECT is .44 as in AmigaBASIC.
@ENDNODE
@NODE CLNG "CLNG"
---------------------------------------------------------------------------
CLNG        - syntax: CLNG(n)
        - Converts n to a signed long integer by rounding the
          fractional portion.
        - When the fractional portion is exactly .5, CLNG *always*
          rounds up in ACE, whereas in AmigaBASIC if the integer
          portion is even, CLNG rounds down, and up if the integer
          portion is odd.
@ENDNODE
@NODE CLOSE "CLOSE"
---------------------------------------------------------------------------
CLOSE        - syntax: CLOSE [#]filenumber[,[#]filenumber..]
          where filenumber represents an open file.
        - This command closes at least one open file.
        - Note that in ACE, CLOSE must be followed by at least one
          filenumber, unlike AmigaBASIC.
        - See section on files in @{"Ace.Guide" alink ace:docs/ace.guide/3files}.
@ENDNODE
@NODE CLS "CLS"
---------------------------------------------------------------------------
CLS        - Clears the current output window or screen and sets the
          pen position to the upper left corner.
        - CLS does not affect any other screens or windows except
          the one which is currently active.
@ENDNODE
@NODE COLOR "COLOR"
---------------------------------------------------------------------------
COLOR        - syntax: color fgnd-id[,bgnd-id]
        - Changes the foreground and/or background color to
          fgnd-id and bgnd-id respectively.
        - Note that in ACE, you can change just the foreground
          color, both the foreground and background colors,
          but not the background color alone. This may be changed
          in a future revision.
        - The @{"PALETTE" link PALETTE} command is used to change
                  the colors corresponding to given color-ids.
@ENDNODE
@NODE CONST "CONST"
---------------------------------------------------------------------------
CONST *        - syntax: CONST <ident> = [+|-]<constant>[,..]
          where <constant> is a signed numeric constant.
        - Defines a named numeric constant or constants, the type
          being *unaffected* by the the @{"DEFxxx" link DEFxxx} directives or type
          (%&!#$) suffixes. All constant definitions are GLOBAL.
        - A number of definitions can be separated by commas.
@ENDNODE
@NODE COS "COS"
---------------------------------------------------------------------------
COS        - syntax: COS(n)
        - Returns the cosine of n.
@ENDNODE
@NODE CSNG "CSNG"
---------------------------------------------------------------------------
CSNG        - syntax: CSNG(n)
        - Converts n to a single-precision value.
@ENDNODE
@NODE CSRLIN "CSRLIN"
---------------------------------------------------------------------------
CSRLIN        - Returns the print line in the current user-defined screen
          or window.
        - CSRLIN and @{"POS" link POS} have no meaning in a
                  CLI/shell and will return 0 if used when a CLI/shell
                  is the current output window.
@ENDNODE
@NODE CSTR "CSTR"
---------------------------------------------------------------------------
CSTR *        - syntax: CSTR(<address>)
        - Coerces a long integer address into a string.
        - This is intended for taking an allocated area of memory
          and using it as a string of characters. Be aware that
                  this memory block must be NULL terminated.
        - A typical use for CSTR is something like this:

            x$=CSTR(addr&)

        - The maximum string length of MAXSTRINGLEN bytes in some
          functions still applies.
@ENDNODE
@NODE DATA "DATA"
---------------------------------------------------------------------------
DATA        - syntax: DATA [numeric-constant | string-constant][,..]
        - Stores numeric and/or string constants into a global
          data list to be accessed by the @{"READ" link READ}
                  statement.
        - DATA statements may be located anywhere in a program and
          are non-executable.
        - Strings need only be enclosed in quotes if they contain
          commas, spaces or colons or other non-identifier
                  characters.
        - In ACE, all numbers from DATA statements are currently
                  stored as single-precision values with a possible loss of
                  accuracy if LARGE long integers are originally specified.
                  This may be rectified in a future revision. Thus far
                  however, I have not had problems because of it. In order
                  to overcome it for now, do something like the following:

            #include <longval.h>
            READ X$
            X&=longval&(X$)         '..longval& returns the value.
            DATA "123456789"

        - In the above example, the BASIC function VAL is
                  substituted with LONGVAL& because the former always
                  returns a single precision value which is what we are
                  trying to avoid.
@ENDNODE
@NODE DATE$ "DATE$"
---------------------------------------------------------------------------
DATE$        - Returns the current system date as a ten-character string
          of the format: mm-dd-yyyy.
@ENDNODE
@NODE DAY "DAY"
---------------------------------------------------------------------------
DAY *        - Returns the day of the week as an integer from 0..6,
          where 0=Sunday and 6=Saturday.
        - The value returned by DAY reflects the last call to @{"DATE$" link DATE$}
          and is otherwise undefined.
@ENDNODE
@NODE DECLARE "DECLARE"
---------------------------------------------------------------------------
DECLARE        - This has three uses in ACE:

         1. DECLARE FUNCTION <func-name>[%&!#$][(param-list)]
                               LIBRARY [<lib-name>]
            (see section on shared library functions in @{"Ace.Guide" alink ace:docs/ace.guide/3lib})

         2. DECLARE SUB [<type>] subprogram-name[(parameter-list)]

             which is used for forward SUB declarations.
             (see also section on subprograms in @{"Ace.Guide" alink ace:docs/ace.guide/3subs})

          3. DECLARE STRUCT <type> [*] <ident1> [,[*] <identN>..]

             where a structure variable of type <struct-type> is
             created. If "*" precedes the variable identifier,
             a pointer to the structure is created, otherwise
             a BSS object is allocated. In both cases, "identN"
             holds the start address of the structure. In the
             latter case, the address is resolved at load time
             while in the former, the address is allocated at
             run time (eg: with @{"ALLOC" link ALLOC}).

        - Only the first usage is supported by AmigaBASIC.
@ENDNODE
@NODE DEF_FN "DEF FN"
---------------------------------------------------------------------------
DEF FN       - syntax: DEF [FN]funcname[!#%&$][(parameter-list)]=expression
         - As an extension to this syntax, in ACE it is also possible
           to follow the DEF keyword with one of the following:

                @{"ADDRESS" link ADDRESS},@{"LONGINT" link LONGINT},@{"SHORTINT" link SHORTINT},@{"SINGLE" link SINGLE},@{"STRING" link STRING}

         - These keywords may also precede each item in the
           parameter list.
         - This command provides the simple defined function
          capability found in many BASICs.
         - The parameters are passed by value and are manipulated
           in the expression on the right hand side of the "=" to
           yield a function return value.
         - Like a subprogram, a defined function in ACE doesn't have
           access to global variables. Unlike the former, DEF FNs
           cannot use @{"SHARED" link SHARED} to get around this. In other
               words, if the function needs to use a particular value,
               you must pass it to the function via the parameter list. If
               a variable is defined in the expression (by just being used)
           its value will be local to the function (and unknown).
         - The function may only be invoked as part of an expression,
           eg:

            DEF SEC(x)=1/COS(x)
            PRINT SEC(12)

           defines and invokes the secant function which can then be
           used in the same way as other built-in functions (eg: COS).

         - Note from the above that the "FN" prefix is optional
           in ACE. If used, there must be no spaces between "FN"
           and the function name.
         - The fact that subprograms (SUBs) in ACE have return
           values and so can be treated as functions obviates the
           need for DEF FN to some extent, but the shorter definition
           may be considered better in some cases. Contrast the
           above definition with the following:

            SUB SEC(x)
              SEC=1/COS(x)
            END SUB

         - A slightly different example is:

            DEF ADDRESS pubmem(bytes&) = ALLOC(bytes&,2)

           which when invoked would return the start address of
           a block of public memory.
         - Once a function has been defined, you cannot redefine
           it (AmigaBASIC allows this) in the same program.
         - See the file ACE include:MathFunc.h for examples of
           defined functions (taken from Appendix E of the
           AmigaBASIC Manual).
@ENDNODE
@NODE DEFxxx "DEFxxx"
---------------------------------------------------------------------------
DEFxxx        - syntax: DEFxxx <letter>[,|-<letter>] [..]
        - The DEFxxx commands (DEFINT,DEFLNG,DEFSNG,DEFDBL,DEFSTR)
          are global data type directives which affect data objects
          in both the main program and subprograms.
        - For example:

            DEFLNG    a-z

          declares all data objects to be of type @{"LONGINT" link LONGINT} unless
          overridden by another DEFxxx directive, variable
                  declaration or trailing character (%&!#$).
         - DEFDBL currently defaults to single-precision since
          double-precision floating-point is not yet supported
                  by ACE.
@ENDNODE
@NODE DIM "DIM"
---------------------------------------------------------------------------
DIM        - syntax: DIM <name>(<i>[,..]) [SIZE <n>] [ADDRESS <addr>][,..]
        - ACE requires that ALL arrays be dimensioned before use.
        - For a subscript range of 0..n, you must DIMension
          an array with an index of n.
        - Up to 255 dimensions can be specified with up to
          32767 elements per dimension. On my 3 Mb machine, around
          11 dimensions is the practical limit.
        - Each dimension must be specified as a short numeric constant
          (literal or defined).
        - The SIZE option is for the specification of string element
          length other than the default MAXSTRINGLEN value.
        - The @{"ADDRESS" link ADDRESS} option allows you to specify some arbitrarily
          allocated area of memory (ALLOC'd, string etc) for
          the array space.
        - Both options (SIZE and ADDRESS) may be used together in
          DIM. This is not so for simple string variables where
          only one or the other may be used (see @{"STRING" link STRING} command).
          When used in DIM, the SIZE option specifies how big each
          string element is to be.
        - SHARED is not an option and ACE arrays are shared in the
          same way as variables. See "Subprograms" in @{"Ace.Guide" alink ace:docs/ace.guide/3subs}.
@ENDNODE
@NODE EOF "EOF"
---------------------------------------------------------------------------
EOF        - syntax: EOF(n)
          where n is the filenumber of an open file.
        - EOF is a function which returns either -1 or 0 depending
          upon whether the file pointer has reached the end-of-file
          or not.
        - If the file doesn't exist or hasn't been opened, EOF
          returns -1.
@ENDNODE
@NODE END "END"
---------------------------------------------------------------------------
END         - Closes standard libraries, performs other cleanup operations
           and passes control back to parent process (CLI/Shell or Wb).
         - Don't use END within an @{"IF" link IF}..THEN..END IF block. Use @{"STOP" link STOP}
           instead which is functionally equivalent in ACE.
@ENDNODE
@NODE ERR "ERR"
---------------------------------------------------------------------------
ERR        - syntax: ERR
        - This parameterless function returns the error code
          corresponding to a failed I/O operation (or zero if no
          error has occurred) and then *immediately* clears the
          error code (sets it to zero).
        - It is important to realise that the error code is
          cleared before the function returns its value, since
          unless this value is stored, it will be lost.
        - The most typical usage is as part of a conditional test,
          eg: IF ERR<>0 THEN PRINT "Error!":STOP
        - ERR may also be called after an error has been trapped
          by the ON ERROR event trapping mechanism. See @{"Ace.Guide" alink ace:docs/ace.guide/3event}
          for more details about event trapping in ACE.
        - ERR currently only returns non-zero values for serial I/O
          and buffered file I/O operations. This does not include
          standard I/O (keyboard and screen).
        - Here are the current codes:

             -- AmigaBASIC codes --
            52  - Bad File Number
            54  - Bad File Mode

            -- AmigaDOS codes --
            103
            to
            233 - See The AmigaDOS Manual (Bantam),
                  Error Codes and Messages

            -- ACE codes --
            300 - Error opening serial port
            301 - Error closing serial port
            302 - Error reading from/querying serial port
            303 - Error writing to serial port
            304 - Bad channel number/port not open
@ENDNODE
@NODE ERROR "ERROR"
---------------------------------------------------------------------------
ERROR        - syntax: ERROR ON|OFF|STOP
        - These commands are used for enabling, disabling and
          suspending ON ERROR event trapping.
        - See the Event Trapping section in @{"Ace.Guide" alink ace:docs/ace.guide/3event}.
@ENDNODE
@NODE EQV "EQV"
---------------------------------------------------------------------------
EQV        - Boolean operator: X EQV Y.

            X Y    Out
            -----------
            T T    T
            T F    F
            F T    F
            F F    T
@ENDNODE
@NODE EXIT_FOR "EXIT FOR"
---------------------------------------------------------------------------
EXIT FOR *    - This command allows for the premature, conditional
          termination of a @{"FOR..NEXT" link FOR..NEXT} loop.
        - Since ACE uses the stack for FOR..NEXT loop counter &
                  step values, issuing a RETURN inside a FOR loop is
                  dangerous because the top item on the stack is something
                  other than the expected return address.
                - In short, leaving a FOR loop before it has finished and
          never returning (@{"CALL" link CALL} and @{"GOSUB" link GOSUB..RETURN} are okay since they will
          return to the loop) is unsafe in ACE, which is why EXIT
          FOR has been provided because it properly cleans up the
          stack before prematurely exiting the loop.
        - When nesting one FOR loop inside another, be aware that
          the inner FOR loop's EXIT FOR will override any previous
          EXIT FOR directives in the enclosing outer FOR loop.
          As a consequence of this:

            FOR I=1 TO 10
                PRINT I
              FOR J=1 TO 5
                PRINT J
                IF MOUSE(0) THEN EXIT FOR
              NEXT
              IF MOUSE(0) THEN EXIT FOR
            NEXT

          will have the desired effect, whereas:

            FOR I=1 TO 10
                PRINT I
              IF MOUSE(0) THEN EXIT FOR  '..overridden below!
              FOR J=1 TO 5
                PRINT J
                IF MOUSE(0) THEN EXIT FOR
              NEXT
            NEXT

          will not. Observe the effect of running these two
          code fragments in order to see what's going on here.
@ENDNODE
@NODE EXIT_SUB "EXIT SUB"
---------------------------------------------------------------------------
EXIT SUB    - This command can only be used inside a subprogram and
          when encountered, has the effect of passing control back
          to the caller of the subprogram in which it appears.
        - If the current instantiation of the subprogram is the
          result of a recursive call, control will be returned
          to the previous instantiation of the same subprogram.
@ENDNODE
@NODE EXP "EXP"
---------------------------------------------------------------------------
EXP        - syntax: EXP(n)
        - Returns e to the power n, where e is the base of
          natural logarithms or 2.7182818284590.
@ENDNODE
@NODE EXTERNAL "EXTERNAL"
---------------------------------------------------------------------------
EXTERNAL *    - syntax: EXTERNAL [FUNCTION] <identifier>[%&!$]
        - Used to declare an external function or variable.
        - See the section on External References in @{"Ace.Guide" alink ace:docs/ace.guide/3ref}.
@ENDNODE
@NODE FILEBOX$ "FILEBOX$"
---------------------------------------------------------------------------
FILEBOX$ *    - syntax: FILEBOX$(title-string)
        - This function invokes a file requester and returns
          the user's selection as a fully qualified path.
        - The title-string is displayed in the title bar of
          the file requester (eg: "Open", "Select a file").
        - If the program is running under Wb 2.04 or higher,
          an ASL file requester appears. If not, an Arp
          requester is invoked which means that if you are
          running Wb 1.3 or lower, you'll need arp.library
          in your LIBS: directory.
        - If you are using FileBox$ under Wb 1.3 make sure
          you have a stack (in the shell/CLI or Tool) which
          is at least 5000 bytes in size.
@ENDNODE
@NODE FILES "FILES"
---------------------------------------------------------------------------
FILES        - syntax: FILES [TO <storefile>] [,<target>]
        - Gives an unsorted directory listing ala AmigaBASIC
          except that ACE's version takes two optional arguments
          while AmigaBASIC's takes one (<target>).
        - If <storefile> is specified, the listing will be
             captured by that file.
           - If <storefile> is omitted, it is assumed that the
          program containing the FILES command was invoked
          from a shell or CLI (since the listing will be
          displayed).
           - The <target> argument can be a file, directory or
             AmigaDOS device name which is to be the subject
          of the directory listing.
@ENDNODE
@NODE FIX "FIX"
---------------------------------------------------------------------------
FIX        - syntax: FIX(n)
        - The function returns the truncated integer portion of n.
        - FIX(n) is equivalent to SGN(n)*INT(ABS(n)).
        - Whereas @{"INT" link INT}(n) rounds off a negative number
          to the next lowest whole number, FIX does not.

        or

        - syntax: FIX n
        - The command which is found only in ACE is intended to
                  have a similar effect to the FIX button found on some
                  calculators that is, to change the number of decimal
                  places ACE rounds a single-precision number to.
        - FIX utilises the ami.lib function arnd(). When the value
                  of n is anything other than 8, arnd() is invoked. This
                  affects the commands: @{"PRINT" link PRINT}, @{"PRINTS" link PRINTS}, @{"WRITE#" link WRITE}, @{"PRINT#" link PRINT_#}
                  and @{"STR$" link STR$}.
        - FIX should be considered experimental since I have not
          completely figured out what all the values of n (as used
          directly by arnd()) do yet.
        - In a future release, a given value for n may have
                  different results than it does now. Currently, n may be
                  positive or negative.

            Examples
            --------

            FIX -3
            PRINT 12.3456

            would display: 12.35
@ENDNODE
@NODE FOR..NEXT "FOR..NEXT"
---------------------------------------------------------------------------
FOR..NEXT    - syntax: FOR <variable>=x TO y [STEP z]
        - The statements between FOR and NEXT are iterated
          the number of times it takes for <variable> to become
          equal to or greater than y (or less than y if z is
                  negative) starting from x. The loop index <variable>
                  is incremented by z, or 1 if STEP is not specified.
           - NEXT can only be followed by a variable, colon or
          comment and must appear on a separate line or in a
          multi-statement (not after THEN for example).
        - Any attempt to use a shared variable as a FOR loop index
          will result in an (intentional) compilation error.
         - If you want to branch out of a FOR loop never to return,
          use EXIT FOR. See also the further discussion of this
          issue (including RETURNing from within a FOR loop) in the
          "Limitations" section of @{"Ace.Guide" alink ace:docs/ace.guide/4limit}.
@ENDNODE
@NODE FORWARD "FORWARD"
---------------------------------------------------------------------------
FORWARD *    - syntax: FORWARD n
        - Move the turtle forward n steps.

@ENDNODE
@NODE FRE "FRE"
---------------------------------------------------------------------------
FRE        - syntax: FRE(n)
          where n is -1,0,1,2 or 3.
        - Since ACE's run-time environment is different to
          AmigaBASIC's, FRE returns different values and
          takes different arguments than in AmigaBASIC.
        - FRE returns the amount of free system memory according
          to n:

              n = -1    ->  total CHIP + FAST memory free.
              n =  0  ->  total CHIP memory free.
              n =  1  ->  total FAST memory free.
                  n =  2  ->  largest contiguous CHIP memory available.
              n =  3  ->  largest contiguous FAST memory available.
@ENDNODE
@NODE GADGET "GADGET"
---------------------------------------------------------------------------
GADGET *    - syntax: GADGET id,status[,gadval,rectangle,type[,style]]

          where id is a unique gadget ID from 1 to 255 and status
          is 1 or 0 to enable or disable the gadget respectively.

        - The remainder of the parameters are optional, but they
          must be specified when creating a new gadget.
        - The first of these, gadval, is either a string or long
          integer (see below); rectangle defines the border of
          the gadget as (x1,y1)-(x2,y2).
        - The GADGET command creates a new gadget or alters the
          status of an existing gadget according to the above
          and in accordance with the final two parameters: type
          and style, as follows (gadval meaning is also shown):

    Type    Gadget      Style Effect            GadVal
    ----    ------     ----- ------            ------
    1    Boolean  1     All points inside the    Gadget text
                           gadget are complemented
                   when it is clicked (this
                   is the default).

             2     A box is drawn around    Gadget text
                   the gadget when clicked.

                 3     Borderless.              Gadget text


    2    String     1     Center justifies text.   Default text

             2     Right justifies text.


    3    LongInt      1    Center justifies number. Default number
                                  (as string)
              2    Right justifies number.


    4    Horiz.
        Slider      1    Borderless.         Maximum
                             slider value

    5    Vertical
        Slider      1    Borderless.         Maximum
                             slider value
    OR

        - syntax: GADGET(n)

          where n is a number from 0 to 3.

        - The GADGET function returns information about the
          last gadget event according to the following:

          N    Returns
          -    -------
          0    -1 if a gadget event has occurred since the last
            call to GADGET(0), 0 otherwise.

          1    The number of the last gadget selected.

          2    Returns the address of the string from the most
            recently selected string gadget or the long integer
            value from the most recently selected LongInt
                        gadget.
            In the former case, use ACE's @{"CSTR" link CSTR} function to
                        convert    the address into an ACE string.

          3    Returns the slider position of the most recently
            selected (horizontal or vertical) proportional
                        gadget.
@ENDNODE
@NODE GADGET_CLOSE "GADGET CLOSE"
---------------------------------------------------------------------------
GADGET CLOSE *    - syntax: GADGET CLOSE id
        - This command removes the specified gadget from the
          current output window and should always be called
          when you are finished with a gadget.
@ENDNODE
@NODE GADGET_ON "GADGET ON"
---------------------------------------------------------------------------
GADGET ON .. *    - syntax: GADGET ON|OFF|STOP
        - These commands are used for enabling, disabling and
          suspending ON GADGET event trapping.
        - See the Event Trapping section in @{"Ace.Guide" alink ace:docs/ace.guide/3event}.
@ENDNODE
@NODE GADGET_WAIT "GADGET WAIT"
---------------------------------------------------------------------------
GADGET WAIT *    - syntax: GADGET WAIT id
        - This command puts the program to sleep until it receives
          a message that the specified gadget has been selected.
        - If id=0 the program will wake up when ANY gadget is
          selected. A call to @{"GADGET" link GADGET}(1) can then
                  be used to determine the number of the gadget.
@ENDNODE
@NODE GOSUB..RETURN "GOSUB..RETURN"
---------------------------------------------------------------------------
GOSUB..RETURN    - syntax: GOSUB <label> | <line>
        - GOSUB transfers control to the specified label or line.
        - RETURN passes control back to the statement following the
          GOSUB command.
@ENDNODE
@NODE GOTO "GOTO"
---------------------------------------------------------------------------
GOTO        - syntax: GOTO <label> | <line>
        - Transfers control to the specified label or line.
@ENDNODE
@NODE HANDLE "HANDLE"
---------------------------------------------------------------------------
HANDLE *    - syntax: HANDLE(n)
          where n is the file number of an @{"OPEN" link OPEN}ed file (1..255).
        - This function returns a long integer which is a pointer
                  to a dos file handle suitable for use with dos.library
                  functions such as Read (xRead when declared in
                  ACE/AmigaBASIC).
        - If HANDLE returns 0& the file does not exist or can't be
          opened as requested.
@ENDNODE
@NODE HEADING "HEADING"
---------------------------------------------------------------------------
HEADING *    - Returns the turtle's current heading in degrees (0..359).
@ENDNODE
@NODE HEX$ "HEX$"
---------------------------------------------------------------------------
HEX$        - syntax: HEX$(n)
        - Returns a string which represents the hexadecimal value
          of the decimal argument n.
@ENDNODE
@NODE HOME "HOME"
---------------------------------------------------------------------------
HOME *        - Move the turtle back to its home position.
@ENDNODE
@NODE IF "IF"
---------------------------------------------------------------------------
IF        - syntax: IF..THEN..[ELSE..]
              IF..GOTO..[ELSE..]
              IF..THEN
              .
              [ELSE]
              .
              END IF
        - ELSEIF is not yet implemented.
        - IF..[ELSE]..END IF blocks can be nested.
        - Use @{"STOP" link STOP} rather than @{"END" link END} before an END IF
          otherwise the compiler will get confused.
@ENDNODE
@NODE IMP "IMP"
---------------------------------------------------------------------------
IMP        - Boolean operator: X IMP Y.

            X Y    Out
            -----------
            T T    T
            T F     F
            F T    T
            F F    T
@ENDNODE
@NODE INKEY$ "INKEY$"
---------------------------------------------------------------------------
INKEY$        - syntax: INKEY$
        - Returns a single character string when a keystroke
          is pending, otherwise the NULL string is returned.
        - INKEY$ works fine in user-defined windows, but since
          a normal CON: window intercepts all keystrokes, INKEY$
          is not very useful in a shell/CLI.
@ENDNODE
@NODE INPUTBOX "INPUTBOX"
---------------------------------------------------------------------------
INPUTBOX *    - syntax: INPUTBOX(prompt[,title][,default][,xpos][,ypos])
        - This function returns a long integer value after invoking
          a requester which prompts the user to enter a value. If
          you need to get a single-precision value, apply @{"VAL" link VAL} to
          the result of the @{"INPUTBOX$" link INPUTBOX$} function (see next entry).
        - An OK and Cancel gadget allow the user to accept or
                  reject the entered value. Zero is returned if the Cancel
                  gadget is selected.
        - The prompt string must be specified but all other
          parameters are optional: title goes into the requester's
          title bar; default is a string containing a default
          integer value which becomes the return value if nothing
          is entered; xpos and ypos specify where to place the
          requester on the screen.
        - Example: num& = INPUTBOX("Enter a number:",,"12345")
@ENDNODE
@NODE INPUTBOX$ "INPUTBOX$"
---------------------------------------------------------------------------
INPUTBOX$ *    - syntax: INPUTBOX$(prompt[,title][,default][,xpos][,ypos])
        - This function returns a string value after invoking
          a requester which prompts the user to enter a value.
        - An OK and Cancel gadget allow the user to accept or
                  reject the entered string. If Cancel is selected the
                  NULL string is returned.
        - The prompt string must be specified but all other
          parameters are optional: title goes into the requester's
          title bar; default is a string return value to be used if
          no new value is entered; xpos and ypos specify where to
          place the requester on the screen.
        - Example: command$ = INPUTBOX$("Enter a command:")
@ENDNODE
@NODE INPUT$ "INPUT$"
---------------------------------------------------------------------------
INPUT$        - syntax: INPUT$(X,[#]filenumber)
        - Returns a string of X characters from the filenumber'th
                  file.
        - There is a 32K upper limit for X in ACE, but if you
          want to read a whole file for example, and the file
                  length (determined by the @{"LOF" link LOF} function) is
                  greater than MAXSTRINGLEN you should do the following:

            STRING myString SIZE N
            OPEN "I",#1,filename$
             myString = INPUT$(LOF(1),#1)
            CLOSE #1

          or if you want to allocate space at run-time according to
                  the exact file size:

            bytes& = LOF(1) + 1    '..need "+1" for EOS marker
            addr& = ALLOC(bytes&,5)
            STRING myString ADDRESS addr&
            OPEN "I",#1,filename$
             myString = INPUT$(bytes&,#1)
            CLOSE #1

           - This method should only be used for small text files as
                 it is slow, and text is really the only useful thing to
                 put in a string if you wish to manipulate it. Some string
                 functions will react unexpectedly to non-text characters
                 in strings.
           - If you wish to read a large file rapidly, it's best to
                 use the dos.library function Read (declared as xRead in
                 BASIC).  The sound player play.b gives an example of this.
           - In general INPUT$ is most useful for reading a few
                 characters at a time from a file. If you wish to read a
                 line at a time, use @{"LINE INPUT#" link LINE_INPUT}. Use @{"INPUT#" link INPUT_#} if you want
                 to read numbers or delimited strings.
           - INPUT$ in ACE is only used for sequential file input, so
         the filenumber is not optional. In AmigaBASIC, if the
                 latter is omitted, input is taken from the keyboard.
                 Not so in ACE.
           - See also section on files in @{"Ace.Guide" alink ace:docs/ace.guide/3files}.
@ENDNODE
@NODE INPUT "INPUT"
---------------------------------------------------------------------------
INPUT        - syntax: INPUT [<prompt-string>] [;|,] var1 [[;|,] varN..]
        - Strings, integers and fixed-point or exponential format
          single-precision values can be input from the keyboard.
        - Each value must appear on a separate line even when
          a single INPUT statement contains multiple variables.
        - If a semicolon precedes a variable "? " will appear,
                  while if a comma is used no "? " will appear.
        - As of ACE v2.0 INPUT works with any screen or window
                  mode.
@ENDNODE
@NODE INPUT_# "INPUT #"
---------------------------------------------------------------------------
INPUT #        - syntax: INPUT #filenumber,<variable-list>
        - Reads data items from a sequential file.
        - The variables in <variable-list> must each match the
                  type of item being read.
        - If unambiguous data format is required, it is best to
          use @{"WRITE#" link WRITE} to store the values that INPUT# will
                  read since WRITE# separates each item with commas and
                  delimits strings with double quotes allowing for spaces.
                  WRITE# will also result in more efficient use of disk
                  space and faster reading by INPUT#.
        - ACE accepts white space (line feeds, spaces, tabs),
                  commas and quotes as delimiters for each field in a
                  sequential file.
        - AmigaBASIC and ACE sequential file formats are virtually
          identical.
        - See also "Files" section in @{"Ace.Guide" alink ace:docs/ace.guide/3files}.
@ENDNODE
@NODE INSTR "INSTR"
---------------------------------------------------------------------------
INSTR        - syntax: INSTR([I,]X$,Y$)
        - INSTR searches for the first occurrence of Y$ in X$ and
          returns the character position from 1..N in X$.
        - If the optional offset I is specified, the search starts
          from that position, otherwise the search starts from the
          first character in X$.
        - If I is greater than len(X$) or X$="" or Y$ is not found
          in X$ or len(Y$) > len(X$), INSTR returns 0.
        - If Y$="", INSTR returns I or 1.
        - X$ and Y$ can be string expressions, variables or
                  literals or any combination thereof.
@ENDNODE
@NODE INT "INT"
---------------------------------------------------------------------------
INT        - syntax: INT(n)
        - Returns the largest integer less than or equal to n.
@ENDNODE
@NODE KILL "KILL"
---------------------------------------------------------------------------
KILL        - syntax: KILL <filespec>
        - Deletes a file or directory.
@ENDNODE
@NODE LEFT$ "LEFT$"
---------------------------------------------------------------------------
LEFT$        - syntax: LEFT$(X$,I)
        - Returns a string which contains the leftmost I characters
          of X$.
        - If I > len(X$), the whole string (X$) is returned.
        - If I = 0, the NULL string is returned.
@ENDNODE
@NODE LEN "LEN"
---------------------------------------------------------------------------
LEN        - syntax: LEN(X$)
        - Returns the number of characters in X$.
@ENDNODE
@NODE LET "LET"
---------------------------------------------------------------------------
LET        - syntax: [LET] <variable> = <expression>
        - LET assigns a value to a variable.
        - Its use is optional so that LET X=1 is equivalent
          to X=1.
@ENDNODE
@NODE LIBRARY "LIBRARY"
---------------------------------------------------------------------------
LIBRARY        - syntax: LIBRARY [CLOSE] [<libname>]
        - Opens or closes one or more Amiga shared libraries.
        - Note that <libname> may be with or without quotes
          and can either end in ".library", ".bmap" or have no
          file extension whatever in ACE.
        - For example, to open the graphics library, two legal
          syntaxes are:

            LIBRARY graphics
          and
            LIBRARY "graphics.library"

        - LIBRARY CLOSE closes all open libraries or a single
                  library can be specified instead.
        - See "Shared library function calls" section in @{"Ace.Guide" alink ace:docs/ace.guide/3lib}.
@ENDNODE
@NODE LINE "LINE"
---------------------------------------------------------------------------
LINE        - The syntax of this command - apart from the simple
          case of LINE (x1,y1)-(x2,y2)[,color,b[f]] - is a little
          unclear from the AmigaBASIC manual.

        - The syntax of the LINE command in ACE is currently as
          follows:

            LINE [STEP](x1,y1)[-(x2,y2)[,[color],[b[f]]]]

        - The second STEP directive has been omitted, but may
                  be added in a future revision.
        - A statement such as LINE STEP (100,90) will cause a
                  line to be drawn from the last referenced coordinate
                  to 100,90.  In addition, this use of LINE does *not*
                  allow for colour setting as can be seen from the ACE
                  syntax specification whereas LINE (100,90)-(200,150),
                  color does. The same is true for the "b" and "bf"
                  options. A future version may correct this problem.
        - Note: x1 must be >= x2 and y1 must be >= y2 otherwise
          display weirdness will result!
@ENDNODE
@NODE LINE_INPUT "LINE INPUT"
---------------------------------------------------------------------------
LINE INPUT    - syntax: LINE INPUT #filenumber,<string-variable>
        - Reads a line from the filenumber'th sequential file and
          stores it in <string-variable>.
        - If <string-variable> does not exist, ACE creates it.
        - Lines are delimited by a line-feed character (ASCII 10)
          and the string which is returned consists of the
                  characters up to but not including the line-feed.
        - Note that the AmigaBASIC manual (8-72) shows a semicolon
          instead of a comma in the above syntax which is incorrect
          since AmigaBASIC itself accepts only a comma.
        - The alternative form of LINE INPUT for keyboard input is
          not currently implemented in ACE.
        - LINE INPUT will not read more than MAXSTRINGLEN
                  characters.
        - See also @{"INPUT$" link INPUT$} (which will read up to
                  32K of characters),
          @{"INPUT#" link INPUT_#} and @{"Ace.Guide" alink ace:docs/ace.guide/3files}'s section on files.
@ENDNODE
@NODE LOCATE "LOCATE"
---------------------------------------------------------------------------
LOCATE        - syntax: LOCATE line[,column].
        - LOCATE changes the printing position for the current
          screen or window.
        - Note that the use of LOCATE on a screen or user-defined
          window currently also changes the next graphics drawing
          coordinates.
@ENDNODE
@NODE LOF "LOF"
---------------------------------------------------------------------------
LOF        - syntax: LOF(n)
          where n is the file number of an open file.
        - LOF returns the length of the file in bytes.
        - If the file is not open or non-existent, LOF returns 0.
@ENDNODE
@NODE LOG "LOG"
---------------------------------------------------------------------------
LOG        - syntax: LOG(n)
        - Returns the natural logarithm of n (log base e of n).
        - The argument n should be greater than zero.
@ENDNODE
@NODE LONGINT "LONGINT"
---------------------------------------------------------------------------
LONGINT    *    - syntax: LONGINT <identifier>[,..]
        - Declares and initialises one or more long integer
                  variables.
@ENDNODE
@NODE MENU "MENU"
---------------------------------------------------------------------------
MENU        - syntax: MENU menu-id,item-id,state[,title[,command-key]]
        - This command creates or modifies the state of a
                  menu or menu item as per AmigaBASIC.
        - The final optional parameter is peculiar to ACE
                  and if used, specifies the Amiga-<key> sequence
                  which if issued results in the selection of the
                  corresponding menu option.  The command key option
                  is displayed along with the menu item when the menu
                  is rendered.
        - The state parameter can have the following values:

                    State           Effect
            -----           ------

            0           Menu or item is disabled (shadowed).

            1           Menu or item is enabled.

            2           Menu item is checkmarked.
                       There must be at least 2 spaces
                       preceding the item for the tick
                       to be rendered properly.

        - The most advisable method of creating menus is to start
          from the first menu and first item in each menu, and code
          them in sequence thereafter.

    OR

        - syntax: MENU(n)
        - This function returns information about the most recently
          selected menu and item. If n=1 the number of the menu is
          returned. If n=2 the number of the menu item is returned.
        - MENU(0) is set to 0 after being called.
        - This function must be used in conjunction with MENU event
          trapping or WAITing.
@ENDNODE
@NODE MENU_CLEAR "MENU CLEAR"
---------------------------------------------------------------------------
MENU CLEAR *    - syntax: MENU CLEAR
        - This command is the equivalent of MENU RESET in
                  AmigaBASIC.
        - The result of calling this is to clear the menu
                  strip for the current output window. In AmigaBASIC
                  the initial menu for the interpreter's window is
                  restored if a new menu is set up in that window.
                  This does not apply in ACE.
        - @{"WINDOW CLOSE" link WINDOW_CLOSE} performs a menu clear in
                  case you don't.
@ENDNODE
@NODE MENU_ON "MENU ON"
---------------------------------------------------------------------------
MENU ON ..    - syntax: MENU ON|OFF|STOP
        - These commands are used for enabling, disabling and
          suspending ON MENU event trapping.
        - See the Event Trapping section in @{"Ace.Guide" alink ace:docs/ace.guide/3event}.
@ENDNODE
@NODE MENU_WAIT "MENU WAIT"
---------------------------------------------------------------------------
MENU WAIT *    - syntax: MENU WAIT
        - This command puts the program to sleep until menu
                  activity is detected.
@ENDNODE
@NODE MID$ "MID$"
---------------------------------------------------------------------------
MID$        - syntax: MID$(X$,I[,J])
        - Only the MID$ *function* is currently implemented in ACE.
        - Returns a string containing J characters from X$ starting
          from the Ith character.
        - If J is omitted or there are fewer than J characters
          to the right of (and including) the Ith character, all
          characters from the Ith position to the end of the string
          are returned.
        - If I > len(X$), MID$ returns the NULL string.
@ENDNODE
@NODE MOD "MOD"
---------------------------------------------------------------------------
MOD        - Modulo arithmetic operator: X MOD Y.

            eg: 101 MOD 10 = 1
@ENDNODE
@NODE MOUSE "MOUSE"
---------------------------------------------------------------------------
MOUSE           - syntax: MOUSE(n)
           - Returns information about the current status of the mouse.
           - Values of n ranging from 0..2 are meaningful in ACE.
           - MOUSE(0) just returns -1 or 0 to indicate whether
                 the left mouse button is currently being pressed or not.
           - MOUSE(1) returns the X location of the mouse pointer
             in the current output window or screen.
           - MOUSE(2) returns the Y location of the mouse pointer
         in the current output window or screen.
           - Future revisions of ACE may add more functionality to
         MOUSE(n).
@ENDNODE
@NODE MOUSE_ON "MOUSE ON"
---------------------------------------------------------------------------
MOUSE ON ..    - syntax: MOUSE ON|OFF|STOP
        - These commands are used for enabling, disabling and
          suspending ON MOUSE event trapping.
        - See the Event Trapping section in @{"Ace.Guide" alink ace:docs/ace.guide/3event}.
@ENDNODE
@NODE MSGBOX "MSGBOX"
---------------------------------------------------------------------------
MSGBOX *    - syntax: MSGBOX(message,button-text1[,button-text2])
        - This function invokes a system requester having one or
          two buttons (boolean gadgets) with the specified text
          in each, plus a message in the requester's main body
          as specified by the message parameter.
        - If only button-text1 is given, a single button is
          rendered, otherwise two buttons appear.
        - The function's return value is -1 or 0 depending
          upon whether the first or second button is selected by
          the user. With only one button present, the return
          value is always -1.
        - Example: result = MsgBox("Really Quit?","Yes","No")
        - Note that the message may only consist of a single line
          but a future revision will allow for multiple lines.
@ENDNODE
@NODE NAME "NAME"
---------------------------------------------------------------------------
NAME        - syntax: NAME <filespec1> AS <filespec2>
        - Renames a file or directory.
@ENDNODE
@NODE NOT "NOT"
---------------------------------------------------------------------------
NOT        - Boolean operator: NOT X.

            X    Out
            -----------
            T    F
            F    T
@ENDNODE
@NODE OCT$ "OCT$"
---------------------------------------------------------------------------
OCT$        - syntax: OCT$(n)
        - Returns the octal string representation of the long
          integer value n.
@ENDNODE
@NODE ON..GOTO..GOSUB "ON..GOTO/GOSUB"
---------------------------------------------------------------------------
ON..GOTO/GOSUB    - syntax 1: ON <integer-expr> GOTO | GOSUB <label> | <line>

          eg: ON n GOTO one,two,three,four,five

          such that if n=1 the program will branch to the label
          "one" and if n=4 the branch will be to "four".

        - syntax 2: ON <event-spec> GOTO | GOSUB <label> | <line>
        - See "Event Trapping" section in @{"Ace.Guide" alink ace:docs/ace.guide/3event}.
@ENDNODE
@NODE OPEN "OPEN"
---------------------------------------------------------------------------
OPEN        - syntax: OPEN mode,[#]filenumber,<filespec>
          which is the same as syntax 1 in AmigaBASIC
          except that no file-buffer-size can be specified.
        - Mode is an upper-case character where:

            - "I" = open file for input
            - "O" = open file for output
            - "A" = open file for appending

        - Filenumber is a value from 1..255 and <filespec>
          is a string containing the file name (eg: "test.doc",
          "df1:letters/santa").
        - Multiple files can be open simultaneously.
@ENDNODE
@NODE OPTION "OPTION"
---------------------------------------------------------------------------
OPTION *    - syntax: OPTION <switch>+|-[,<switch>+|-..]
        - Compiler directives (switches) can be issued via this
          command instead of from the command line. The latter
          only allows for compiler directives to be *activated*.
        - Each switch must be followed by a "+" or "-" with
          the former activating the directive and the latter
          neutralising it.
        - Switches currently implemented are: b,c,E,i,l,O,w
         - See @{"Ace.Guide" alink ace:docs/ace.guide/2options} "Compiler options"
                  for details of each switch. Notice that for switches i
                  and O, activation or deactivation takes effect at the
                  end of compilation.
@ENDNODE
@NODE OR "OR"
---------------------------------------------------------------------------
OR        - Boolean operator: X OR Y.

            X Y     Out
            -----------
            T T    T
            T F    T
            F T    T
            F F     F
@ENDNODE
@NODE PAINT "PAINT"
---------------------------------------------------------------------------
PAINT        - syntax: PAINT (x,y)[[,color-id][,border-id]]
        - PAINT flood-fills an enclosed region with the
          color specified by color-id and if the latter
          is omitted, the current foreground pen is used.
        - If border-id is not specified, color-id is used
          to determine when to stop the filling process by
          looking for a border of that color. The use of
          border-id allows a region to be filled with one
          color and be bordered by another.
        - x and y can be anywhere within the enclosed region.
        - Note that the ACE version of PAINT has no STEP
          option so x and y constitute an absolute coordinate.
        - STEP may be added in a future revision.
@ENDNODE
@NODE PALETTE "PALETTE"
---------------------------------------------------------------------------
PALETTE        - syntax: PALETTE color-id,R,G,B
          where R,G,B are the red, green and blue color
          components of color-id, each in the range 0..1.
        - Palette changes colors in the current screen
          (including the Workbench!).
@ENDNODE
@NODE PATTERN "PATTERN"
---------------------------------------------------------------------------
PATTERN        - syntax: PATTERN [line-pattern][,area-pattern] | RESTORE
        - Same as in AmigaBASIC with the addition of a RESTORE
          option. PATTERN RESTORE resets the line and area patterns
          to their default values.
        - The line-pattern is a short integer value.
        - The area-pattern is a DIM'd short integer array.
        - The number of elements in area-pattern must be a
                  power of 2.
@ENDNODE
@NODE PEEKx "PEEKx"
---------------------------------------------------------------------------
PEEKx        - syntax: PEEKx(<address>)
        - The functions PEEK,PEEKW and PEEKL return an
                  8-bit, 16-bit and 32-bit value from memory, respectively.
@ENDNODE
@NODE PENDOWN "PENDOWN"
---------------------------------------------------------------------------
PENDOWN *    - Lowers the turtle's "pen". This enables drawing by the
          Turtle graphics commands.
@ENDNODE
@NODE PENUP "PENUP"
---------------------------------------------------------------------------
PENUP *        - Raises the turtle's "pen". This disables drawing by the
          Turtle graphics commands.
@ENDNODE
@NODE POINT "POINT"
---------------------------------------------------------------------------
POINT        - syntax: POINT(x,y)
        - Returns the color-id of a point in the current output
          window or screen.
@ENDNODE
@NODE POKEx "POKEx"
---------------------------------------------------------------------------
POKEx        - syntax: POKEx <address>,<numeric-value>
        - The commands POKE,POKEW and POKEL change the contents of
          <address> to <numeric-value>.
        - Unless you know what you are POKEing and why, don't (!!)
          or you can expect a visit from the Guru.
@ENDNODE
@NODE POS "POS"
---------------------------------------------------------------------------
POS        - Returns the print column in the current user-defined
                  screen or window.
        - Note that the syntax is different from AmigaBASIC where a
          dummy argument of zero is used: POS(0).
        - POS and @{"CSRLIN" link CSRLIN} have no meaning in a CLI/shell
                  and will return 0 if used when a CLI/shell is the current
                  output window.
@ENDNODE
@NODE POTX "POTX"
---------------------------------------------------------------------------
POTX *        - syntax: POTX(n)
          where n=0 or 1 (game port 1 or 2).
        - Returns a short integer value corresponding to the
          current potentiometer reading on pin 5 of the game port.
@ENDNODE
@NODE POTY "POTY"
---------------------------------------------------------------------------
POTY *        - syntax: POTY(n)
          where n=0 or 1 (game port 1 or 2).
        - Returns a short integer value corresponding to the
          current potentiometer reading on pin 9 of the game port.
@ENDNODE
@NODE PRINT "PRINT"
---------------------------------------------------------------------------
PRINT        - syntax: PRINT [<expression>][,|;| ..]
          where <expression> is a string or numeric value to
          be printed at the current print location of the current
          (DOS or Intuition) output window.
        - @{"LOCATE" link LOCATE} can be used to set the location for
                  the next PRINT command. So can @{"SETXY" link SETXY} for
                  printing on a non-shell window.
        - PRINT can be abbreviated to '?' as in AmigaBASIC.
        - If <expression> is followed by a semi-colon, a line-feed
          will not occur before the next PRINT.
        - If <expression> is followed by a comma, the effect is
          the same except that first, a horizontal tab (CHR$(9))
          is sent to the output window.
        - Note that ASCII 9 does not have exactly the same effect
          as an AmigaBASIC tab, but the result is similar.
          If spacing is critical, you should use @{"TAB" link TAB} or @{"SPC" link SPC}.
@ENDNODE
@NODE PRINT_# "PRINT #"
---------------------------------------------------------------------------
PRINT #        - syntax: PRINT #filenumber,<expression>[,|;| ..]
          where <expression> is a string or numeric value to
          be printed at the current print location in the
          filenumber'th file.
        - PRINT can be abbreviated to '?' as in AmigaBASIC.
        - This version of PRINT writes values to a file in the
          same format as they would appear in a window.
        - One oddity is that since ACE strings are NULL-terminated,
          and this NULL (ASCII 0) is normally not displayed, any
          attempt to send this character to a file, eg:

              PRINT #filenumber,CHR$(0)

          should by all rights be ignored. However, since some
          programs write NULLs to files as delimiters, ACE does
                  NOT ignore a lone CHR$(0). A consequence of this is
                  that if you send an empty - @{"LEN" link LEN}(<string>) = 0 - string to
                  a file, an ASCII 0 will be written. This is also holds
                  true for @{"WRITE #" link WRITE}filenumber,<string>. Just check the
                  length of a string before sending it to a file if in
                  doubt.
@ENDNODE
@NODE PRINTS "PRINTS"
---------------------------------------------------------------------------
PRINTS *    - syntax: PRINTS [<expression>][,|;| ..]
          where <expression> is a string or numeric value to
          be printed at the current x,y location of an open
          screen or Intuition window. @{"SETXY" link SETXY} or @{"LOCATE" link LOCATE} can be
                  used to set the X,Y coordinates for the next PRINTS
                  command.
        - This command is now redundant since as of v2.0 PRINT
          handles DOS and Intuition windows/screens transparently.
        - However since PRINTS doesn't have to make a decision
          about whether to print to a DOS or Intuition window,
          it is faster than PRINT. It should not be used in a
          CLI/shell.
@ENDNODE
@NODE PSET "PSET"
---------------------------------------------------------------------------
PSET        - syntax: PSET [STEP] (x,y)[,color-id]
        - Plots a point in the current output window or
          screen.
        - If color-id is not specified, the current
          foreground color is used.
        - If STEP is specified, the point is relative to
          the current x,y location as set by the last
          graphics command.
@ENDNODE
@NODE PTAB "PTAB"
---------------------------------------------------------------------------
PTAB        - syntax: PTAB(n)
          where n is in the range: 0..32767
        - This function is used in conjunction with @{"PRINT" link PRINT} to
          move the horizontal print position for the current
           output window to the nth pixel.
        - Subsequent graphics commands are also affected by
          PTAB.
@ENDNODE
@NODE RANDOMIZE "RANDOMIZE"
---------------------------------------------------------------------------
RANDOMIZE    - syntax: RANDOMIZE <expression>
        - Seeds the random number generator.
        - In ACE, RANDOMIZE *requires* an argument. @{"TIMER" link TIMER} and
          all other arguments will be coerced to long integers.
        - RANDOMIZE TIMER is the most commonly used syntax.
@ENDNODE
@NODE READ "READ"
---------------------------------------------------------------------------
READ        - syntax: READ <variable>[,<variableN>..]
        - Assigns <variable> the value of the next item in the
          global data list as created by DATA statements in
          the current program.
        - The <variable> must be of the same type as the data
          item to be read otherwise an unexpected value will be
          assigned to <variable>.
        - See also @{"DATA" link DATA} (especially re: READing long values).
@ENDNODE
@NODE REM "REM"
---------------------------------------------------------------------------
REM        - syntax: REM <comment>
        - A single-line comment.
        - All characters after REM until the end of line are
          ignored.
        - REM can be substituted by an apostrophe as in AmigaBASIC.
        - While REM is treated as a true statement, and must
          either appear on a separate line or after a ":" in a
          multi-statement, an apostrophe followed by a comment
          can appear anywhere in the text of a program.
        - Note that ACE also supports block comments: {..}.
        - The ACE compiler can handle the three types of comments
          while the pre-processor APP can only handle the ' and
          {..} forms. Some form of commenting is required in APP
          so that pre-processor commands can be commented out.
@ENDNODE
@NODE REPEAT..UNTIL "REPEAT..UNTIL"
---------------------------------------------------------------------------
REPEAT..UNTIL *    - syntax: REPEAT
              .
              .
              UNTIL <condition>

          where <condition> is an expression which reduces
          to a boolean (true/false) value.

        - Statements between the REPEAT and UNTIL are executed
          until the <condition> is true (ie: non-zero).
        - Styled after the Pascal REPEAT..UNTIL construct.
        - The loop is always executed at least once.
@ENDNODE
@NODE RESTORE "RESTORE"
---------------------------------------------------------------------------
RESTORE        - syntax: RESTORE
        - Resets the DATA pointer to the first @{"DATA" link DATA} statement
          in the program.
        - Note that there is no optional label in the ACE version
          of RESTORE. This may be added in a future revision.
@ENDNODE
@NODE RIGHT$ "RIGHT$
---------------------------------------------------------------------------
RIGHT$        - syntax: RIGHT$(X$,I)
        - Returns a string which contains the rightmost I
                  characters of X$.
        - If I > len(X$), the whole string (X$) is returned.
        - If I = 0, the NULL string is returned.
@ENDNODE
@NODE RND "RND"
---------------------------------------------------------------------------
RND        - syntax: RND[(X)]
        - The RND function takes an optional parameter and always
          returns a single-precision pseudo-random value between 0
          and 1.
        - At present if it is supplied, X is ignored in ACE.
@ENDNODE
@NODE SADD "SADD"
---------------------------------------------------------------------------
SADD           - syntax: SADD(<string-expression>)
           - Returns the address of <string-expression> which can be a
                 string literal, variable or expression.
           - Unlike AmigaBASIC, string allocations after a call to SADD
                 have no impact upon the address of <string-expression>.
           - @{"VARPTR" link VARPTR} can also safely be used to find the
                 address of a string variable.
@ENDNODE
@NODE SAY "SAY"
---------------------------------------------------------------------------
SAY        - In ACE, there is a SAY command and a SAY function.

        SAY command
        -----------
        - syntax: SAY <phoneme-string>[,mode-array]
        - Same as AmigaBASIC's SAY command: speak a phoneme string.
        - The <phoneme-string> can be a string literal, expression
          or variable, while the optional mode-array is a 9-element
          (0..8) DIM'd short integer array.
        - The mode-array is allowed, and the following parameters
          are supported:

            Argument     Element    Values        Default
            --------     -------    ------        -------
            pitch         0        65..320        110
            inflection   1        0 or 1        0
            rate         2        40..400        150
            voice         3        0 or 1        0
            tuning         4        5000..28000    22200 (Hz)
            volume         5        0..64        64
            channel         6        0..11        10
            mode         7        0 or 1        0
            control         8              0,1 or 2    0

        - Inflection=0 allows inflections and emphasis of syllables
          while inflection=1 gives a monotone voice.
        - The voice parameter specifies gender: 0=male; 1=female.
        - Audio channel values have the same meaning as in
                  AmigaBASIC:

            Value    Channel(s)
            -----     ----------
            0    0
            1    1
            2    2
            3    3
            4    0 and 1
            5    0 and 2
            6    3 and 1
            7    3 and 2
            8    either available left channel
            9    either available right channel
            10    either available left/right pair
                                of channels
            11    any available single channel

        - Mode is used to specify synchronous or asynchronous
                  speech (0 and 1 respectively).
        - Control is used when mode=1 to determine what action is
          to be taken when asynchronous speech is active. If
                  control is set to 0, the current SAY command waits until
                  the last SAY is finished before executing. When control=1
                  the last SAY statement is cancelled and speech processing
                  stops until the next call to SAY. When control=2 ACE
                  interrupts the last SAY command and initiates the current
                  one.
        - The defaults are the same as in AmigaBASIC.

        SAY function    (only works properly under 2.04 or higher)
        ------------
        - syntax: SAY(n)

          where n equals 0, 1 or 2.

          SAY(0) - returns true or false (-1 or 0) to indicate
               whether there is currently active asynchronous
               speech.

          SAY(1) - returns the width of the "mouth" corresponding
               to the phoneme being spoken.

          SAY(2) - returns the height of the "mouth" corresponding
               to the phoneme being spoken.

        - SAY(0) allows for monitoring of the asynchronous
          speech process (see details of mode-array above).
        - Use of SAY(1) and SAY(2) allows an animated mouth
          to be drawn.
        - SAY(1)'s and SAY(2)'s values reflect the last call
          to SAY(0) and so must be used in conjunction with
          the latter.
        - Usage of the SAY function is typically like this:

            SAY ...        '..start asynchronous speech

            WHILE SAY(0)
              x = SAY(1)
              y = SAY(2)
              .
               .
            WEND
@ENDNODE
@NODE SCREEN "SCREEN"
---------------------------------------------------------------------------
SCREEN        - The SCREEN statement syntax is the same as in AmigaBASIC:

            SCREEN screen-id,width,height,depth,mode

          where mode is one of the following:

          1=lores
          2=hires
          3=lores,interlaced
          4=hires,interlaced.

        - The SCREEN function (ACE only) syntax is SCREEN(n),
                  where:

          SCREEN(0) - Returns a pointer to the Intuition window,
                  that is, the current output window or default
                  window for the screen.

          SCREEN(1) - Returns a pointer to the Intuition screen.

          SCREEN(2) - Returns a pointer to the rastport of
                  the default window or current output
                  window for the screen.

          SCREEN(3) - Returns a pointer to the screen's viewport

        - A future revision of ACE's SCREEN command may support
          AGA screen modes.
@ENDNODE
@NODE SCREEN_CLOSE "SCREEN CLOSE"
---------------------------------------------------------------------------
SCREEN CLOSE    - syntax: SCREEN CLOSE screen-id
        - Closes a single screen.
@ENDNODE
@NODE SCROLL "SCROLL"
---------------------------------------------------------------------------
SCROLL        - syntax: SCROLL (xmin,ymin)-(xmax,ymax),delta-x,delta-y
        - Scrolls bits inside the specified rectangle.
        - Delta-x and delta-y specify motion right and down
          respectively.
        - Negative delta values yield motion left and up.
@ENDNODE
@NODE SERIAL "SERIAL"
---------------------------------------------------------------------------
SERIAL *    - syntax: SERIAL(channel,n)

          where channel is a serial channel identifier from 1..255
          and n is a function number from 0..11 (see below).

        - This function returns information about an open serial
          channel.

          n value
          -------

          0    - Returns the number of characters in the serial
              read buffer. Use this value to determine how many
              bytes to read from the buffer (see @{"SERIAL READ" link SERIAL_READ}).

          1    - Unit number of serial device in use by this
                          channel
              (see @{"SERIAL OPEN" link SERIAL_OPEN}).

          2    - Baud rate.

          3    - Parity. Actually the ASCII value of the character
              representing the selected parity (N,E,O,M,S). Use
              @{"CHR$" link CHR$} function to recover the character.

          4    - Number of data bits.

          5    - Number of stop bits.

          6    - Number of wires for handshaking: 3 or 7.

          7    - XON/XOFF feature: 0=disabled; 1=enabled.

          8     - Shared access mode: 0=disabled; 1=enabled.

          9    - Fast mode: 0=disabled; 1=enabled.

         10    - Serial (read) buffer size in bytes.

         11    - Name of serial device. Actually, the value
                          returned is the address in memory of the name
                          string. Use ACE's @{"CSTR" link CSTR} function to
                          convert it to a string.

        - For more information about the serial device modes
          see @{"SERIAL OPEN" link SERIAL_OPEN} command below and Commodore's
                  Rom Kernel Reference Manual: (Libraries and) Devices.
@ENDNODE
@NODE SERIAL_CLOSE "SERIAL CLOSE"
---------------------------------------------------------------------------
SERIAL CLOSE *    - syntax: SERIAL CLOSE [#] channel
        - Closes a logical channel to a serial device.
@ENDNODE
@NODE SERIAL_OPEN "SERIAL OPEN"
---------------------------------------------------------------------------
SERIAL OPEN * - syntax: SERIAL OPEN [#]channel,unit,baud,params[,size][,dev]

          - This command opens a logical channel to a serial device.
          - The channel parameter must be in the range 1..255.
          - The unit parameter tells ACE which serial device unit to
            open (eg: for a multi-port serial card). Normally however,
            you should specify 0 for a single serial port.
          - The baud rate is specified by the baud parameter. This
                value can be in the range 110..292,000 on the Amiga.
          - The next parameter is a string consisting of at least
                three single character "switches":

            parity         - N,E,O,M or S. Other = N.
            data bits    - usually 7 or 8.
            stop bits    - usually 1 or 2.

            wires        - 3 or 7. Other = 7.
            XON/XOFF    - X = enabled. Other = disabled.
            Access        - S = shared. Other = exclusive.
            Fast mode    - F = fast mode. Other = normal.

        - Parity, data bits and stop bits MUST be specified and
          in the order shown above, while the remaining switches
          are optional and can be given in any order.
        - For a letter, upper or lower case can be used.
        - In the above description of switches "Other" means any
          other character (I suggest you use "?" or some other
          character consistently, to indicate "don't care").

        - The optional parameter "size" specifies the size of the
          serial read buffer. At high baud rates the buffer can
                  fill up quickly. The default is 512 bytes.
        - The final parameter (dev) is also optional. This
                  specifies the name of the serial device to be used.
                  The device name defaults to "serial.device" if not
                  specified. An alternate serial device can be used as
                  long as the device's commands are compatible with the
                  standard serial.device supplied with the Amiga.
                  This device normally lives in the DEVS: directory.
        - If using another serial device, simply supply its name
          if it resides in the DEVS: directory, otherwise a full
          path must be specified.

        - Here's a typical example of SERIAL OPEN usage:

          SERIAL OPEN 1,0,2400,"N81",1024

          which opens a channel (#1) to the standard serial device
          with a baud rate of 2400, no parity, 8 data bits and 1
          stop bit. All 7 wires will be used for handshaking and
          the serial buffer will be set to 1K.
@ENDNODE
@NODE SERIAL_READ "SERIAL READ"
---------------------------------------------------------------------------
SERIAL READ *    - syntax: SERIAL READ [#] channel,buffer,length
        - Tells ACE to read length bytes from the serial buffer
          corresponding to the (open) logical channel into a string
          buffer.
        - The buffer can be a string variable or array.
@ENDNODE
@NODE SERIAL_WRITE "SERIAL WRITE"
---------------------------------------------------------------------------
SERIAL WRITE *    - syntax: SERIAL WRITE [#] channel,string,length
        - Tells ACE to write length bytes to the serial port
          corresponding to the (open) logical channel from a
          string buffer.
        - The string buffer can be any string expression.
@ENDNODE
@NODE SETHEADING "SETHEADING"
---------------------------------------------------------------------------
SETHEADING *     - syntax: SETHEADING n
        - Changes the turtle's heading to n degrees.
@ENDNODE
@NODE SETXY "SETXY"
---------------------------------------------------------------------------
SETXY *        - syntax: SETXY x,y
        - Sets the x,y location for the next graphics command
          in the current output window or open screen.
        - Its primary use is for turtle graphics. To prevent the
          "turtle" drawing a line when SETXY is used, the @{"PENUP" link PENUP}
          command should first be issued.
@ENDNODE
@NODE SGN "SGN"
---------------------------------------------------------------------------
SGN        - syntax: SGN(n)
        - Returns the sign of the number n:

            if n>0, SGN(n) returns  1
            if n=0, SGN(n) returns  0
            if n<0, SGN(n) returns -1
@ENDNODE
@NODE SHARED "SHARED"
---------------------------------------------------------------------------
SHARED        - syntax: SHARED <ident>[,<ident> ... ]
        - Variables, arrays and structures must explicitly
          be shared between the main program and subprograms.
        - Only @{"EXTERNAL" link EXTERNAL} variables are exempt from such sharing in
          ACE since they are global (see "Identifiers" in @{"Ace.Guide" alink ace:docs/ace.guide/3id}).
        - One or more SHARED statements can appear in a subprogram
          and are usually placed before all other code in that SUB.
        - Declarations of objects to be shared must appear in the
          main program before the subprogram is *declared*.
        - See subprograms section in @{"Ace.Guide" alink ace:docs/ace.guide/3subs} and the entry for
          @{"DIM" link DIM} above re: DIM SHARED.
@ENDNODE
@NODE SHL "SHL"
---------------------------------------------------------------------------
SHL *        - syntax: SHL(n,m)
          where n is the value to be shifted and m is the number
          of bit positions to shift.
        - Arithmetic shift left function. Returns a long integer.
        - Shifting left by 1 bit is faster than multiplying by 2
          or powers thereof.
@ENDNODE
@NODE SHR "SHR"
---------------------------------------------------------------------------
SHR *        - syntax: SHR(n,m)
          where n is the value to be shifted and m is the number
          of bit positions to shift.
        - Arithmetic shift right function. Returns a long integer.
        - Shifting right by 1 bit is faster than dividing by 2
          or powers thereof.
@ENDNODE
@NODE SHORTINT "SHORTINT"
---------------------------------------------------------------------------
SHORTINT *    - syntax: SHORTINT <identifier>[,..]
        - Declares and initialises one or more short integer
          variables.
@ENDNODE
@NODE SINGLE "SINGLE"
---------------------------------------------------------------------------
SINGLE *    - syntax: SINGLE <identifier>[,..]
        - Declares and initialises one or more single-precision
          variables.
@ENDNODE
@NODE SIZEOF "SIZEOF"
---------------------------------------------------------------------------
SIZEOF *      - syntax:
        SIZEOF(byte|shortint|longint|address|single|string|<ident>)
        where <ident> is the name of a variable, array, structure
        type or structure variable (not a @{"SUB" link SUB..END_SUB}, function or external
        variable).
          - A size in bytes is returned.
          - The intention is the same as that of C's sizeof() operator.
          - SIZEOF most is useful for allocating memory for structures.
@ENDNODE
@NODE SIN "SIN"
---------------------------------------------------------------------------
SIN        - syntax: SIN(n)
        - Returns the sine of n.
@ENDNODE
@NODE SLEEP "SLEEP"
---------------------------------------------------------------------------
SLEEP        - syntax: SLEEP
        - This command puts a program to sleep until there is
          mouse, menu or keyboard activity. The program will
          also be woken up by intuiticks (timer signals from a
          user-defined window or screen) at regular intervals
          so your program can perform other checks.
        - If SLEEP is called when the current output window is
          a CLI/shell, the command returns immediately.
@ENDNODE
@NODE SOUND "SOUND"
---------------------------------------------------------------------------
SOUND        - syntax: SOUND period,duration[,volume][,voice]
        - Note that the syntax of this command is different
          from the equivalent statement in AmigaBASIC.
        - See the sound section in @{"Ace.Guide" alink ace:docs/ace.guide/3sound} for details.
        - See also the @{"WAVE" link WAVE} command. A combination of
          these two commands in ACE allows you to easily
          play sound samples (see example program play.b).
        - SOUND currently uses the audio hardware directly
          but a future revision will use the audio device.
@ENDNODE
@NODE SPACE$ "SPACE$"
---------------------------------------------------------------------------
SPACE$        - syntax: SPACE$(n)
        - Returns a string of n spaces.
@ENDNODE
@NODE SPC "SPC"
---------------------------------------------------------------------------
SPC        - syntax: SPC(n)
        - This function is generally used in conjunction with @{"PRINT" link PRINT}
          and returns a string of n spaces, where n is a value from
          0 to 255.
@ENDNODE
@NODE SQR "SQR"
---------------------------------------------------------------------------
SQR        - syntax: SQR(n)
        - Returns the square root of n.
        - The argument n must be >= 0.
@ENDNODE
@NODE STICK "STICK"
---------------------------------------------------------------------------
STICK        - syntax: STICK(n)
        - Returns information about joystick direction.
        - At the moment, STICK(0) & STICK(1) always return 0,
          while STICK(2) & STICK(3) return the state of
          the joystick in port 2 (B), where:

            STICK(2) is joystick B in X direction.
            STICK(3) is joystick B in Y direction.

        - Return values are:

             0 = joystick is not engaged.
             1 = movement is upward or to the right.
            -1 = movement is downward or to the left.
        - STICK currently goes straight to the hardware. A future
          revision may use the gameport device.
@ENDNODE
@NODE STOP "STOP"
---------------------------------------------------------------------------
STOP        - This is functionally equivalent to @{"END" link END} in ACE.
        - See also @{"IF" link IF}..[ELSE]..END IF.
@ENDNODE
@NODE STR$ "STR$"
---------------------------------------------------------------------------
STR$        - syntax: STR$(n)
        - Returns the string representation of the numeric value n.
         - The string includes a leading space or "-" depending upon
          the sign of the number.
@ENDNODE
@NODE STRIG "STRIG"
---------------------------------------------------------------------------
STRIG        - syntax: STRIG(n)
        - Returns information about the state of a joystick button.
        - At the moment, STRIG(0), STRIG(1) & STRIG(2) always
          return 0.
        - STRIG(3) returns -1 if the port 2 joystick's
          fire button is *currently* pressed and 0 if it isn't.
        - STRIG currently goes straight to the hardware. A future
          revision may use the gameport device.
@ENDNODE
@NODE STRING "STRING"
---------------------------------------------------------------------------
STRING *   - syntax: STRING <ident> [[ADDRESS <addr>] | [SIZE <size>]][,..]
           - Declares and initialises one or more string variables
         with an optional size or address. If the size is not
         specified, a length of MAXSTRINGLEN bytes is assumed.
       - If an address is specified, the SIZE option can't be used
         since the size of the area of memory pointed to by <addr>
         has already been determined.
@ENDNODE
@NODE STRING$ "STRING$"
---------------------------------------------------------------------------
STRING$        - syntax: STRING$(I,J) or STRING(I,X$).
        - STRING$ returns a string of length I consisting of
                  characters with ASCII code J or ASC(MID$(X$,1,1)).
@ENDNODE
@NODE STRUCT "STRUCT"
---------------------------------------------------------------------------
STRUCT *    - Defines a new structure data type, thus:

          STRUCT <ident>
            <type> <ident1>
            <type> <ident2>
            .
            .
            <type> <identN>
          END STRUCT

          where <type> can be BYTE,@{"SHORTINT" link SHORTINT},@{"LONGINT" link LONGINT},@{"ADDRESS" link ADDRESS},@{"SINGLE" link SINGLE},
          STRING and <ident1>..<identN> are structure members of
                  one of these data types.
        - Where a member is of type @{"STRING" link STRING}, an optional size can be
          specified (STRING <ident> [SIZE <size>]).
        - See also: @{"DECLARE" link DECLARE} and the section on structures
                  in @{"Ace.Guide" alink ace:docs/ace.guide/3struct}.
        - Structures have been provided in ACE primarily to make
          communicating with the operating system a little nicer
          and to make dynamic data structures possible (see the
          example program turtle/bst.b).
        - ACE structures cannot currently be array elements
                  although there is nothing to stop you from storing
                  structure start addresses in array elements.
        - See "Structures" section in @{"Ace.Guide" alink ace:docs/ace.guide/3struct} for more details.
@ENDNODE
@NODE SUB..END_SUB "SUB..END SUB"
---------------------------------------------------------------------------
SUB..END SUB    - syntax: SUB [<type>] <ident> [([<type>] <param> [..])]
                     <statement1>
                    <statement2>
                    .
                    .
                    <statementN>
                END SUB
          where the optional <type> is one of: @{"LONGINT" link LONGINT},@{"ADDRESS" link ADDRESS},
          @{"SHORTINT" link SHORTINT},@{"SINGLE" link SINGLE} or @{"STRING" link STRING}.
        - In ACE, subprograms are non-static, allow recursion, may
          have return values and have optional parameter lists.
        - Parameters are call-by-value but ACE does provide
                  mechanisms for call-by-reference parameters.
        - SHARED variables are supported in ACE (see @{"SHARED" link SHARED}
                  command).
        - Note that since ACE SUBs are non-static, the STATIC
                  keyword is not allowed.
        - See "Subprograms" section in @{"Ace.Guide" alink ace:docs/ace.guide/3subs} for more details.
@ENDNODE
@NODE SWAP "SWAP"
---------------------------------------------------------------------------
SWAP        - syntax: SWAP <object>,<object>
          where <object> is a simple/external variable, parameter,
          array element, structure or structure member.
        - This command swaps the value of the specified data
                  objects.
        - SWAP is not intended to be used for exchanging two whole
          arrays.
        - ACE currently assumes a maximum length of MAXSTRINGLEN
          when swapping strings.
@ENDNODE
@NODE SYSTEM "SYSTEM"
---------------------------------------------------------------------------
SYSTEM        - syntax 1: SYSTEM n
          where n is an integer exit value (return code).
        - SYSTEM causes an ACE program to exit with the specified
          return code. The latter can be tested in a shell script
          as WARN, ERROR etc. This value is hidden from a Workbench
          launched program.
        - Note that in AmigaBASIC, SYSTEM returns from the
                  interpreter to the shell/CLI or Workbench. The same is
                  true in ACE, except that @{"END" link END} and @{"STOP" link STOP} will also do this,
                  so SYSTEM's intended purpose in ACE is different to that
                  in AmigaBASIC.

    OR

        - syntax 2: SYSTEM command-string
        - This version of the SYSTEM command attempts to run a
          shell/CLI command. It is equivalent to the following
          dos.library command: Execute(command-string,stdin,stdout).
        - If the command writes to standard output, make sure you
          are running the program from a shell/CLI or at least
          that you have given the @{"EXTERNAL" link EXTERNAL} stdout variable a valid
          value corresponding to an open file's handle, typically a
          CON: or RAW: window (see @{"HANDLE" link HANDLE} function).
        - Also, make sure that "Run" is in your C: directory.
        - Examples:

            SYSTEM "list"       '..lists files in current directory

            SYSTEM "dir > fred" '..runs dir command and redirects
                    '..output to a file called fred.

    OR

        - syntax 3: SYSTEM
        - This *function* returns the Exec library version,
                  enabling your program to do different things depending
                  upon the version of the operating system under which it
                  is running.
        - A value of 34 indicates Workbench 1.3 while 37 indicates
          Workbench 2.04.
@ENDNODE
@NODE TAB "TAB"
---------------------------------------------------------------------------
TAB        - syntax: TAB(n)
        - Used in conjunction with @{"PRINT" link PRINT} to move the print position
          to the nth column.
        - TAB(n) - where n=1..81.
        - if n>81, wraparound will occur in a DOS window while
          a user-defined (Intuition) window/screen will clip any
          output past the last character position.
        - if n<1, the next print position will be column 1
                  (leftmost).
@ENDNODE
@NODE TAN "TAN"
---------------------------------------------------------------------------
TAN        - syntax: TAN(n)
        - Returns the tangent of n.
@ENDNODE
@NODE TIME$ "TIME$"
---------------------------------------------------------------------------
TIME$        - syntax: TIME$
        - Returns the current time as a string of the format:

            hh:mm:ss

          where hh is hours, mm is minutes and ss is seconds.
@ENDNODE
@NODE TIMER "TIMER"
---------------------------------------------------------------------------
TIMER        - syntax: TIMER
        - Returns a single-precision value corresponding to
          seconds elapsed since midnight.
@ENDNODE
@NODE TIMER_ON "TIMER ON"
---------------------------------------------------------------------------
TIMER ON ..    - syntax: TIMER ON|OFF|STOP
        - These commands are used for enabling, disabling and
          suspending ON TIMER(n) event trapping.
        - See the Event Trapping section in @{"Ace.Guide" alink ace:docs/ace.guide/3event}.
@ENDNODE
@NODE TRANSLATE$ "TRANSLATE$"
---------------------------------------------------------------------------
TRANSLATE$    - syntax: TRANSLATE$(<string-expression>)
        - Returns the phoneme-string equivalent of
                  <string-expression> where the latter contains words.
@ENDNODE
@NODE TURN "TURN"
---------------------------------------------------------------------------
TURN *           - syntax: TURN n
           - Rotates the turtle by n degrees.
           - If n is negative, the turtle will rotate counter-clockwise
         while if it is positive, the rotation will be clockwise.
@ENDNODE
@NODE TURNLEFT "TURNLEFT"
---------------------------------------------------------------------------
TURNLEFT *    - syntax: TURNLEFT n
        - Rotates the turtle counter-clockwise by n degrees.
        - If n is negative, the result will be the same as
          @{"TURNRIGHT" link TURNRIGHT} @{"ABS" link ABS}(n).
@ENDNODE
@NODE TURNRIGHT "TURNRIGHT"
---------------------------------------------------------------------------
TURNRIGHT *    - syntax: TURNRIGHT n
        - Rotates the turtle clockwise by n degrees.
        - If n is negative, the result will be the same as
          @{"TURNLEFT" link TURNLEFT} @{"ABS" link ABS}(n).
@ENDNODE
@NODE UCASE$ "UCASE$"
---------------------------------------------------------------------------
UCASE$        - syntax: UCASE$(<string-expression>)
        - Returns a string with all alphabetic characters in
          upper case.
@ENDNODE
@NODE VAL "VAL"
---------------------------------------------------------------------------
VAL        - syntax: VAL(X$)
        - Returns the numeric value of X$ as a single-precision
          number.
        - The translation of integers plus fixed-point and
                  exponential format single-precision values is supported.
        - The hexadecimal and octal prefixes (&H and &O) are
                  recognised by VAL.
         - There may be a loss of accuracy if the string contains a
          LARGE long integer value, due to the limitations of the
          single-precision numeric format. To overcome this, use
          the LONGVAL& function in the include file longval.h,
                  thus:

            #include <longval.h>
            X$="123456789"
             X& = longval&(X$)
@ENDNODE
@NODE VARPTR "VARPTR"
---------------------------------------------------------------------------
VARPTR        - syntax: VARPTR(<data-object>)
        - Returns the absolute address of a numeric variable,
          string, array, array element, structure or structure
          member.
        - You can safely use VARPTR to find a string variable's
          address (@{"SADD" link SADD} has also been provided for string variables
          and expressions).
        - Unlike AmigaBASIC, an object's address does *not* move
          around in memory once allocated.
        - In ACE, the symbol "@" can be used instead of VARPTR,
          eg: addr& = @n(2)  '..finds address of an array element.
        - When used in conjunction with a structure variable x,
          @x will return the address of the variable itself, NOT
          the start address of the structure (see "Structures" in
          @{"Ace.Guide" alink ace:docs/ace.guide/3struct} for more).
        - See also section on indirection operators in @{"Ace.Guide" alink ace:docs/ace.guide/3indirect}.
@ENDNODE
@NODE WAVE "WAVE"
---------------------------------------------------------------------------
WAVE        - syntax: WAVE voice,SIN | [waveform-address,byte-count]
        - Defines a waveform of any length to be used by the @{"SOUND" link SOUND}
          statement for a specified audio channel (voice: 0..3).
        - If the SIN option is used, a sine waveform table is
          allocated to the specified channel. This is the default
          waveform for the SOUND statement.
        - Unlike AmigaBASIC, the number of bytes in the waveform
          table must be specified when SIN is not used.
        - See the Sound section in @{"Ace.Guide" alink ace:docs/ace.guide/3sound}.
@ENDNODE
@NODE WHILE..WEND "WHILE..WEND"
---------------------------------------------------------------------------
WHILE..WEND    - syntax: WHILE <condition>
              .
              .
              WEND

          where <condition> is an expression which reduces
          to a boolean (true/false) value.

        - Statements inside the WHILE and WEND are executed
          while the <condition> is true (ie: non-zero).
@ENDNODE
@NODE WINDOW "WINDOW"
---------------------------------------------------------------------------
WINDOW          - syntax:
        WINDOW id,[title-string],(x1,y1)-(x2,y2)[,type][,screen-id]

        where screen-id specifies the screen to which the window
        should be attached and type can be a combination of the
        following:

            Type        Effect
            ----        ------
            1        Window size can be changed via
                    sizing gadget.

            2        Window can be moved about using
                    the title bar.

            4        Window can be moved from front to
                    back using the Back gadget.

            5        Under Release 2.x of the OS, when
                    this Type value is specified alone
                    or as a component of larger Type
                    value (eg: 7,15,23) a zoom gadget
                    is added to the window allowing it
                    to be switched between the two most
                    recent window sizes.

            8        Close gadget added to window.

            16        Contents of window reappear after
                    it has been covered.

    OR
        - syntax: WINDOW(n)
        - While the window function syntax is still WINDOW(n),
          n can take on more values in ACE than in AmigaBASIC.

          WINDOW(0)  - same as window(1)
          WINDOW(1)  - window-id of current output window.
          WINDOW(2)  - present width of current output window.
          WINDOW(3)  - present height of current output window.
          WINDOW(4)  - x-coordinate in current output window where
                   next pixel will be plotted.
          WINDOW(5)  - y-coordinate in current output window where
                   next pixel will be plotted.
            WINDOW(6)  - max legal colour-id for current output
                               window.
          WINDOW(7)  - pointer to Intuition Window for current
                               output window.
          WINDOW(8)  - pointer to Rastport of current output
                               window.
          WINDOW(9)  - pointer to AmigaDOS file handle for current
                   output window (non-zero for shell/CLI only).
          WINDOW(10) - foreground pen in current output window.
          WINDOW(11) - background pen in current output window.
          WINDOW(12) - font width for current output window.
          WINDOW(13) - font height for current output window.

        - See the section on ACE windows in @{"Ace.Guide" alink ace:docs/ace.guide/3windows} for more
                  details.
@ENDNODE
@NODE WINDOW_CLOSE "WINDOW CLOSE"
---------------------------------------------------------------------------
WINDOW CLOSE    - syntax: WINDOW CLOSE id
        - Closes the id'th window if it is open.
@ENDNODE
@NODE WINDOW_ON "WINDOW ON"
---------------------------------------------------------------------------
WINDOW ON .. *    - syntax: WINDOW ON|OFF|STOP
        - These commands are used for enabling, disabling and
          suspending ON WINDOW event trapping.
        - See the Event Trapping section in @{"Ace.Guide" alink ace:docs/ace.guide/3event}.
@ENDNODE
@NODE WINDOW_OUTPUT "WINDOW OUTPUT"
---------------------------------------------------------------------------
WINDOW OUTPUT     - syntax: WINDOW OUTPUT id
        - Makes the id'th open window the current output window.
@ENDNODE
@NODE WRITE "WRITE"
---------------------------------------------------------------------------
WRITE        - syntax: WRITE #filenumber,expression-list
          where filenumber corresponds to an open file.
        - The expression-list can contain any combination
          of data items (constants, variables) of any type
          separated by commas.
        - Note that the form of WRITE allowing for screen
          output is not supported by ACE.
        - See @{"PRINT#" link PRINT_#} re: the treatment of CHR$(0) in file
                  I/O by ACE.
        - See also @{"INPUT#" link INPUT_#} and the section on files in @{"Ace.Guide" alink ace:docs/ace.guide/3files}.
@ENDNODE
@NODE XCOR "XCOR"
---------------------------------------------------------------------------
XCOR *        - Returns the turtle's current x-coordinate.
@ENDNODE
@NODE YCOR "YCOR"
---------------------------------------------------------------------------
YCOR *        - Returns the turtle's current y-coordinate.
@ENDNODE
@NODE XOR "XOR"
---------------------------------------------------------------------------
XOR        - Boolean operator: X XOR Y.

            X Y    Out
            -----------
            T T    F
            T F    T
            F T    T
            F F    F
@ENDNODE