home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 2 / FFMCD02.bin / useful / dist / dev / lang / ace / docs / ref.doc < prev   
Encoding:
Text File  |  1993-07-10  |  51.0 KB  |  1,414 lines

  1.                    ---------
  2.                     ACE v1.1a 
  3.                   ---------
  4.  
  5.             ------------------------------
  6.             Command and Function Reference  
  7.             ------------------------------
  8.                 
  9. This document consists of a description of currently implemented commands 
  10. and functions.
  11.  
  12. As with AmigaBASIC, the case of commands and functions is of no consequence.
  13.  
  14. NOTES:     - [] means that a parameter or command component is optional.    
  15.           - <> surround literals, names and expressions.
  16.           - .. implies that statements are expected to follow.
  17.  
  18.     - Commands and functions marked with an asterix are found only in ACE, 
  19.       not AmigaBASIC.
  20.     - Standard trigonometric functions take their arguments in radians.
  21.  
  22.     - EOS = end-of-string character (ASCII 0).
  23.     - MAXSTRINGLEN currently equals 1024. The last character in a string 
  24.       is EOS, so if you want a string which holds 1024 characters, you 
  25.       need a 1025 (not 1024) byte string (see STRING command).
  26.  
  27. --------------------------------------------------------------------------------
  28.  
  29. ABS        - syntax: ABS(n)
  30.         - Returns the absolute value of n. 
  31.  
  32. ADDRESS    *    - syntax: ADDRESS <identifier>[,..]
  33.         - Declares and initialises one or more variables of type
  34.           address. In fact, this data type is synonymous with the 
  35.           long integer (see LONGINT) data type. It's main purpose 
  36.           is to make clear just what sort of data is going to be
  37.           stored.
  38.         - See also SUB, STRUCT.
  39.   
  40. ALLOC *        - syntax: ALLOC(<bytes>,<memory-type>)
  41.         - This is ACE's hassle-free memory allocator.
  42.         - You can call this function to get the address of a block
  43.           of memory at least <bytes> bytes in size.
  44.         - The <memory-type> argument can be one of the following:
  45.           
  46.             0 = CHIP memory
  47.             1 = FAST memory
  48.             2 = PUBLIC memory
  49.             3 = CLEARED CHIP memory
  50.             4 = CLEARED FAST memory
  51.             5 = CLEARED PUBLIC memory
  52.  
  53.           and if a value outside this range is specified, ALLOC
  54.           defaults to CLEARED PUBLIC memory.
  55.         - CLEARED memory is filled with zeros.
  56.         - The main benefit of ALLOC is that it keeps track of
  57.           all memory allocated by an ACE program and frees it all
  58.           at the end of a program run, saving you from ever having
  59.           to free memory.
  60.         - ALLOC will free allocated memory even if a program aborts 
  61.           due to a ctrl-c break or an error (except where a GURU 
  62.           results).
  63.         - Use of ALLOC assumes that you know what you're doing with
  64.           memory and why you want a chunk of it.
  65.  
  66. AND        - Boolean operator: X AND Y.
  67.  
  68.             X Y    Out
  69.             -----------
  70.             T T    T
  71.             T F     F
  72.             F T      F
  73.             F F    F        
  74.         
  75. ARG$ *        - syntax: ARG$(n) where n=0..ARGCOUNT.
  76.         - Returns the nth command line argument as a string. 
  77.         - If n=0 the name of the command is returned.
  78.         - Note that ARG$ only works for CLI/Shell launched 
  79.           programs. See ace.doc for details about how to access
  80.           Workbench arguments.
  81.  
  82. ARGCOUNT *    - Returns the number of command line arguments.
  83.         - See also ace.doc re: Workbench arguments.
  84.  
  85. AREA        - syntax: AREA [STEP](x,y)
  86.         - Functions indentically to AmigaBASIC's AREA command.
  87.         - Defines a set of up to 20 points to be joined
  88.           into a polygon and filled by AREAFILL.
  89.  
  90. AREAFILL    - syntax: AREAFILL [mode]
  91.         - Same as AmigaBASIC's AREAFILL command.
  92.         - The optional mode can be 0 or 1:
  93.             
  94.             0 = fill polygon with current pattern and 
  95.                 foreground color.
  96.  
  97.             1 = fill polygon with current pattern 
  98.                 but inverse of foreground color 
  99.                 (max-color-id - fdgnd-color-id).
  100.         
  101.         - See also PATTERN command.
  102.  
  103. ASC        - syntax: ASC(X$)
  104.         - Returns the ASCII code of the first character in X$.
  105.  
  106. ASSEM *        - syntax: ASSEM
  107.                 <line of assembly code>
  108.                 <line of assembly code>
  109.                 .
  110.                 .
  111.               END ASSEM
  112.         - This allows for the inline inclusion of assembly source
  113.           code into the A68K file generated by ACE.
  114.         - ACE does not attempt to check the correctness of the
  115.           inline code, leaving the task of assembly up to A68K.
  116.         - If you use this facility, it is assumed that you know
  117.           what you are doing.        
  118.         
  119. ATN        - syntax: ATN(n)
  120.         - Returns the arctangent of n.
  121.  
  122. BACK *        - syntax: BACK n        
  123.         - Moves the turtle back n steps.
  124.  
  125. BEEP        - Issues a brief pulse from the speaker.
  126.          - BEEP doesn't flash the screen as it does in AmigaBASIC.
  127.         - This command is useful for alerting the user to an error
  128.           or other important event.
  129.  
  130. BIN$ *        - syntax: BIN$(n)
  131.         - Returns a string containing the binary equivalent of n.
  132.         - If n is a single-precision value, ACE coerces it to integer.
  133.  
  134. BREAK        - syntax: BREAK [ON|OFF|STOP] 
  135.         - See the Event Trapping section in ace.doc.
  136.         
  137. CALL        - Passes control to a user-defined subprogram, 
  138.           shared library function, external function, 
  139.           or user-defined machine code routine.
  140.         - Subprogram CALLs can be recursive (user SUBs). 
  141.         - See also sections on subprograms, shared library access,
  142.           external functions and machine code calls in ace.doc.
  143.  
  144. CASE *        - ACE's version of the CASE statement which is different 
  145.           from the Pascal CASE and C switch statements.
  146.         - The syntax is:
  147.             
  148.             CASE
  149.               <expression> : <statement>
  150.               .
  151.               .
  152.              [<expression> : <statement>]
  153.             END CASE
  154.  
  155.            where <expression> can be any legal expression ranging
  156.            from a constant to a relational or mathematical expression.
  157.  
  158.         - The expression is used as a boolean such that 0 is false
  159.           and any non-zero value is true. 
  160.         - The statement can consist of a single legal ACE statement
  161.           (including block IF and loops) or a multi-statement.
  162.  
  163. CHDIR        - syntax: CHDIR <dirname>
  164.  
  165.           where <dirname> is a string corresponding to the name of
  166.           a directory.
  167.  
  168.         - If <dirname> is a legitimate directory and is accessible
  169.            from the current directory, it will become the new current
  170.           directory. 
  171.         - In short, this is ACE's equivalent of the AmigaDOS "cd"
  172.           command, the only difference being that the path change
  173.           is not reflected in the shell prompt.
  174.  
  175. CHR$        - syntax: CHR$(n)
  176.         - Returns a string consisting of a single character with the
  177.           ASCII value n.
  178.         - Note that PRINT CHR$(7) will NOT sound the bell since the
  179.           Amiga Shell/CLI and RAW: windows do not respond to CHR$(7)
  180.           in the same way as the AmigaBASIC output window.
  181.   
  182. CINT        - syntax: CINT(n)
  183.         - Converts n to a signed short integer by rounding the 
  184.           fractional portion.
  185.         - When the fractional portion is exactly .5, CINT *always*
  186.           rounds up in ACE, whereas in AmigaBASIC if the integer
  187.           portion is even, CINT rounds down, and up if the integer
  188.           portion is odd.
  189.  
  190. CIRCLE        - syntax: CIRCLE (x,y),radius[,color-id,start,end,aspect]
  191.         - Start and end angles are specified in DEGREES *not* radians
  192.           because this is probably more useful when thinking about 
  193.           circles. (Note: this may be changed to radians in future).
  194.         - If a whole ellipse is to be drawn, the graphics library
  195.           DrawEllipse() function is used. However, if the start
  196.           angle is not 0 or the end angle is not 359 (these are
  197.           the defaults when not specified), a different routine 
  198.           is used. The latter is quite slow.
  199.         - The default ASPECT is .44 as in AmigaBASIC.
  200.  
  201. CLNG        - syntax: CLNG(n)
  202.         - Converts n to a signed long integer by rounding the 
  203.           fractional portion.
  204.         - When the fractional portion is exactly .5, CLNG *always*
  205.           rounds up in ACE, whereas in AmigaBASIC if the integer
  206.           portion is even, CLNG rounds down, and up if the integer
  207.           portion is odd.
  208.  
  209. CLOSE        - syntax: CLOSE [#]filenumber[,[#]filenumber..] 
  210.           where filenumber represents an open file.
  211.         - Closes at least one open file. 
  212.         - Note that in ACE, CLOSE must be followed by at least one 
  213.           filenumber, unlike AmigaBASIC.
  214.         - See section on files in ace.doc.
  215.  
  216. CLS        - Clears the current output window or screen and sets the
  217.           pen position to the upper left corner.
  218.         - CLS does not affect any other screens or windows except 
  219.           the one currently active.
  220.  
  221. COLOR        - syntax: color fgnd-id[,bgnd-id]
  222.         - Changes the foreground and/or background color to
  223.           fgnd-id and bgnd-id respectively.
  224.         - Note that in ACE, you can change just the foreground
  225.           color, both the foreground and background colors,
  226.           but not the background color alone.
  227.         - This may be changed in a future revision.
  228.         - The PALETTE command is used to change the colors 
  229.           corresponding to given color-ids.
  230.  
  231. CONST *        - syntax: CONST <ident> = [+|-]<constant>[,..]
  232.           where <constant> is a signed numeric constant.
  233.         - Defines a named numeric constant or constants, the type
  234.           being *unaffected* by the the DEFxxx directives or type 
  235.           (%&!#$) suffixes. All constant definitions are GLOBAL.
  236.         - Any number of definitions can be separated by commas.
  237.  
  238. COS        - syntax: COS(n)
  239.         - Returns the cosine of n.    
  240.  
  241. CSNG        - syntax: CSNG(n)
  242.         - Converts n to a single-precision value.
  243.  
  244. CSRLIN        - returns the print line in the current user-defined SCREEN 
  245.           as set by LOCATE.
  246.         - If called when output is to a window, zero is returned.
  247.         - In other words, CSRLIN currently only has meaning for 
  248.           screens (see also POS).
  249.  
  250. CSTR *        - syntax: CSTR(<address>) 
  251.         - Coerces a long integer address into a string. 
  252.         - This is intended for taking an allocated area of memory
  253.           and using it as a string of characters. Be aware that this
  254.           memory block must be NULL terminated.
  255.         - A typical use for CSTR is something like this:
  256.         
  257.             x$=CSTR(addr&)
  258.  
  259.         - The maximum string length of MAXSTRINGLEN bytes in some 
  260.           functions still applies. Ignore this at your own peril! 
  261.  
  262. DATA        - syntax: DATA [numeric-constant | string-constant][,..]
  263.         - Stores numeric and/or string constants into a global
  264.           data list to be accessed by the READ statement.
  265.         - DATA statements may be located anywhere in a program and
  266.           non-executable.
  267.         - Strings need only be enclosed in quotes if they contain 
  268.           commas, spaces or colons or other non-identifier characters.
  269.         - In ACE, all numbers from DATA statements are currently stored 
  270.           as single-precision values with a possible loss of accuracy 
  271.           if LARGE long integers are originally specified. This may
  272.           be rectified in a future revision. Thus far however, I have 
  273.           not had problems because of it. In order to overcome it for
  274.           now, do something like the following:
  275.  
  276.             #include <longval.h>
  277.             READ X$
  278.             X=longval&(X$)        '..longval& returns the value.
  279.             DATA "123456789"
  280.  
  281.         - In the above example, the BASIC function VAL is substituted 
  282.           with LONGVAL& because the former always returns a single
  283.           precision value which is what we are trying to avoid.
  284.  
  285. DATE$        - Returns the current system date as a ten-character string
  286.           of the format: mm-dd-yyyy.
  287.  
  288. DAY *        - Returns the day of the week as an integer from 0..6,
  289.           where 0=Sunday and 6=Saturday.
  290.         - The value returned by DAY reflects the last call to DATE$.
  291.  
  292. DECLARE        - This has three uses in ACE: 
  293.  
  294.           1. DECLARE FUNCTION <func-name>[%&!] LIBRARY <lib-name>
  295.              (see section on shared library access in ace.doc)
  296.  
  297.           2. DECLARE SUB [<type>] subprogram-name[(parameter-list)] 
  298.  
  299.              which is used for forward SUB declarations.
  300.              (see also section on subprograms in ace.doc)
  301.  
  302.           3. DECLARE STRUCT <type> [*] <ident1> [,[*] <identN>..]
  303.              
  304.              where a structure variable of type <struct-type> is
  305.              created. If "*" precedes the variable identifier,
  306.              a pointer to the structure is created, otherwise
  307.              a BSS object is allocated. In both cases, "identN"
  308.              holds the start address of the structure. In the
  309.              latter case, the address is resolved at load time
  310.              while in the former, the address is allocated at
  311.              run time (eg: with ALLOC).
  312.  
  313.         - Only the first usage is supported by AmigaBASIC (although
  314.           the syntax is slightly different).
  315.   
  316. The following DEFxxx commands are GLOBAL data type 
  317. directives which affect data objects in both the main 
  318. program and subprograms.
  319.  
  320. The general syntax is: DEFxxx <letter>[,|-<letter>] [..]
  321. eg:
  322.         DEFLNG    a-z
  323.   
  324. declares all data objects to be of type LONGINT unless overridden by another 
  325. DEFxxx directive, variable declaration or trailing character (%&!#$).
  326.  
  327. DEFDBL currently defaults to single-precision since double-precision is not 
  328. yet supported.
  329.  
  330. DEFINT
  331. DEFLNG
  332. DEFSNG
  333. DEFDBL        
  334. DEFSTR         
  335.  
  336. DIM        - syntax: DIM <name>(<i>[,..]) [SIZE <n>] [ADDRESS <addr>][,..] 
  337.         - ACE requires that ALL arrays be dimensioned before use.
  338.         - For a subscript range of 0..n, you must DIMension
  339.           an array with an index of n.
  340.         - Up to 10 dimensions can be specified with up to
  341.           32767 elements per dimension. Each dimension must be 
  342.           specified as a short numeric constant (literal or defined). 
  343.         - The SIZE option is for the specification of string element
  344.           length other than the default MAXSTRINGLEN value.
  345.         - The ADDRESS option allows you to specify some arbitrarily 
  346.           allocated area of memory (ALLOC'd, string etc) for
  347.           the array space.
  348.         - Both options (SIZE and ADDRESS) may be used together in
  349.           DIM. This is not so for simple string variables where
  350.           only one or the other may be used (see STRING command).
  351.         - SHARED is not an option and ACE arrays are shared in the
  352.           same way as variables. See "Subprograms" in ace.doc.
  353.  
  354. EOF        - syntax: EOF(n)
  355.           where n is the filenumber of an open file.
  356.         - EOF is a function which returns either -1 or 0 depending
  357.           upon whether the file pointer has reached the end-of-file
  358.           or not. 
  359.         - If the file doesn't exist or hasn't been opened, EOF 
  360.           returns -1. 
  361.  
  362. END        - Closes libraries and passes control back to parent process.
  363.         - Don't use END within an IF..THEN..END IF block. Use STOP
  364.           instead which is functionally equivalent in ACE.
  365.  
  366.  
  367. EQV        - Boolean operator: X EQV Y.
  368.  
  369.             X Y    Out
  370.             -----------
  371.             T T    T
  372.             T F    F
  373.             F T    F
  374.             F F    T            
  375.                         
  376. EXIT SUB    - This command can only be used inside a subprogram and
  377.           when encountered, has the effect of passing control back
  378.           to the caller of the subprogram in which it appears.
  379.         - If the current instantiation of the subprogram is the
  380.           result of a recursive call, control will be returned
  381.           to the previous instantiation of the same subprogram.
  382.  
  383. EXP        - syntax: EXP(n)
  384.         - Returns e to the power n, where e is the base of
  385.           natural logarithms or 2.7182818284590.
  386.  
  387. EXTERNAL *    - syntax: EXTERNAL [FUNCTION] <identifier>[%&!$]
  388.         - Used to declare an external function or variable.
  389.  
  390. FILES        - syntax: FILES [TO <storefile>] [,<target>]
  391.         - Gives an unsorted directory listing ala AmigaBASIC
  392.           except that ACE's version takes two optional arguments
  393.           while AmigaBASIC's takes one (<target>).
  394.         - If <storefile> is specified, the listing will be
  395.              captured by that file.
  396.            - If <storefile> is omitted, it is assumed that the
  397.           program containing the FILES command was invoked 
  398.           from a shell or CLI (since the listing will be 
  399.           displayed). 
  400.            - The <target> argument can be a file, directory or
  401.              AmigaDOS device name which is to be the subject
  402.           of the directory listing.
  403.  
  404. FIX        - syntax: FIX(n)
  405.         - The function returns the truncated integer portion of n.
  406.         - FIX(n) is equivalent to SGN(n)*INT(ABS(n)).
  407.         - Whereas INT(n) rounds off a negative number
  408.           to the next lowest whole number, FIX does not.
  409.  
  410.         or
  411.  
  412.         - syntax: FIX n
  413.         - The command which is found only in ACE is intended to have
  414.           a similar effect to the FIX button found on a HP calculator,
  415.           that is, to change the number of decimal place ACE rounds a
  416.           single-precision number to.
  417.         - FIX utilises the ami.lib function arnd(). When the value of
  418.           n is anything other than 8, arnd() is invoked. This affects
  419.           the commands: PRINT, PRINTS, WRITE#, PRINT# and STR$. 
  420.         - FIX should be considered experimental since I have not 
  421.           completely figured out what all the values of n (as used 
  422.           directly by arnd()) do yet.
  423.         - In a future release, a given value for n may have different 
  424.           results than it does now. Currently, n may be positive or 
  425.           negative.
  426.         
  427.             Examples
  428.             --------
  429.  
  430.             FIX -3
  431.             PRINT 12.3456
  432.  
  433.             would display: 12.35
  434.  
  435. FOR..NEXT    - syntax: FOR <variable>=x TO y [STEP z]
  436.         - The statements between FOR and NEXT are iterated
  437.           the number of times it takes for <variable> to become
  438.           equal to or greater than y (or less than y if z is negative)
  439.           starting from x. The loop index <variable> is incremented 
  440.           by z, or 1 if STEP is not specified. 
  441.            - NEXT can only be followed by a variable, colon or
  442.           comment and must appear on a separate line or in a 
  443.           multi-statement (not after THEN for example). 
  444.         - Any attempt to use a shared variable as a FOR loop index
  445.           will result in a compilation error.
  446.  
  447. FORWARD *    - syntax: FORWARD n
  448.         - Move the turtle forward n steps.
  449.  
  450. FRE        - syntax: FRE(n)
  451.           where n is -1,0,1,2 or 3.
  452.         - Since ACE's run-time environment is different to
  453.           AmigaBASIC's, FRE returns different values and 
  454.           takes different arguments than in AmigaBASIC.
  455.         - FRE returns the amount of free system memory according 
  456.           to n:
  457.  
  458.             n = -1    ->  total CHIP + FAST memory free.
  459.             n =  0  ->  total CHIP memory free.
  460.             n =  1  ->  total FAST memory free.
  461.             n =  2  ->  largest contiguous CHIP memory available.
  462.             n =  3  ->  largest contiguous FAST memory available.
  463.   
  464. GOSUB..RETURN    - with labels or line numbers.
  465.  
  466. GOTO        - with labels or line numbers.
  467.  
  468. HANDLE *    - syntax: HANDLE(n)
  469.           where n is the file number of an OPENed file (1..255).
  470.         - This function returns a long integer which is a pointer to
  471.           a dos file handle suitable for use with dos.library functions
  472.           such as Read (xRead when declared in ACE/AmigaBASIC). 
  473.         - If HANDLE returns 0& the file does not exist or can't be
  474.           opened as requested.
  475.  
  476. HEADING *    - Returns the turtle's current heading in degrees (0..359).
  477.  
  478. HEX$        - syntax: HEX$(n)
  479.         - Returns a string which represents the hexadecimal value
  480.           of the decimal argument n.
  481.  
  482. HOME *        - Move the turtle back to its home position.
  483.  
  484. IF..THEN..[ELSE..]
  485. IF..GOTO..[ELSE..]
  486. IF..THEN
  487. .
  488. [ELSE]
  489. .
  490. END IF         - ELSEIF is not yet implemented.
  491.         - IF..[ELSE]..END IF blocks can be nested.
  492.         - Use STOP rather than END before an END IF
  493.           otherwise the compiler will get confused.
  494.  
  495. IMP        - Boolean operator: X IMP Y.
  496.  
  497.             X Y    Out
  498.             -----------
  499.             T T    T
  500.             T F     F
  501.             F T    T
  502.             F F    T        
  503.  
  504. INKEY$        - Returns a single character string when a keystroke 
  505.           is pending, otherwise the NULL string is returned.
  506.         - If input is from the shell/CLI or a user-defined window, 
  507.           dos is employed to return the pressed key's value, otherwise 
  508.           Intuition is used (this is transparent to the programmer).
  509.         - INKEY$ works fine in user-defined windows (RAW:), but since
  510.           a normal CON: window intercepts all keystrokes, INKEY$ is 
  511.           useless in a shell/CLI.
  512.         - When using the dos library functions, INKEY$ is SLOW,
  513.           so don't use it in a time-critical loop. In particular,
  514.               the use of WaitChar() slows things down quite a bit since
  515.           it forces a pause of at least 1 tick each time INKEY$ is 
  516.           called.
  517.         - Things are somewhat faster when INKEY$ gets input from a
  518.           user-defined screen's window (see section on screens in 
  519.           ace.doc).
  520.  
  521. INPUT$        - syntax: INPUT$(X,[#]filenumber)
  522.         - Returns a string of X characters from the filenumber'th file.
  523.         - There is a 32K upper limit for X in ACE, but if you
  524.           want to read a whole file for example, and the file length
  525.           (determined by LOF) is greater than MAXSTRINGLEN, you 
  526.           should do the following:
  527.  
  528.             STRING X$ SIZE N     '..N <= 32766+1 (+1 for EOS)
  529.             OPEN "I",#1,filename$
  530.              X$=INPUT$(LOF(1),#1)
  531.             CLOSE #1
  532.  
  533.           or if you want to allocate space at run-time according to the
  534.           exact file size:
  535.  
  536.             bytes& = LOF(1) + 1
  537.             addr& = ALLOC(bytes&,5)
  538.             STRING X$ ADDRESS addr&
  539.             OPEN "I",#1,filename$
  540.              X$ = INPUT$(bytes&,#1)
  541.             CLOSE #1
  542.         
  543.         - This method should only be used for small text files as it
  544.           is slow, and text is really the only useful thing to put in 
  545.           a string if you wish to manipulate it. Many string functions
  546.           will react unexpectedly to non-text characters in strings.
  547.         - If you wish to read a large file rapidly, it's best to use 
  548.           the dos.library function Read (declared as xRead in BASIC).
  549.           The sound player play.b gives a good example of this.
  550.         - In general INPUT$ is most useful for reading a few characters
  551.           at a time from a file. If you wish to read a line at a time,
  552.           use LINE INPUT# and INPUT# if you want to read numbers or
  553.           strings. 
  554.         - INPUT$ in ACE is only used for sequential file input, so
  555.           the filenumber is not optional. In AmigaBASIC, if the latter
  556.           is omitted, input is taken from the keyboard. Not so in ACE.
  557.         - See also section on files in ace.doc.
  558.  
  559. INPUT        - syntax: INPUT [prompt-string] [;|,] var1 [[;|,] varN..]
  560.         - Strings, integers and fixed-point or exponential format 
  561.           reals can be input from the keyboard.
  562.         - Each value must appear on a separate line even when
  563.           a single INPUT statement contains multiple variables.  
  564.         - If ";" precedes a variable a "? " will appear, while if 
  565.           a "," is used no "? " will appear.
  566.         - INPUT only takes input from the shell/CLI or an ACE window.
  567.           If you need input from a screen, use the functions in 
  568.           inputs.h: INPUTS$, INPUTS%, INPUTS& and INPUTS!.
  569.           An example follows:
  570.  
  571.             #include <inputs.h>
  572.  
  573.             SCREEN 1,640,200,2,2
  574.  
  575.             PALETTE 0,0,0,0
  576.             PALETTE 1,1,1,1
  577.             PALETTE 2,1,0,0
  578.             PALETTE 3,0,1,0
  579.  
  580.             PRINTS "Enter a long integer: ";
  581.             X& = inputs&
  582.             PRINTS "You entered ";X&
  583.  
  584.             PRINTS "Press q to quit"
  585.             WHILE UCASE$(INKEY$) <> "Q":WEND
  586.  
  587.             SCREEN CLOSE 1
  588.  
  589. INPUT#        - syntax: INPUT #filenumber,<variable-list>
  590.         - Reads data items from a sequential file.
  591.         - The variables in <variable-list> must each match the type
  592.           of item being read.
  593.         - If unambiguous data format is required, it is best to
  594.           use WRITE# to store the values that INPUT# will read
  595.           since WRITE# separates each item with commas and delimits
  596.           strings with double quotes allowing for spaces. WRITE# will
  597.           also result in more efficient use of disk space and faster
  598.           reading by INPUT#.
  599.         - ACE accepts white space (line feeds, spaces, tabs), commas
  600.           and quotes as delimiters for each field in a sequential file.
  601.         - AmigaBASIC and ACE sequential file formats are very nearly
  602.           identical.
  603.         - See also files section in ace.doc.
  604.  
  605. INSTR        - syntax: INSTR([I,]X$,Y$)
  606.         - INSTR searches for the first occurrence of Y$ in X$ and
  607.           returns the character position from 1..N in X$.
  608.         - If the optional offset I is specified, the search starts
  609.           from that position, otherwise the search starts from the
  610.           first character in X$.
  611.         - If I is greater than len(X$) or X$="" or Y$ is not found
  612.           in X$ or len(Y$) > len(X$), INSTR returns 0.
  613.         - If Y$="", INSTR returns I or 1.
  614.         - X$ and Y$ can be string expressions, variables or literals
  615.           or any combination thereof.
  616.  
  617. INT        - syntax: INT(n)
  618.         - Returns the largest integer less than or equal to n.
  619.  
  620. KILL        - syntax: KILL <filespec>
  621.         - Deletes a file or directory.
  622.  
  623. LEFT$        - syntax: LEFT$(X$,I)
  624.         - Returns a string which contains the leftmost I characters
  625.           of X$.
  626.         - If I > len(X$), the whole string (X$) is returned.
  627.         - If I = 0, the NULL string is returned.
  628.  
  629. LEN        - syntax: LEN(X$)
  630.         - Returns the number of characters in X$.
  631.  
  632. LET        - syntax: [LET] <variable> = <expression>
  633.         - LET assigns a value to a variable.
  634.         - Its use is optional so that LET X=1 is equivalent
  635.           to X=1.
  636.  
  637. LIBRARY        - syntax: LIBRARY [CLOSE] <libname>
  638.         - Opens or closes an Amiga shared library.
  639.         - Note that <libname> is not enclosed in quotes
  640.           and does not end in .library, so that to open
  641.           graphics.library, the syntax is: LIBRARY graphics. 
  642.         - See "Shared library function calls" section in ace.doc.
  643.  
  644. LINE        - The syntax of this command - apart from the simple 
  645.           case of LINE (x1,y1)-(x2,y2)[,color,b[f]] - is a little
  646.           unclear from the AmigaBASIC manual.
  647.  
  648.         - The syntax of the LINE command in ACE is currently as 
  649.           follows:
  650.  
  651.             LINE [STEP](x1,y1)[-(x2,y2)[,[color],[b[f]]]]
  652.  
  653.         - The second STEP directive has been omitted, but may be
  654.           added in a future revision.
  655.         - A statement such as LINE STEP (100,90) will cause a line
  656.           to be drawn from the last referenced coordinate to 100,90.
  657.           In addition, this use of LINE does *not* allow for colour
  658.           setting as can be seen from the ACE syntax specification
  659.           whereas LINE (100,90)-(200,150),color does. The same is
  660.           true for the "b" and "bf" options. A future version may
  661.           correct this problem.
  662.         - Note: x1 must be >= x2 and y1 must be >= y2 otherwise
  663.           weirdness will result!
  664.  
  665. LINE INPUT    - syntax: LINE INPUT #filenumber,<string-variable>
  666.         - Reads a line from the filenumber'th sequential file and
  667.           stores it in <string-variable>.
  668.         - If <string-variable> does not exist, ACE creates it.
  669.         - Lines are delimited by a line-feed character (ASCII 10)
  670.           and the string which is returned consists of the characters
  671.           up to but not including the line-feed.
  672.         - Note that the AmigaBASIC manual (8-72) shows a semicolon
  673.           instead of a comma in the above syntax which is incorrect
  674.           since AmigaBASIC itself accepts only a comma.
  675.         - The alternative form of LINE INPUT for keyboard input is
  676.           not currently implemented in ACE.
  677.         - LINE INPUT will not read more than MAXSTRINGLEN characters.
  678.         - See also INPUT$ (which will read up to 32K of characters)
  679.           INPUT# and ace.doc's section on files.
  680.     
  681. LOCATE        - syntax: LOCATE line[,column].
  682.         - LOCATE changes the printing position for the current
  683.           screen or window.
  684.         - Note that the use of LOCATE on a screen also changes 
  685.           the next graphics drawing coordinates.
  686.  
  687. LOF        - syntax: LOF(n) 
  688.           where n is the file number of an open file. 
  689.         - LOF returns the length of the file in bytes. 
  690.         - If the file is not open or non-existent, LOF returns 0.
  691.                 
  692. LOG        - syntax: LOG(n)
  693.         - Returns the natural logarithm of n (log base e of n).
  694.         - The argument n should be greater than zero.
  695.  
  696. LONGINT    *    - syntax: LONGINT <identifier>[,..]
  697.         - Declares and initialises one or more long integer variables.
  698.  
  699. MID$        - syntax: MID$(X$,I[,J])
  700.         - Only the MID$ *function* is currently supported by ACE.
  701.         - Returns a string containing J characters from X$
  702.           starting from the Ith character.
  703.         - If J is omitted or there are fewer than J characters 
  704.           to the right of (and including) the Ith character, all 
  705.           characters from the Ith position to the end of the string 
  706.           are returned.
  707.         - If I > len(X$), MID$ returns the NULL string.
  708.   
  709. MOD        - Modulo arithmetic operator: X MOD Y.
  710.  
  711.             eg: 101 MOD 10 = 1
  712.     
  713. MOUSE        - syntax: MOUSE(n)
  714.         - Returns information about the current status of the mouse.
  715.         - Values of n ranging from 0..2 are meaningful in ACE.
  716.         - MOUSE(0) just returns -1 or 0 to indicate whether the left 
  717.           mouse button is currently being pressed or not.
  718.         - MOUSE(1) returns the X location of the mouse pointer
  719.           in the current output window or screen.
  720.         - MOUSE(2) returns the Y location of the mouse pointer
  721.           in the current output window or screen.
  722.          or
  723.         - syntax: MOUSE [ON|OFF|STOP] 
  724.         - See Event trapping section in ace.doc.
  725.  
  726. NAME        - syntax: NAME <filespec1> AS <filespec2>
  727.         - Renames a file or directory.
  728.     
  729. NOT        - Boolean operator: NOT X.
  730.  
  731.             X    Out
  732.             -----------
  733.             T    F
  734.             F    T
  735.  
  736. OCT$        - syntax: OCT$(n)
  737.         - Returns the octal string representation of the long
  738.           integer value n.
  739.  
  740. ON..GOTO/GOSUB    - syntax 1: ON <integer-expr> GOTO | GOSUB <label> | <line>
  741.  
  742.           eg: ON n GOTO one,two,three,four,five
  743.             
  744.           such that if n=1 the program will branch to the label 
  745.           "one" and if n=4 the branch will be to "four".
  746.  
  747.         - syntax 2: ON <event-spec> GOTO | GOSUB <label> | <line>
  748.         - See "Event Trapping" section in ace.doc.
  749.  
  750. OPEN        - syntax: OPEN mode,[#]filenumber,filespec
  751.           which is the same as syntax 1 in AmigaBASIC
  752.           except that no file-buffer-size can be specified.
  753.         - Mode is an upper-case character where:
  754.  
  755.             - "I" = open file for input
  756.             - "O" = open file for output
  757.             - "A" = open file for append
  758.         
  759.         - Filenumber is a value from 1..255
  760.         - Filespec is a string containing the file name
  761.           (eg: "test.doc", "df1:letters/santa").
  762.         - Multiple files can be open at one time.        
  763.  
  764. OPTION *    - syntax: OPTION <switch>+|-[,<switch>+|-..]
  765.         - Compiler directives (switches) can be issued via this
  766.           command instead of from the command line. The latter
  767.           only allows for compiler directives to be *activated*.
  768.         - Each switch must be followed by a "+" or "-" with
  769.           the former activating the directive and the latter
  770.           neutralising it.
  771.         - Switches currently implemented are: b,c,E,i,l,O
  772.          - See ace.doc "Compiler options" for details of each
  773.           switch. Notice that for switches i and O, activation 
  774.           or deactivation takes effect at the end of compilation.
  775.  
  776. OR        - Boolean operator: X OR Y.
  777.  
  778.             X Y     Out
  779.             -----------
  780.             T T    T
  781.             T F    T
  782.             F T    T
  783.             F F     F
  784.  
  785. PAINT        - syntax: PAINT (x,y)[[,color-id][,border-id]]
  786.         - PAINT flood fills an enclosed region with the
  787.           color specified by color-id and if the latter
  788.           is omitted, the current foreground pen is used.
  789.         - If border-id is not specified, color-id is used 
  790.           to determine when to stop the filling process by 
  791.           looking for a border of that color. The use of 
  792.           border-id allows a region to be filled with one 
  793.           color and be bordered by another.
  794.         - x and y can be anywhere within the enclosed region.
  795.         - Note that the ACE version of PAINT has no STEP 
  796.           option so x and y constitute an absolute coordinate.
  797.         - STEP may be added in a future revision.
  798.  
  799. PALETTE        - syntax: PALETTE color-id,R,G,B
  800.           where R,G,B are the red, green and blue colour 
  801.           components of color-id.
  802.         - Palette changes colors in the current screen 
  803.           (including Workbench!). 
  804.  
  805. PATTERN        - syntax: PATTERN [line-pattern][,area-pattern] | RESTORE
  806.         - Same as in AmigaBASIC with the addition of a RESTORE
  807.           option. PATTERN RESTORE resets the line and area patterns
  808.           to their default values.
  809.         - The line-pattern is a short integer value.
  810.         - The area-pattern is a DIM'd short integer array. 
  811.         - The number of elements in area-pattern must be a power of 2.
  812.  
  813. PEEK        - syntax: PEEKx(<address>)
  814. PEEKL
  815. PEEKW        - These three commands return an 8-bit, 32-bit and 16-bit
  816.           value from memory (<address>) respectively.
  817.  
  818. PENDOWN *    - Lowers the turtle's "pen".
  819.  
  820. PENUP *        - Raises the turtle's "pen".
  821.         
  822. POINT        - syntax: POINT(x,y)
  823.         - Returns the color-id of a point in the current output
  824.           window or screen.
  825.  
  826. POKE        - syntax: POKEx <address>,<numeric-value>
  827. POKEL
  828. POKEW        - These three commands change the contents of <address>
  829.           to <numeric-value>.
  830.         - Unless you know what you are POKEing and why, don't
  831.           or you can expect a visit from the Guru.
  832.         
  833. POS        - Returns the print column in the current user-defined SCREEN 
  834.           as set by LOCATE.
  835.         - If called when output is to a window, zero is returned.
  836.         - In other words, POS currently only has meaning for 
  837.           screens (see also CSRLIN).
  838.         - Note that the syntax is different from AmigaBASIC where a
  839.           dummy argument of zero is used: POS(0).
  840.  
  841. POTX *        - syntax: POTX(n)
  842.           where n=0 or 1 (game port 1 or 2).
  843.         - Returns short integer value corresponding to
  844.           current potentiometer reading on pin 5 of game port.
  845.  
  846. POTY *        - syntax: POTY(n)
  847.           where n=0 or 1 (game port 1 or 2).
  848.         - Returns short integer value corresponding to
  849.           current potentiometer reading on pin 9 of game port.
  850.  
  851. PRINT        - syntax: PRINT [<expression>][,|;| ..]
  852.           where <expression> is a string or numeric value to
  853.           be printed at the current print location of the current
  854.           output window. 
  855.         - LOCATE can be used to set the location for the next PRINT 
  856.           command.
  857.         - PRINT can be abbreviated to '?' as in AmigaBASIC.
  858.         - If <expression> is followed by a semi-colon, a line-feed
  859.           will not occur before the next PRINT.
  860.         - If <expression> is followed by a comma, the effect is
  861.           the same except that first, two horizontal tabs (CHR$(9)) 
  862.           are sent to the output window.
  863.         - Note that two ASCII 9s do not have exactly the same effect 
  864.           as an AmigaBASIC tab, but the result is very similar (about
  865.           17 spaces between TABs instead of 15). If spacing is critical
  866.           you should use TAB or SPACE$.
  867.  
  868. PRINT#        - syntax: PRINT #filenumber,<expression>[,|;| ..]
  869.           where <expression> is a string or numeric value to
  870.           be printed at the current print location in the 
  871.           filenumber'th file. 
  872.         - PRINT can be abbreviated to '?' as in AmigaBASIC.
  873.         - This version of PRINT writes values to a file in the 
  874.           same format as they would appear in a window.
  875.         - One oddity is that since ACE strings are NULL-terminated,
  876.           and this NULL (ASCII 0) is normally not displayed, any 
  877.           attempt to send this character to a file, eg:
  878.  
  879.               PRINT #filenumber,CHR$(0) 
  880.  
  881.           should by all rights be ignored. However, since some
  882.           programs write NULLs to files as delimiters, ACE does NOT
  883.           ignore a lone CHR$(0). A consequence of this is that if
  884.           you send an empty - LEN(<string>) = 0 - string to a file, 
  885.           an ASCII 0 will be written. This is also holds true for 
  886.           WRITE #filenumber,<string>. Just check the length of a 
  887.           string before sending it to a file if in doubt.
  888.  
  889. PRINTS *    - syntax: PRINTS [<expression>][,|;| ..]
  890.           where <expression> is a string or numeric value to
  891.           be printed at the current x,y location of an open
  892.           screen. SETXY or LOCATE can be used to set the X,Y 
  893.           coordinates for the next PRINTS command.
  894.         - PRINTS behaves in the same way as PRINT except that text 
  895.           is clipped after the last column. 
  896.         - see also CSRLIN and POS. 
  897.   
  898. PSET        - syntax: PSET [STEP] (x,y)[,color-id]
  899.         - Plots a point in the current output window or 
  900.           screen.
  901.         - If color-id is not specified, the current
  902.           foreground color is used.
  903.         - If STEP is specified, the point is relative to
  904.           the current x,y location as set by the last
  905.           graphics command.
  906.  
  907. RANDOMIZE    - syntax: RANDOMIZE <expression>
  908.         - Seeds the random number generator.
  909.         - *requires* an argument. TIMER and all
  910.           other arguments will be coerced to long integers.
  911.         - RANDOMIZE TIMER is the most commonly used syntax.
  912.  
  913. READ        - syntax: READ <variable>[,<variableN>..]
  914.         - Assigns <variable> the value of the next item in the 
  915.           global data list as created by DATA statements in
  916.           the current program.
  917.         - The <variable> must be of the same type as the data 
  918.           item to be read otherwise an unexpected value will be
  919.           assigned to <variable>.  
  920.         - See also DATA (especially re: READing long values).
  921.     
  922. REM        - syntax: REM <comment>
  923.         - A single-line comment.
  924.         - All characters after REM until the end of line are 
  925.           ignored.
  926.         - REM can be substituted by an apostrophe as in AmigaBASIC.
  927.         - While REM is treated as a true statement, and must
  928.           either appear on a separate line or after a ":" in a 
  929.           multi-statement, an apostrophe followed by a comment
  930.           can appear anywhere in the text of a program. 
  931.         - Note that ACE also supports block comments: {..}.
  932.         - The ACE compiler can handle the three types of comments
  933.           while the pre-processor APP can only handle the ' and 
  934.           {..} forms. Some form of commenting is required in APP
  935.           so that pre-processor commands can be commented out. 
  936.  
  937. REPEAT..UNTIL *    - syntax: REPEAT
  938.               .
  939.               .
  940.               UNTIL <condition>
  941.  
  942.           where <condition> is an expression which reduces
  943.           to a boolean (true/false) value.
  944.  
  945.         - Statements inside the REPEAT and UNTIL are executed
  946.           until the <condition> is true (ie: non-zero).      
  947.         - Styled after the Pascal REPEAT..UNTIL construct.
  948.         - The loop is *always* executed at least once.
  949.  
  950. RESTORE        - syntax: RESTORE
  951.         - Resets the DATA pointer to the first DATA statement
  952.           in the program.
  953.         - Note that there is no optional label in the ACE version
  954.           of RESTORE. This may be added in a future revision.
  955.  
  956. RIGHT$        - syntax: RIGHT$(X$,I)
  957.         - Returns a string which contains the rightmost I characters
  958.           of X$.
  959.         - If I > len(X$), the whole string (X$) is returned.
  960.         - If I = 0, the NULL string is returned.
  961.  
  962. RND        - syntax: RND
  963.         - ACE's RND function takes no parameter and always returns a
  964.           single-precision pseudo-random value between 0 and 1.
  965.  
  966. SADD        - syntax: SADD(<string-expression>)
  967.         - Returns the address of <string-expression> which can be
  968.           a string literal, variable or expression.
  969.         - Unlike AmigaBASIC, string allocations after a call to
  970.           SADD have no impact upon the address of <string-expression>.
  971.         - VARPTR can also safely be used to find the address of
  972.           a string variable.
  973.                   
  974. SAY        In ACE, there is a SAY command and a SAY function.
  975.  
  976.         SAY command 
  977.         -----------
  978.         - syntax: SAY <phoneme-string>[,mode-array]
  979.         - Same as AmigaBASIC's SAY command: speak a phoneme string.
  980.         - The <phoneme-string> can be a string literal, expression
  981.           or variable, while the optional mode-array is a 9-element 
  982.           (0..8) DIM'd short integer array.
  983.         - The mode-array is allowed, and the following parameters
  984.           are supported:
  985.  
  986.             Argument     Element    Values        Default    
  987.             --------     -------    ------        -------
  988.             pitch         0        65..320        110
  989.             inflection   1        0 or 1        0    
  990.             rate         2        40..400        150
  991.             voice         3        0 or 1        0
  992.             tuning         4        5000..28000    22200 (Hz)
  993.             volume         5        0..64        64
  994.             channel         6        0..11        10
  995.             mode         7        0 or 1        0
  996.             control         8              0,1 or 2    0
  997.  
  998.         - Inflection=0 allows inflections and emphasis of syllables 
  999.           while inflection=1 gives a monotone voice.
  1000.         - The voice parameter specifies gender: 0=male; 1=female.
  1001.         - Audio channel values have the same meaning as in AmigaBASIC:
  1002.  
  1003.             Value    Channel(s)
  1004.             -----     ----------
  1005.             0    0
  1006.             1    1
  1007.             2    2
  1008.             3    3
  1009.             4    0 and 1
  1010.             5    0 and 2
  1011.             6    3 and 1
  1012.             7    3 and 2
  1013.             8    either available left channel
  1014.             9    either available right channel
  1015.             10    either available left/right pair of channels
  1016.             11    any available single channel        
  1017.  
  1018.         - Mode is used to specify synchronous or asynchronous speech
  1019.           (0 and 1 respectively).
  1020.         - Control is used when mode=1 to determine what action is
  1021.           to be taken when asynchronous speech is active. If control
  1022.           is set to 0, the current SAY command waits until the last
  1023.           SAY is finished before executing. When control=1 the last
  1024.           SAY statement is cancelled and speech processing stops
  1025.           until the next call to SAY. When control=2 ACE interrupts
  1026.           the last SAY command and initiates the current one.
  1027.         - The defaults are the same as in AmigaBASIC.
  1028.  
  1029.         SAY function    (only works properly under 2.04 or higher)
  1030.         ------------
  1031.         - syntax: SAY(n)
  1032.  
  1033.           where n equals 0, 1 or 2.
  1034.  
  1035.           SAY(0) - returns true or false (-1 or 0) to indicate
  1036.                whether there is currently active asynchronous
  1037.                speech.
  1038.  
  1039.           SAY(1) - returns the width of the "mouth" corresponding
  1040.                to the phoneme being spoken.
  1041.     
  1042.           SAY(2) - returns the height of the "mouth" corresponding
  1043.                to the phoneme being spoken.
  1044.     
  1045.         - SAY(0) allows for monitoring of the asynchronous 
  1046.           speech process (see details of mode-array above).
  1047.         - Use of SAY(1) and SAY(2) allows an animated mouth
  1048.           to be drawn. See the program mouth.b for an example.
  1049.         - SAY(1)'s and SAY(2)'s values reflect the last call
  1050.           to SAY(0) and so must be used in conjunction with 
  1051.           the latter.  
  1052.         
  1053. SCREEN        - The SCREEN statement syntax is the same as in AmigaBASIC:
  1054.  
  1055.             SCREEN screen-id,width,height,depth,mode
  1056.  
  1057.           mode 1=lores, 2=hires, 3=lores/interlaced, 4=hires/interlaced.
  1058.  
  1059.         - The SCREEN function (ACE only) syntax is SCREEN(n), where:
  1060.  
  1061.           SCREEN(0) - returns a pointer to the Intuition window
  1062.           SCREEN(1) - returns a pointer to the Intuition screen
  1063.           SCREEN(2) - returns a pointer to the screen's rastport
  1064.           SCREEN(3) - returns a pointer to the screen's viewport
  1065.  
  1066. SCREEN CLOSE    - syntax: SCREEN CLOSE screen-id
  1067.         - Closes a single ACE screen. 
  1068.  
  1069. SCROLL        - syntax: SCROLL (xmin,ymin)-(xmax,ymax),delta-x,delta-y
  1070.         - Scrolls bits inside the specified rectangle.
  1071.         - Delta-x and delta-y specify motion right and down 
  1072.           respectively.
  1073.         - Negative delta values yield  motion left and up.
  1074.  
  1075. SETHEADING *     - syntax: SETHEADING n
  1076.         - Changes the turtle's heading to n degrees.
  1077.  
  1078. SETXY *        - syntax: SETXY x,y
  1079.         - Sets the x,y location for the next graphics command
  1080.           in the current output window or open screen.
  1081.         - It's primary use is for turtle graphics. To
  1082.           avoid the "turtle" drawing a line when SETXY is used,
  1083.           the PENUP command should first be issued.
  1084.  
  1085. SGN        - syntax: SGN(n)
  1086.         - Returns the sign of the number n:
  1087.  
  1088.             if n>0, SGN(n) returns  1
  1089.             if n=0, SGN(n) returns  0
  1090.             if n<0, SGN(n) returns -1
  1091.  
  1092. SHARED        - syntax: SHARED <ident>[,<ident> ... ]
  1093.         - Variables, arrays and structures must explicitly
  1094.           be shared between the main program and subprograms.
  1095.           Only EXTERNAL variables are exempt from such sharing in
  1096.           ACE since they are global (see "Identifiers" in ace.doc).
  1097.         - One or more SHARED statements can appear in a subprogram
  1098.           and are usually placed before all other code in that SUB.
  1099.         - Declarations of objects to be shared must appear in the 
  1100.           main program before the subprogram is *declared*.
  1101.         - See subprograms section in ace.doc and the entry for
  1102.           DIM above re: DIM SHARED.
  1103.  
  1104. SHL *        - syntax: SHL(n,m) 
  1105.           where n is the value to be shifted and m is the number 
  1106.           of bit positions to shift.        
  1107.         - Arithmetic shift left function. Returns a long integer. 
  1108.         - Shifting left by 1 bit is faster than multiplying by 2
  1109.           or powers thereof.  
  1110.  
  1111. SHR *        - syntax: SHR(n,m) 
  1112.           where n is the value to be shifted and m is the number 
  1113.           of bit positions to shift. 
  1114.         - Arithmetic shift right function. Returns long integer.
  1115.         - Shifting right by 1 bit is faster than dividing by 2
  1116.           or powers thereof.  
  1117.  
  1118. SHORTINT *    - syntax: SHORTINT <identifier>[,..]
  1119.         - Declares and initialises one or more short integer 
  1120.           variables.
  1121.  
  1122. SINGLE *    - syntax: SINGLE <identifier>[,..]
  1123.         - Declares and initialises one or more single precision 
  1124.           variables.
  1125.  
  1126. SIZEOF *    - syntax: 
  1127.           SIZEOF(byte|shortint|longint|address|single|string|<ident>)
  1128.           where <ident> is the name of a variable, array, structure
  1129.           type or structure variable (not a SUB, function or external
  1130.           variable).
  1131.         - A size in bytes is returned.
  1132.         - The intention is the same as that of C's sizeof() operator.
  1133.         - SIZEOF is useful for allocating memory for structures.
  1134.  
  1135. SIN        - syntax: SIN(n)
  1136.         - Returns the sine of n.
  1137.  
  1138. SLEEP        - syntax: SLEEP
  1139.         - This command puts a program to sleep until there is 
  1140.           mouse, keyboard or timer activity.
  1141.         - The current version of SLEEP is somewhat limited in 
  1142.           that it only works in screen mode.
  1143.  
  1144. SOUND        - syntax: SOUND period,duration[,volume][,voice]
  1145.         - Note that the syntax of this command is different
  1146.           from the equivalent statement in AmigaBASIC.
  1147.         - See the sound section in ace.doc for details.
  1148.         - See also the WAVE command. A combination of
  1149.           these two commands in ACE allows you to easily
  1150.           play sound samples (see example program play.b).
  1151.         - SOUND currently uses the audio hardware directly
  1152.           but a future revision may use the audio device.
  1153.  
  1154. SPACE$        - syntax: SPACE$(n)
  1155.         - Returns a string of n spaces.
  1156.  
  1157. SQR        - syntax: SQR(n)
  1158.         - Returns the square root of n.
  1159.         - The argument n must be >= 0.
  1160.  
  1161. STICK        - syntax: STICK(n)
  1162.         - Returns information about joystick direction.
  1163.         - At the moment, STICK(0) & STICK(1) always return 0,
  1164.           while STICK(2) & STICK(3) return the state of
  1165.           the joystick in port 2 (B), where:
  1166.  
  1167.             STICK(2) is joystick B in X direction.
  1168.             STICK(3) is joystick B in Y direction.
  1169.         
  1170.         - Return values are:
  1171.  
  1172.              0 = joystick is not engaged.
  1173.              1 = movement is upward or to the right.
  1174.             -1 = movement is downward or to the left.
  1175.         - STICK currently goes straight to the hardware. A future
  1176.           revision may use the gameport device.    
  1177.  
  1178. STOP        - This is functionally equivalent to END in ACE.
  1179.  
  1180. STR$        - syntax: STR$(n)
  1181.         - Returns the string representation of the numeric value n.
  1182.          - The string includes a leading space or "-" depending upon
  1183.           the sign of the number.
  1184.  
  1185. STRIG        - syntax: STRIG(n)
  1186.         - Returns information about the state of a joystick button.
  1187.         - At the moment, STRIG(0), STRIG(1) & STRIG(2) always
  1188.           return 0. 
  1189.         - STRIG(3) returns -1 if the port 2 joystick's
  1190.           fire button is *currently* pressed and 0 if it isn't.
  1191.         - STRIG currently goes straight to the hardware. A future
  1192.           revision may use the gameport device.    
  1193.  
  1194. STRING *    - syntax: STRING <ident> [[ADDRESS <addr>] | [SIZE <size>]][,..]
  1195.         - Declares and initialises one or more string variables
  1196.           with an optional size or address. If the size is not 
  1197.           specified, a length of MAXSTRINGLEN bytes is assumed.
  1198.         - If an address is specified, the SIZE option can't be used
  1199.           since the size of the area of memory pointed to by <addr>
  1200.           has already been determined.
  1201.  
  1202. STRING$        - syntax: STRING$(I,J) or STRING(I,X$).
  1203.         - STRING$ returns a string of length I consisting of characters
  1204.           with ASCII code J or ASC(MID$(X$,1,1)).
  1205.  
  1206. STRUCT *    - Defines a new structure data type, thus:
  1207.  
  1208.           STRUCT <ident>
  1209.             <type> <ident1>
  1210.             <type> <ident2>
  1211.             .
  1212.             .
  1213.             <type> <identN>
  1214.           END STRUCT
  1215.  
  1216.           where <type> can be BYTE,SHORTINT,LONGINT,ADDRESS,SINGLE,
  1217.           STRING and <ident1>..<identN> are structure members of one
  1218.           of these data types.
  1219.         - See also: DECLARE and the section on structures in ace.doc.
  1220.         - Structures have been provided in ACE primarily to make
  1221.           communicating with the operating system a little nicer
  1222.           and to make dynamic data structures possible (see bst.b).
  1223.         - ACE structures cannot currently be array elements although
  1224.           there is nothing to stop you from storing structure start
  1225.           addresses in array elements.
  1226.         - See "Structures" section in ace.doc for more details.
  1227.             
  1228. SUB..END SUB    - syntax: SUB [<type>] <ident> [([<type>] <param> [..])]
  1229.                      <statement1>
  1230.                     <statement2>
  1231.                     .
  1232.                     .
  1233.                     <statementN>    
  1234.                 END SUB
  1235.           where the optional <type> is one of: LONGINT,ADDRESS,
  1236.           SHORTINT,SINGLE or STRING.    
  1237.         - In ACE, subprograms are non-static, allow recursion, have
  1238.           return values and have optional parameter lists.
  1239.         - Parameters are call-by-value but ACE does provide mechanisms
  1240.           for call-by-reference parameters.
  1241.         - SHARED variables are supported in ACE (see SHARED command).  
  1242.         - See "Subprograms" section in ace.doc for more details.
  1243.  
  1244. SWAP        - syntax: SWAP <object>,<object>
  1245.           where <object> is a simple/external variable, parameter,
  1246.           array element, structure or structure member.
  1247.         - This command swaps the value of the specified data objects.
  1248.         - SWAP is not intended to be used for exchanging two whole 
  1249.           arrays.
  1250.         - ACE currently assumes a maximum length of MAXSTRINGLEN
  1251.           when swapping strings.
  1252.  
  1253. SYSTEM        - syntax: SYSTEM n
  1254.           where n is an integer exit value or return code.
  1255.         - SYSTEM causes an ACE program to exit with the specified
  1256.           return code. The latter can be tested in a shell script
  1257.           as WARN, ERROR etc. This value is not returned if a program
  1258.           is Workbench-launched. 
  1259.         - Note that in AmigaBASIC SYSTEM returns from the interpreter
  1260.           to the shell/CLI or Workbench. The same is true in ACE, 
  1261.           except that END and STOP will also do this, so SYSTEM's
  1262.           purpose in ACE is different to that in AmigaBASIC.
  1263.  
  1264. TAB        - syntax: TAB(n)
  1265.         - Used in conjunction with PRINT to move the print position
  1266.           to the nth column.
  1267.         - TAB(n) - where n=1..81. 
  1268.         - if n>81, wraparound will occur.
  1269.         - if n<1, the next print position will be column 1 (leftmost).  
  1270.  
  1271. TAN        - syntax: TAN(n)
  1272.         - Returns the tangent of n.
  1273.  
  1274. TIME$        - syntax: TIME$
  1275.         - Returns the current time as a string of the format:
  1276.  
  1277.             hh:mm:ss
  1278.  
  1279.           where hh is hours, mm is minutes and ss is seconds.
  1280.  
  1281. TIMER        - syntax: TIMER
  1282.         - Returns a *single-precision* value corresponding to 
  1283.           seconds elapsed since midnight.
  1284.           or
  1285.         - syntax: TIMER(n) [ON|OFF|STOP], where n is seconds. 
  1286.         - see Event trapping section in ace.doc.
  1287.  
  1288. TRANSLATE$    - syntax: TRANSLATE$(<string-expression>)
  1289.         - Returns the phoneme-string equivalent of <string-expression> 
  1290.           where the latter contains words.
  1291.  
  1292. TURN *        - syntax: TURN n
  1293.         - Rotates the turtle by n degrees.
  1294.         - If n is negative, the turtle will rotate counter-clockwise
  1295.           while if it is positive, the rotation will be clockwise.
  1296.  
  1297. TURNLEFT *    - syntax: TURNLEFT n
  1298.         - Rotates the turtle counter-clockwise by n degrees.
  1299.         - If n is negative, the result will be the same as
  1300.           TURNRIGHT ABS(n).    
  1301.     
  1302. TURNRIGHT *    - syntax: TURNRIGHT n
  1303.         - Rotates the turtle clockwise by n degrees.
  1304.         - If n is negative, the result will be the same as
  1305.           TURNLEFT ABS(n).    
  1306.  
  1307. UCASE$        - syntax: UCASE$(<string-expression>)
  1308.         - Returns a string with all alphabetic characters in
  1309.           upper case. 
  1310.  
  1311. VAL        - syntax: VAL(X$)
  1312.         - Returns the numeric value of X$ as a single-precision
  1313.           number.
  1314.         - The translation of integers and fixed-point and exponential
  1315.           format real constants is supported.
  1316.         - The hexadecimal and octal prefixes (&H and &O) are recognised
  1317.           by VAL.
  1318.          - There may be a loss of accuracy if the string contains a 
  1319.           LARGE long integer value, due to the limitations of the 
  1320.           single-precision numeric format. To overcome this, use 
  1321.           the LONGVAL& function in the include file longval.h, thus:
  1322.  
  1323.             #include <longval.h>
  1324.             X$="123456789"
  1325.              X& = longval&(X$)
  1326.  
  1327. VARPTR        - syntax: VARPTR(<data-object>)
  1328.         - Returns the absolute address of a numeric variable, 
  1329.           string, array, array element, structure or structure 
  1330.           member.
  1331.         - You can safely use VARPTR to find a string variable's 
  1332.           address (SADD has also been provided for string variables
  1333.           and expressions).
  1334.         - Unlike AmigaBASIC, an object's address does *not* move 
  1335.           around in memory once allocated.
  1336.         - In ACE, the symbol "@" can be used instead of VARPTR, 
  1337.           eg: addr& = @n(2)  '..finds address of an array element 
  1338.         - When used in conjunction with a structure variable x, 
  1339.           @x will return the address of the variable itself, NOT 
  1340.           the start address of the structure (see "Structures" in
  1341.           ace.doc for more).
  1342.         - See also section on indirection operators in ace.doc.
  1343.  
  1344. WAVE        - syntax: WAVE voice,SIN | [waveform-address,byte-count]
  1345.         - Defines a waveform of any length to be used by the SOUND 
  1346.           statement for a specified audio channel (voice: 0..3).
  1347.         - If the SIN option is used, a sine waveform table is 
  1348.           allocated to the specified channel. This is the default
  1349.           waveform for the SOUND statement.
  1350.         - Unlike AmigaBASIC, the number of bytes in the waveform 
  1351.           table must be specified.
  1352.         - See the Sound section in ace.doc.
  1353.         
  1354. WHILE..WEND    - syntax: WHILE <condition>
  1355.               .
  1356.               .
  1357.               WEND
  1358.  
  1359.           where <condition> is an expression which reduces
  1360.           to a boolean (true/false) value.
  1361.  
  1362.         - Statements inside the WHILE and WEND are executed
  1363.           while the <condition> is true (ie: non-zero).    
  1364.     
  1365. WINDOW        - The ACE syntax for the window statement is:
  1366.  
  1367.               WINDOW n,[title-string],(x1,y1)-(x2,y2)
  1368.  
  1369.         - WINDOW OUTPUT n and WINDOW CLOSE n are the same
  1370.           as in AmigaBASIC. 
  1371.         - The window function syntax is still WINDOW(n) in ACE.
  1372.  
  1373.           WINDOW(0)  - same as window(1)
  1374.           WINDOW(1)  - window-id of current output window.
  1375.           WINDOW(2)  - present width of current output window.
  1376.           WINDOW(3)  - present height of current output window.
  1377.           WINDOW(4)  - x-coordinate in current output window where 
  1378.                    next pixel will be plotted.
  1379.           WINDOW(5)  - y-coordinate in current output window where 
  1380.                    next pixel will be plotted.
  1381.             WINDOW(6)  - max legal colour-id for current output window.
  1382.           WINDOW(7)  - pointer to Intuition Window for current output 
  1383.                    window.
  1384.           WINDOW(8)  - pointer to Rastport of current output window.
  1385.           WINDOW(9)  - pointer to AmigaDOS file handle for current 
  1386.                    output window.
  1387.           WINDOW(10) - foreground pen in current output window.
  1388.           WINDOW(11) - background pen in current output window.
  1389.  
  1390.         - See the section on ACE windows in ace.doc for more details.  
  1391.  
  1392. WRITE        - syntax: WRITE #filenumber,expression-list
  1393.           where filenumber corresponds to an open file.
  1394.         - The expression-list can contain any combination of
  1395.           data items (constants, variables) of any type
  1396.           separated by commas.
  1397.         - Note that the form of WRITE allowing for screen
  1398.           output is not currently supported by ACE.
  1399.         - See PRINT# re: the treatment of CHR$(0) in file I/O by ACE. 
  1400.         - See also INPUT# and the section on files in ace.doc. 
  1401.  
  1402. XCOR *        - Returns the turtle's current x-coordinate.
  1403.  
  1404. YCOR *        - Returns the turtle's current y-coordinate.
  1405.  
  1406. XOR        - Boolean operator: X XOR Y.
  1407.  
  1408.             X Y    Out
  1409.             -----------
  1410.             T T    F
  1411.             T F    T
  1412.             F T    T
  1413.             F F    F
  1414.