ACE v2.3 Programmer's Guide

 
	STRUCT mySecondStruct
	  STRING myArray SIZE 100       '..reserve space for the array
	  .
	  .
	END STRUCT
	
	DECLARE STRUCT mySecondStruct aStruct
 
	DIM N%(100) ADDRESS @aStruct->myArray

 
	DIM a_short_array%(49)
	PRINT SIZEOF(a_short_array%)

Note that in the case of the array and structure members above, it is necessary to take the address of the member and assign it to a normal array or structure (pointer to structure - see below) variable.

When declaring a structure, the only difference between the following two forms:

 
		DECLARE STRUCT mystructtype mystruct
	and
		DECLARE STRUCT mystructtype *mystruct

In both cases, mystruct contains the start address of a structure of type mystructtype. In the second case, the address is NULL until assigned a value (eg: with ALLOC). In both cases, the address can be reassigned at will, although this should only really be done for structure pointers (the second form).

Since both forms of structure declaration result in an address being stored (in mystruct in the example), the dereferencing operator is always "->".

Examples:

 
	PRINT mystruct       -  prints the start address of the structure.
 
	PRINT mystruct->mins -  prints the value of a member called mins.

ACE structures are stand-alone data objects, and cannot be elements in an array, although structure *addresses* _can_ be. For an example of the latter, see prgs/misc/array_of_structs.b.

An ACE structure can be SHARED to allow its member's values to be modified, or a structure's address can be passed to a subprogram, eg:

 
	struct my
	  longint one
	  longint two
	end struct
	
	sub test(addr&)
	declare struct my *second
	  second=addr&
	  second->one = second->one * 2
	end sub
 
	'..main
	declare struct my first
	first->one=12
	print first->one
	test(first)
	print first->one

The following code allocates enough memory to hold a structure of type "my", gives values to the structure's 2 members, and changes the address held by the structure variable "third" to the start of the newly allocated memory area:

 
	declare struct my *third
 
	sub create(ADDRESS a_struct)
	declare struct my *temp
	  temp = ALLOC(sizeof(my))
	  temp->one = 16
	  temp->two = 10
	  *&a_struct := temp    '..change structure variable's value
	end sub
 
	'..main
	create(@third)
	.
	.

CONTENTS

Shared library function calls

Also, the library in question must either be in LIBS: or in ROM.

As of version 2.0, ACE and AmigaBASIC are otherwise pretty much the same. The ACE commands also retain their earlier syntax for backward compatibility and convenience.

The commands are as follows:

LIBRARY <libname>

• Where is the name of a shared library with or without quotes (eg: "graphics", "graphics.library", graphics).
• A ".library" or ".bmap" suffix is allowed but optional.
• The LIBRARY command opens the shared library and provides a copy of its base address for use internally by function calls.
• If a library can't be opened at run-time, the program will abort.

LIBRARY CLOSE [<libname>]

• Closes the specified shared library or all open libraries if no library name is given.
• Closing a library more than once will cause no harm.

Notes about standard libraries used by ACE:

• There are currently six standard libraries which are often opened by ACE routines during a program run. These are: dos, intuition, graphics, mathffp, mathtrans and translator libraries.
• If one of these six is opened by the LIBRARY command it will be opened at the start of the program *and* closed at the end. Any other library will be opened and closed at the points in the program specified by you.
• You don't actually have to close any of the six libraries mentioned above, but it won't hurt.
• Moreover, you never have to open or close the dos.library since ACE opens it for EVERY program.

DECLARE FUNCTION <funcname>[%&!#$][(param-list)] LIBRARY [<libname>]

• Where <funcname> is the case sensitive name of a function in a shared library.
• <funcname> may have a trailing character (&%#!$) to indicate type, otherwise default data type rules apply for the function's return value. This character is optional when CALLing the function.
• The optional parameter-list is for documentation purposes only and is otherwise ignored.
• If <libname> (same as for LIBRARY and LIBRARY CLOSE) is specified, ACE only looks in the bmap file for that library, otherwise ACE looks for the function in the bmap files for all open libraries and all the standard libraries known to the compiler. Needless to say that specifying <libname> results in faster bmap file entry lookups. This option is not given by AmigaBASIC however.
• Example: DECLARE FUNCTION SetSoftStyle LIBRARY

[CALL] <funcname>[(parameter-list)]

• Transfers control to the function , loading the appropriate registers before doing so, according to the information about that function in the library's bmap file.
• The return value of a function can be accessed by calling a function as part of an expression, eg: addr& = AllocMem(100,2).

** PLEASE NOTE ***

No type checking of parameters is performed, so expect weirdness if you pass values of the wrong type to a shared library function. ACE _does_ however now automatically promote all short integers to long integers by sign-extension.

When passing strings as parameters it is not necessary to add a CHR$(0) to the end of a string since ACE strings are already NULL terminated.

Either VARPTR or SADD can safely be used to find the address of a string variable or constant. Actually, the use of SADD or VARPTR for strings passed to library functions is optional, but it's probably a good idea to use one or the other all the time, for consistency's sake. These comments also apply to calling machine code routines and external functions.

It is up to YOU to open and close libraries correctly. ACE doesn't keep track of this, and will try to jump to a library function so long as it finds a reference to it in a bmap file even if the library hasn't been opened! As mentioned above, it is not necessary to open and close dos.library because _every_ ACE program does this.

ACE expects the bmap file for a library to be in the directory ACEbmaps: (see "Installation").

Given Commodore's liquidation this year and the resultant confusion over who's now in charge of all this kind of stuff, I have no idea when or if the .bmaps will be provided with the ACE archive. However, this doesn't really matter so long as you have the .FD files. Read on...

As of version 2.0, I have provided a program (FD2BMAP) which is functionally equivalent to ConvertFD (since this may NOT be freely redistributed) so that bmap files for new libraries can be created. The program FD2BMAP can be found in the ACE:utils/fd2bmap directory and was written in ACE by Harald Schneider, with some modifications from me.

The 1.3 FD files can be found in the BasicDemos drawer on the Extras disk.

The FD files for Release 2.x/3.x are available from Commodore (who?) for about $30 (you get six disks of developer goodies: ask for the Native Developer Kit).

The FD files can also be found on Fred Fish's CD-ROMs and on the InterNet FTP site: ftp.rz.uni-wuerzburg.de in /pub/amiga/frozenfish/bbs/cbm. Note that FDs obtained from these sources are not freely redistributable and must be obtained on an individual basis, presumably to prevent modification when being passed through many hands.

AmigaBASIC cannot handle functions which use address register a5. This is not true for ACE. Neither ACE nor AmigaBASIC allow the use of functions which use register a6 however.

See the programs in prgs/Library for examples of how to use shared library functions in ACE.

CONTENTS

Machine code calls

The syntax for calling such a routine is:

 
	CALL long-integer-variable-name[(parameter-list)]

For example,

 
	CALL caps&(length&,addr&)

        
	8(sp) = addr&
	4(sp) = length&
	0(sp) = return address

On exit from a routine, ACE cleans up the stack by POPping all parameters.

You can use a short integer array, a string or an allocated area of memory (eg. with ACE's ALLOC function) to poke the bytes of a machine code routine into. I prefer the latter method.

Note that because ACE treats ASCII 0 as the end-of-string character, don't use the string-building method, eg:

 
	z$=""
	for i=1 to N
	  read b 
	  z$=z$+chr$(b)
	next

 
	z$=""   '..or STRING z$ SIZE 100 (if there are 100 bytes of MC).
	addr&=sadd(z$)
	for i&=0 to N-1
	  read b%
	  poke addr&+i&,b%
	next
	call addr&

 
	addr&=Alloc(100)        '..100 bytes of ANY memory
	for i&=0 to N-1
	  read b%
	  poke addr&+i&,b%
	next
	CALL addr&

ACE also supports primitive inline assembly code inclusion. See ref.doc under ASSEM..END ASSEM for details.

CONTENTS

External references

When passing parameters, standard C parameter passing conventions are used. Although some C compilers seem to pass all parameters as 4 bytes per parameter on the stack, ACE allows 2 (short words) or 4 byte parameters. Be aware of this! See prgs/ExternFunc for examples.

External variables can be assigned values like normal variables, eg:

 
		external RangeSeed&
		RangeSeed=5276&

 
		external longint RangeSeed

Note however that externally referenced string variables are assumed to be arrays of characters ala C, eg.

 
		char my_buffer[80];
or
		char my_string[] = "Hello World!"

 
		char *a_char_pointer = "Hello World!"

All external reference identifiers have an underscore prefixed by ACE but this is optional when declaring or using an external reference. C compilers always seem to prefix referenceable symbols with an underscore, so ACE does too.

Note that the names of external references (all except external SUBs - see below) *are* case sensitive.

Also, the bas script can take as a third argument the name of the object file produced from the original C or assembly source (ie: .o or .lib file) which contains the external function or variable to be linked with your ACE program. AIDE has facilities which allow for the linking of multiple object modules.

You can't easily call ACE SUBs from C or assembler because ACE SUBs don't use C parameter passing conventions and ACE code relies heavily upon linking code from run-time libraries (db.lib and startup.lib).

CONTENTS

Creating & using ACE subprogram modules

 
	SUB lines(n) EXTERNAL
	  FOR i=1 to n
	    LINE (RND*640,RND*200)-(RND*640,RND*200)
	  NEXT
	END SUB

 
	'..main
	DECLARE SUB lines(n) EXTERNAL
	LIBRARY "graphics.library"
	WINDOW 1,,(0,0)-(640,200)
	lines(500)
	WINDOW CLOSE 1
	END

  
	ace -Om lines           { The -m switch is the key here }
	a68k lines.s
	bas -O main lines.o

 
	module lines

There are a few things to be kept in mind when using ACE modules:

1. Only subprograms - not subroutines (ie. via GOTO/GOSUB) - in such modules can be called from other modules.
2. The main module *MUST* open all standard libraries required by the other ACE modules linked to it. If in doubt add the following lines of code at the top of your main program:

    
   			LIBRARY mathffp
   			LIBRARY mathtrans
   			LIBRARY graphics
   			LIBRARY intuition
   			LIBRARY translator      '..only if TRANSLATE$ used
   

   If your code works as a single-module program but you invoke the GURU or your program just doesn't work anymore when part of it is placed into a linkable module, the above should fix it.
3. The "m" switch creates an assembly source module containing bare code with no calls to the startup functions normally invoked by an ACE program. Because of this, you need to keep the following in mind:
   • Command-line arguments must either be handled in the main program module or ARGCOUNT or ARG$ must be used one or more times in the main module if they are going to be used in a module produced with ACE's "m" switch. A line of code in the main module such as:

      
     		n = ARGCOUNT
     

     will suffice.
   • Likewise, if ALLOC is used in a module, it must also be used at least once in the main program (eg. x=ALLOC(0) - no bytes will be allocated).

• In order to use DATA/READ within a module, make sure you issue a RESTORE command (in a subprogram) before the _first_ READ is executed. This RESTORE command *must* be in a subprogram. For example, in the calling module:

   
  		library mathffp
  		declare sub data_test external
  		data_test
  

  and in the library module:

   
  		sub data_test external
  		  restore
  		  read x
  		  print x
  		  data 1.345    '..DATA lines _can_ be outside of SUBs
  		end sub
  

• ON TIMER normally has special startup code associated with it. Since there _is_ no startup code in modules, you will have to include the following lines of code such that they will be executed before the ON TIMER code:

   
  		external function ontimerstart
  		ontimerstart
  

  For example, in the calling module:

   
  		library mathffp
  		declare sub timer_test external
  		timer_test
  

  and in the library module:

   
  		sub timer_test external
  		SHORTINT count
  		  external function ontimerstart    '..can be outside SUB
  		  ontimerstart
  		  on timer(1) gosub do_beep
  		  timer on
  		  while -1
  		    if count=5 then exit sub
  		  wend  
  		  do_beep:
  		    ++count
  		    beep
  		    return
  		end sub
  

 
	SUB even(n) EXTERNAL 
	  m = n MOD 2
	  IF m=0 THEN
	    even = -1
	  ELSE
	    even = 0
	  END IF 
	END SUB

 
	SUB even(n) EXTERNAL
	  m = n MOD 2
	  IF m=0 THEN
	    even = -1
	  ELSE
	    even = 0
	  END IF 
	    PRINT n;"mod 2 is"m        ' trashes d0!!
	END SUB

Note that the d0 convention ONLY applies when the "m" compiler switch is used and that it applies to all subprograms in a module. However, even if a SUB is declared to be external, the d0 parameter passing convention will not be used unless either: (i) the "m" switch is used for the module in which the SUB is defined, or (ii) a SUB is used after being externally referenced via DECLARE SUB ... EXTERNAL.

Instead of an external SUB, it is legal to have an external DEF FN. The forward declaration is still the same as for a SUB. The definition for the "even" function (in a module) looks like this:

 
	DEF even(n) EXTERNAL = -(n MOD 2)

Finally, be careful to match up the return and parameter types for an externally defined subprogram and its forward (external) declaration.

CONTENTS

Windows

All user-defined windows are now (as of ACE v2.0) Intuition windows with each characteristic being configurable via the "type" parameter as per AmigaBASIC (see ref.doc).

Windows can be opened on the Workbench screen or on a user-defined screen.

The zeroth window (the shell/CLI, if the program was CLI launched) is now the only instance of a DOS console window in ACE.

The WINDOW function takes a single parameter and returns information about the current output window. See ref.doc for details.

Note that for user-defined windows, close-gadget clicks must be handled by the use of ON WINDOW event trapping or via the "w" compiler switch (or the OPTION w+ command).

Please read the next section for more information about how windows relate to screens in ACE.

CONTENTS

Screens

By default, when a screen is opened, a (BORDERLESS+BACKDROP) window the same size as the screen is also opened. Subsequent output is directed to and input received from this window until the screen is closed (unless other windows are defined for the screen). Note that this feature is not found in AmigaBASIC. Note also that this default window is *not* counted as having a window-id of 0. That privilege is reserved for the shell window if the program was shell-launched. Read on...

The main use for such a default window is to provide a simple graphics output "slate" for quick-and-dirty programs. The borderless+backdrop characteristic prevents user-defined windows which may later be opened onto the screen from accidentally being depth arranged behind an invisible window where they would stay for the remainder of that screen's life. With a backdrop window this cannot happen since it will _always_ be the rear-most window for a screen.

Text and graphics positions will be different on a screen's default window than for user-defined windows. For example, text in the first row will be partially off the top of the screen, so LOCATE may need to be used to adjust this. In short, I recommend that default windows now ONLY be used for rough output. If you still want a borderless window, use the WINDOW command and ensure that the window-type has 32 as a component.

Avoid mixing the use of default and user-defined windows. Except for the simple case in which you use nothing but screens and their default windows you should consider your own windows to be the primary output destination for graphics and text.

Windows with depth gadgets cannot be sent behind the default window, but one screen can be sent to the back of other screens. It can also be moved vertically (and possibly horizontally). SCREEN BACK|FORWARD can be used to shuffle screens under program control.

When a screen is closed, ACE makes the screen with the next highest id the current one, so it is advisable to open and close screens in ascending and descending order.

A special SCREEN function exists in ACE which returns pointers to various Intuition structures (window,screen,rastport,viewport,bitmap) and x,y font sizes. This is detailed in the command and function reference (ref.doc) as are the following commands: SCREEN, SCREEN CLOSE, PALETTE and PRINTS. The latter is now redundant since all commands and functions can - as of ACE v2.0 - be used transparently for screens, user-defined windows and the shell/CLI.

CONTENTS

Gadgets

Since one of my aims is to support all Amigas running everything from Wb 1.3 to Wb 3.0, I have chosen to stick with simple Intuition gadgets for now.

Even so, ACE now supports the 3D bevel-box look of GadTools gadgets found under Wb 2.x/3.0. Moreover, a BEVELBOX command allows the programmer to create such boxes at will.

A future revision may support other gadget types, such as radio buttons, check boxes, list boxes etc.

Memory permitting, up to 255 gadgets can be created during a single program run.

The GADGET command creates a gadget with specific features while GADGET CLOSE removes the gadget from the window. Once created, a gadget can be enabled or disabled, indeed it can be disabled upon creation if so desired. The GADGET MOD command modifies the state of a slider (knob size and position).

Having created a gadget or gadgets, you must then decide how to receive and handle information from them. ACE provides four methods: standard event trapping (ON GADGET), polling (via the GADGET function), WAITing for a specific gadget or WAITing for any gadget.

Where it is possible to make your programs modal (ie. focussed upon a single event or event type) you can use the GADGET WAIT command.

The following commands set up a window with two boolean gadgets and a close gadget. The latter is set up by Intuition with the WINDOW command.

The program traps WINDOW and GADGET events. The comments should help you to understand the code.

 
CONST having_fun = -1&
 
WINDOW 1,"Gadgets",(0,0)-(640,200),8
 
GADGET 1,ON,"Hit Me",(3,3)-(75,20),BUTTON,1
GADGET 2,OFF,"Quit",(100,150)-(200,175),BUTTON,2
 
ON GADGET GOSUB gadget_handler
GADGET ON
 
ON WINDOW GOTO quit
WINDOW ON
 
'..main loop (actually does nothing, but is necessary for event trapping)
WHILE having_fun
  '..have a nap while nothing's happening  
  '..(don't hog the machine by busy waiting) 
  SLEEP         
WEND
 
gadget_handler:
  '..find out which gadget was selected
  gad = GADGET(1)
  LOCATE 12,40:PRINT "<<"gad;">>" 
  if gad = 2 then quit    
RETURN
 
quit:
  GADGET CLOSE 2
  GADGET CLOSE 1
 
  WINDOW CLOSE 1
END

.
.
'..await a gadget selection
REPEAT
  WHILE NOT GADGET(0)
    SLEEP  '..be a little nice to other tasks
  WEND
  
  '..which one?
  gad = GADGET(1)
  LOCATE 12,40
  PRINT "<<"gad;">>" 
UNTIL gad=2
.
.

 
.
.
GADGET WAIT 2     '.."GADGET WAIT 0" waits for ANY gadget! -> BEST method!
.
.

For boolean gadgets you can - if you need to - get information about the width and height of the gadget's text font by calling SCREEN(5) and SCREEN(6). If you need more precise width information, use the graphics library TextLength or TextExtent (v36) function.

String and LongInt gadgets now have associated with them a 1K buffer.

For more details about the GADGET commands and function, see ref.doc.

CONTENTS

Menus

 
	MENU 1,5,1,"Quit","Q"

Note that although ACE adjusts menu text for font size and type as set via preferences, some fonts may require you to pad your menu title/item names with blanks when using command keys to avoid overlaps, so it is a good idea to add a couple of spaces to the end of a menu item string.

For an example of menu programming with ACE see prgs/ifs.b. For a better example, see the source code for AIDE. Over time I will modify some of the other example programs in the archive so that they are menu-driven.

Note that in ACE, MENU CLEAR replaces MENU RESET.

See ref.doc for more details about the MENU commands and function.

CONTENTS

Requesters

• System requester
• File requester
• Input requesters (STRING and LONGINT)

If you are running Wb 2.x and above, ACE generates an ASL file requester.

For Wb 1.3 an ARP file requester is invoked for two simple reasons:

• It is quite acceptable.
• The arp.library is common on Wb 1.3 systems.

CONTENTS

Turtle Graphics

• what the heck is Turtle Graphics?
• isn't that for kids?
• why did he include THAT?

LOGO also has many Lisp-like qualities and so can be used as a language for AI work, although to my knowledge, it's not.

But I digress. Apart from the fun kids can have with TG, it's actually possible to construct quite complex shapes with it. Combined with recursion, TG is a powerful tool. It is particularly useful in plotting many fractal shapes (see snowflake.b, dragon.b).

Since the first LOGO, there have been many manifestations of TG. Turbo Pascal for the PC and the Mac have both had TG.

A few years ago, I wrote a pure TG subset of LOGO which used the same syntax as the original language and allowed recursive procedures. I've also written TG functions in C. Both of these have been useful to me and I've often wished that BASIC came with TG built-in. Well, now one dialect does!

For some examples of the use of Turtle Graphics in ACE, see the following programs:

• tree.b
• flower.b
• boxit.b
• torus.b
• dragon.b
• snowflake.b
• bst.b

Okay, enough philosophy. Here's the ACE stuff:

 
BACK n          - move turtle back by n.
FORWARD n       - move turtle forward by n.
HEADING         - return turtle's current heading in degrees (0..359).
HOME            - move turtle back to its home position.
PENDOWN         - put turtle's pen down. 
PENUP           - lift turtle's pen up.
SETHEADING degs - change turtle's heading to degs.
SETXY x,y       - change turtle's current x,y location.
TURN degs       - rotate turtle by degs.
TURNLEFT degs   - turn turtle left by degs.
TURNRIGHT degs  - turn turtle right by degs.
XCOR            - return turtle's current x-coordinate.
YCOR            - return turtle's current y-coordinate.

• n is pixels
• degs is a signed short integer representing degrees with the turtle starting at a 270 degree orientation -- pointing up.
• home is the turtle's x,y start location (0,0).

 
	EXTERNAL SINGLE tg_xy_ratio
	tg_xy_ratio = 1.125     

 
	Screen mode                     Aspect ratio    
	-----------                     ------------
	Lo-res, non-interlaced          0.9375
	Hi-res, non-interlaced          1.875
	Lo-res, interlaced              0.46875
	Hi-res, interlaced              0.9375
	Hold and Modify (HAM)           0.9375
	Extra-Halfbrite                 0.9375

If a negative value is specified for the turnleft or turnright commands, the turtle will be rotated in the opposite direction to that indicated by the the command name. Note that there is also a TURN command.

When using ACE's TG system, it's best to think of an imaginary turtle (in LOGO it's usually a small triangle on the screen) which rotates and moves according to your whim. The turtle can either have its pen lowered or raised - and will therefore draw or not - which is useful when you need to move in a relative fashion from one location to another without drawing anything.

SetXY is like the graphics library Move() command and may need to be preceded by PENUP unless you want to draw a line as the turtle finds its new position.

To change the colour of the drawing pen, use the COLOR command.

That's probably enough about Turtle Graphics. Oh by the way, if you want to know more about the origins and uses of Logo, read Papert's "Mindstorms" and his recent book entitled "The Children's Machine: Rethinking School in the Age of the Computer". They make for interesting reading.

While I think of it, Sherry Turkle wrote a book called "The Second Self: Computers and the human spirit", which I recommend if you're at all interested in the psychological/social effects of computing.

CONTENTS

Loading & displaying IFF pictures

The short example program prgs/gfx/iff.b demonstrates typical usage.

IFF READ uses the freeware ILBM.library but you don't need to have this since it will be created by ACE automatically at run-time if need be. If LIBS:ilbm.library is not found at run-time ACE will use the library's binary image - which is stored in db.lib - to create ram:ILBMtmp/ilbm.library. This file and the directory ILBMtmp will be removed when the program exits. The idea of using a binary image like this was Roland Acton's.

See ref.doc for details of the IFF commands and function.

CONTENTS

Sound

See prgs/sound/sound.b for an example of how to use ACE's sound facilities in general.

How many times have you wished that AmigaBASIC would let you produce white noise easily like the good ol' C64 and Vic-20 did?

Well, you'll be pleased to know that ACE allows you to do this. All you have to do is allocate about 4000 or more bytes of Chip RAM (upwards of 4000 bytes yields better quality white noise), poke it with random values (between -128 and 127), call WAVE and you're set (see sound.b)!

Moreover, you can actually play sound samples (IFF or otherwise) in the same way, using just the two commands WAVE and SOUND (see prgs/sound/play.b).

As with AmigaBASIC, a sine waveform is the default, but through the WAVE statement you can create any waveform you wish including sawtooth, triangle, square and random (white noise).

WAVE has the following syntaxes:

 
	WAVE voice,SIN
and     
	WAVE voice,waveform-address,byte-count

The SOUND statement syntax is as follows:

 
	SOUND period,duration[,volume][,voice]

Sampling period is inversely proportional to frequency, so a high sampling rate corresponds to a low frequency and vice-versa. ACE allows you to specify a sampling period in the range 124..32767.

The duration is a single-precision value as in AmigaBASIC but can range from 0..999 (instead of 0..77). This range is somewhat arbitrary, but gives plenty of scope for large sound samples. This specifies the length of time that a tone should be played for. A duration of 18.2 corresponds to about 1 second.

Volume defaults to 64 if not specified and can range from 0..64.

The voice can be in the range 0..3 - since there are 4 audio channels - with 0 & 3 corresponding to the left speaker and 1 & 2 to the right. The default voice is 0.

At the moment, ACE's SOUND statement isn't very good when used to produce a series of short pulses, although this is somewhat dependent upon the waveform in use. In any case, more work needs to be done in this area to prevent "popping" between SOUND statements when the audio hardware is turned on and off in rapid sequence.

ACE sound is produced by programming the hardware directly. A future version will utilise the audio device instead. Indeed, the SOUND statement in ACE may change in the future to be more in line with AmigaBASIC (see also "Future Versions").

Finally, here's some useful equations for use in conjunction with ACE's SOUND statement:

 
	samples/second to period:
	------------------------
	period = 3579546 / samples-per-second
	
	musical note to period:
	----------------------
	period = 3579546 / (length * frequency)
 
	where length is the size of the waveform table in bytes 
	(32 bytes for ACE's sine waveform) and frequency is the
	note itself (eg: middle C is 523.25 Hz).
 
	duration value for one waveform cycle:
	-------------------------------------
	duration = .279365 * period * length / 1E6 * 18.2

Event trapping

 
	BREAK     -  user break: ctrl-c.
	MOUSE     -  left mouse button press.
	TIMER(n)  -  cause a trap every n seconds.
	ERROR     -  I/O and other errors.
	MENU      -  menu selection.
	WINDOW    -  window event: close-gadget click. 
	GADGET    -  user-defined gadget selection.

Even if your program expects to do nothing but trap events, you'll need a loop like this:

 
	WHILE -1
	  SLEEP   '..don't hog the CPU  [SLEEP is optional but nice] 
	WEND

The specification for the trapping of an event is:

 
	ON  GOSUB | GOTO | (eg: ON BREAK GOTO quit)

 
	 ON  (eg: BREAK ON)  

It is a good idea to put trap handlers at the end of a program, since once the handler for an event is found by the compiler, no more event trapping code is generated for that event even if there is code below the handing routine. In other words, the equivalent of an OFF (see below) command is issued once the trap handling code is found by the compiler.

Other commands are:

 
	 STOP

ON is issued, and:

 
	 OFF

which disables trapping for the event permanently.

Just so there is no misunderstanding, the latter two commands prevent the inclusion of event trapping code for a specific event in your program at the assembly source level. They do this from the point in an ACE program at which they are issued.

Here's a typical example:

 
	ON BREAK GOTO quit
	BREAK ON
 
	for i=1 to 1000000
	 print i
	next
 
	quit:
	  PRINT "**break!"
	  STOP

Simultaneous trapping of several different events is possible and in general works very well. The use of INKEY$ and ON BREAK together when a user-defined window is the current output window leads to some competition. You may simply need to hit ctrl-c a few times in this circumstance for a user break to be accepted.

If you wish to trap only one kind of event you should consider the use of WAITing (only for menus and gadgets currently - see MENU/GADGET WAIT).

CONTENTS

---

Interprocess Communication

ACE provides a simple IPC mechanism centered around a set of MESSAGE commands (see ref.doc for full details).

ACEports represent a half-duplex, blocking/non-blocking, named IPC mechanism, similar to Berkeley Unix domain datagram sockets.

The mechanism is based upon Exec message ports and provides a simple way for concurrently running ACE programs to communicate across unique, safe channels. Strings can be sent as messages to a particular message port, the name of which must be known in advance.

Probably the best way to find out how the MESSAGE commands are used in ACE is to compile, run and study the programs in prgs/ACEports.

I consider this feature to be experimental and am interested in your feedback regarding it. The ACEports mechanism will probably be improved as time goes by.

ARexx capabilities are also planned for ACE at some stage.

CONTENTS

---

Error handling

The compiler messages generated by ACE are often different to the ones in the AmigaBASIC interpreter (and ACE doesn't beep at you with each error) but they are usually fairly clear.

Syntactically incorrect programs can lead ACE to produce a bunch of spurious error messages. In such cases, it's best to ignore all but the first one or two, unless there are "clusters" of messages which are separated by periods of error-free compilation.

If you leave out END IF, WEND, UNTIL, NEXT, END SUB, END STRUCT or END CASE, there will be a corresponding number of error messages at the end of the compile. If you leave off two WENDs, you'll get 2 "WHILE without WEND" error messages.

ACE generally reports the first error in a line of code and ignores the rest of the "bad" line. A typical message consists of the line containing the error, a carat ("^") marker, and the error message itself. More work still needs to be done on ACE's compile-time error handling, but it's bearable.

No error messages are issued by ACE programs at run-time. Generally, when a program runs into something it can't do, or an erroneous request - like trying to open two files to the same file number or trying to open a library that doesn't exist - the program will either quit or just not have the desired effect.

Note that while the ERR function and ON ERROR event trapping are supported, only file I/O, serial I/O, IFF, IPC (MESSAGE) and window/screen open errors are currently reported via these mechanisms.

CONTENTS

---

Notes for assembly programmers

I've tried to make the assembly source files that ACE produces as readable as possible by using meaningful data object names. See also "Compiler options" re: the compiler's "-c" switch.

Linked library routines use data registers d0-d6 and address registers a0-a3, while d7 is used for array index calculations. Also, a4 and a5 are used as stack frame pointers for variables and parameters.

Most db.lib routines don't save and restore registers via the stack, but the use of registers is internally consistent (ie: all registers are up for grabs but interdependent routines are written in such a way so as not to conflict). External function calls in ACE programs now _do_ save and restore registers.

The use of linked libraries means that the size of all executables is fairly large. But given that disk space and memory are cheap, I'd rather this than the alternative of having every executable be dependent upon one or more special shared libraries at run-time. However, I will try to reduce the size of executables. Some improvement has been made with the current revision. Kendall Sears has suggested the creation of smaller versions of db.lib and startup.lib for use with shell-based programs. I like this idea and will implement it when I have time.

Due to BASIC's tendency to coerce data types so much for the programmer, the resulting code can look a little nasty, and big increases in efficiency can be gained by careful combinations of data types in expressions.

Writing ACE has so far been a learning experience for me and if when I started I knew what I know now, I would have done many things differently.

My original rationale for passing parameters via registers to ACE (and shared) library functions was to improve execution speed. However, since I call lots of other functions (eg: in ami.lib) which require their parameters to be on the stack, I would probably call ALL functions in this way if I did it again.

Moreover, my desire for internal consistency led me to a rather odd method of passing parameters to SUBs. This allowed me to treat parameters in the same way as variables which is all very nice, but it led to other problems, chief among them being the need to use a Forbid()/Permit() pair when sending parameters to a SUB. This works fine however, so I'm taking the view that if it 'aint broke, I probably shouldn't fix it.

CONTENTS

---

Limitations

Undeclared variables do NOT get a default zero or NULL value, so don't assume ANYTHING about the contents of an uninitialised variable, eg.

 
	PRINT X 

will yield garbage if X has not been given a value. The optional variable declarations provided in ACE are therefore worth using since they DO give variables an initial zero or NULL value.

The precision of exponentiation begins to falter with large numbers (where the exponent is around 23 or higher) because all exponentiation is currently done with the single-precision math library function SPPow(). Use either long integer multiplication or ACE's SHL function for greater accuracy, where integers are applicable. For example, compare SHL(2,22) with INT(2^23). You may also find that integer exponentiation sometimes yields a non-integer result, eg.

 
	PRINT 2^3
gives:
	8.0000009

This is an artifact of single-precision exponentiation. I intend to make ACE take a more intelligent approach to integer exponentiation in a future revision (probably the next one).

If you are only interested in an integer result, apply CINT or CLNG, thus:

 
	PRINT CLNG(2^3)

to get:

	8 

See also the LONGINT(n) function for getting around the problem of extracting a large integer value from a string.

While strings can be defined to be longer (or shorter) than 1K, there are some ACE commands and functions which still assume a 1K limit, namely: STRING$, SPACE$, LINE INPUT#, INPUT and SWAP.

Strings and arrays which are local to a subprogram will be overwritten if the SUB has recursive calls to itself. The same applies to string parameters. In all these cases a single static data item is being referenced.

If you issue RETURN from within a FOR loop, the return address will *not* be the top item on the stack. Instead, FOR..NEXT loop data will be. A GURU will almost certainly result. It is probably better to use a while or repeat loop if you must RETURN from within a loop. See also EXIT FOR in ref.doc which allows for the safe, early termination of FOR loops.

A shared variable cannot be used as a FOR loop index in ACE. Any attempt to do so will result in a compile-time error.

IF..THEN NEXT will not have the desired effect (it's bad coding anyway). NEXT must always appear on a line by itself or as part of a multi-statement.

ACE does not consider "=>" to be the same symbol as ">=". In fact, ACE doesn't recognise the former at all. The same is true of "=<".

The compiler only responds to ctrl-c during the main compilation phase, and not during optimisation or when target code is being written.

Don't mix the compiler's "b" option with BREAK event trapping, as they will conflict.

CONTENTS

---

Known Bugs

The SAY(n) *function* works under release 2.x but not under 1.3. Since the function uses no 2.x-specific code, this is puzzling. The SAY command works under both 1.3 and 2.x however.

A68K sometimes complains about string literal definitions produced by ACE if they are much longer than a single line.

Some fonts cause the INPUTBOX[$] display (string gadget) to be corrupted. Stick to topaz for this where possible. A future revision may use a GadTools or BOOPSI requester (for 2.x/3.x machines).

CONTENTS

---

Future versions

Random files and double-precision floating-point math are high on the agenda.

More graphics (eg: GET,PUT) commands and functions are planned and I also intend to fix any remaining differences between ACE and AmigaBASIC in this area.

AGA screen modes are likely to be supported soon (especially since I recently purchased an A1200 :).

I may provide support for sprites at some stage.

Thus far, I've taken the approach of implementing what I most often use and what I have often wished for in BASIC.

In recent times I have been impressed by three things in the programming world: the rise of Object-Oriented Programming (OOP), Resources (as found on the Macintosh and MS-Windows) and Visual BASIC for Windows.

The idea of resources (pioneered by the Macintosh resource fork and ResEdit) is a powerful one and Microsoft and Borland have picked up on this in MS-Windows. I wish the Amiga had them as standard, but alas it doesn't.

I am trying to add more "visual" stuff to ACE, hence: gadgets, menus, requesters, AIDE. You can expect to see more "visualising" of ACE as time goes by, including a GUI designer for ACE programs. To make ACE like Visual BASIC would take a major rewrite, but I can at least try to take advantage of some of its features.

CONTENTS

---

A note to PD libraries and reviewers

First, to those magazines who have reviewed ACE so far, let me say a big THANK YOU. Good publicity is always appreciated as is acknowledgement of the time I've spent on ACE.

I'd appreciate it if you would check with me (if possible) to ensure you have the latest version of ACE before including it in your library or reviewing it for a magazine. If you don't have e-mail access, I don't expect you to do this (snail-mail is a pain isn't it!?).

Lastly, the wider ACE travels the happier I am, so I'm pleased to see ACE turning up in the odd PD library. Please note however that I don't wish people to profit financially from the distribution of ACE. You may charge a fee which covers the cost of the disk and the copying thereof, but no more.

CONTENTS

---

Disclaimer

Although every care has been taken in the development and testing of the compiler and its libraries, the author will not be held liable for damages caused either directly or indirectly as a result of the use of ACE.

CONTENTS

---

References

The following references have been used in developing ACE:

 
+----------------------------------------------------------------------------+
| "Amiga BASIC" (manual), 1985, Commodore-Amiga Inc. and Microsoft Inc.      |
|                                                                            |
| "Amiga ROM Kernel Reference Manual: Libraries", 1992, Commodore-Amiga      |
|                                                                            |
| "Amiga ROM Kernel Reference Manual: Devices", 1991, Commodore-Amiga        |
|                                                                            |
| Anderson & Thompson, 1990, "Mapping the Amiga", COMPUTE! Publications Inc. |
|                                                                            |
| Bleek, Jenrich & Schulz, 1989, "Amiga C for Advanced Programmers", Abacus  |
|                                                                            |
| Choi, 1990, "Advanced Programming Techniques", University of Tasmania      |
|                                                                            |
| Dittrich, 1989, "Amiga Machine Language", Abacus                           |
+----------------------------------------------------------------------------+

Despite its not infrequent errors, "Mapping the Amiga" remains an excellent resource. I have also often referenced "Advanced Amiga C programming".

Naturally, the two RKM volumes listed above and the "Amiga BASIC" manual are used regularly as well.

Although not listed, Commodore's Autodocs for the Amiga (supplied with the Native Developer Kit) are also constantly used.

Young Choi's Advanced Programming notes in many ways provided the impetus for the development of ACE. They were used in a compiler construction course I took as an undergraduate. I thank Young for introducing me to the joys of compiler writing, although I know he didn't intend me to spend *all* my time writing programming language translators of one kind or another. :-)

Including the Pascal Minus compiler I wrote for that course, and the PC BASIC interpreter I wrote during the same period, I've since written a version of Logo (turtle graphics subset), a Forth interpreter and ACE.

CONTENTS

---

Contacting the author

I am contactable via e-mail on: the Internet, Compuserve and Discovery 40/80. Of course, there is also the telephone and snail-mail.

 
+-----------------------------------------------+
|     Internet: D.Benn@appcomp.utas.edu.au      |
|                                               |
|   Compuserve: 100033,605                      |
|                                               |
| Discovery 40: 032432850                       |
|                                               |
|      Phone: (003) 317 680 [home]              |
|             (003) 243 529 [work]              |
|                                               |
|    Address: 181 St John Street, Launceston,   |                          
|             Tasmania, Australia, 7250         |
+-----------------------------------------------+

CONTENTS

---

ACE discussion list and FTP site

In February 1994 I was allowed to establish a listserver-based discussion list for ACE on one of the Unix boxes at my place of work, the University of Tasmania at Launceston's Department of Applied Computing and Mathematics.

The purpose of the list is to allow for the dissemination of information about ACE, the discussion of bugs, problems, solutions and ACE programming in general.

To subscribe to the list send (Internet) e-mail to:

 
	Listserver@appcomp.utas.edu.au

The subject-line of the message is unimportant, but the first line of the message must be of the following format:

 
	subscribe ace FirstName LastName

For example, in my case:

 
	subscribe ace David Benn

would do the trick. The listserver will send you a welcome message and information about how to participate in the list.

At about the same time as the ACE list was established, an anonymous FTP server was set up:

 
	ftp.appcomp.utas.edu.au

ACE-related files are stored in the directory:

 
	/pub/amiga/ACE

I'd like to thank Tony Gray (Technical Services Manager) and Christian McGee for maintaining the listserver and Young Choi (Head of Department) for allowing me to use the department's facilities for this purpose.

CONTENTS

---

Final word

Let me offer my thanks to Charlie Gibbs for his reliable assembler and to the Software Distillery for Blink. Without these excellent programs, far fewer compilers would have seen the light of day, including ACE.

Sozobon C (ZC) has always been a reliable workhorse for me, so a vote of thanks goes to Sozobon as well. Isn't freeware great?

I'd like to thank those people who have tested ACE so far. They are too numerous to mention here, but special thanks goes to Addison Laurent, Alan-Peyton Smith, Peter Zielinski, John Stiwinter and the members of the ACE discussion list (see above).

These guys have given ACE a good workout on a variety of platforms ranging from an A1000 running Wb 1.3 to 68030 machines running Wb 3.0.

I'd especially like to thank Michael Zielinski for discovering a particularly serious bug which prevented branches of greater than 32K in length prior to v1.02. Also, Enforcer hits reported by him started me on a trail which led to a nasty string-related bug (see entry for 13/4/93 in docs/history).

Jarto 'Robin' Tarp pointed out how inefficient my first implementation of INSTR was. It's considerably faster now (since v1.02).

Let me stress that any remaining bugs in ACE are entirely my fault.

Others have given me a great deal of encouragement and made useful comments throughout 1993 and 1994. I hope this continues. The sense of community on the virtual world of the Net is a refreshing change from the general weirdness of the "real" world.

I'd like to thank John Stiwinter for all his excellent work in putting together the AmigaGuide documents for ACE. Having ACE's reference material in this format has enhanced its utility enormously. He has also done other stuff in the background for which I am grateful.

Many of the subscribers to the ACE discussion list (see above section) have given me plenty to think about, plenty of bug reports and plenty of support. In particular, thanks goes to Kendall Sears for keeping me on my toes and for providing expert technical knowledge of the Amiga.

Jeff Harris, Chuck Kenney, Dan Oberlin, Sean Miller and Kenneth Brill have all contributed to ACE in their own ways. Thanks guys! Also, to all those who have e-mailed or written to me, thanks. You know who you are!

I'd also like to thank my wife Karen, for her encouragement and support, for putting up with the number of hours I spend at the computer, and just for tolerating me generally. :-) IFS is her favourite program so it's dedicated to her (try the "Green Fern").

Despite ACE's problems (see "Limitations" and "Known Bugs") it is proving to be a useful tool for me, and if others can derive benefit from it, well, that's great. ACE is gradually coming to support the features I and others want it to, but there's still plenty of work to do.

The provision of support for shared library functions, external functions, machine code routines, inline assembly code, include files and linkable SUB modules should go a long way towards making up for ACE's intrinsic shortcomings.

I hope you enjoy ACE and find it useful. I'm learning a great deal by developing it and having a lot of fun in the process. If you feel the need to send me some money, please go ahead, but I certainly don't expect it.

What I DO want is feedback. If you have any problems, requests, queries or suggestions, I want to hear from you and I'd like to hear about interesting programs you've written with ACE (send me the source code if you like). I'm always on the lookout for good example programs to include in the ACE archive.

Remember that ACE is FreeWare, so redirect flames to NIL: :^).

Happy programming!

Regards, David Benn
22nd October 1994

CONTENTS

---