!lm12
!rm75
A Review of AMPER-MAGIC....................Bob Sander-Cederlof

AMPER-MAGIC is a utility program which makes it easy to add machine language subroutines to Applesoft programs and thereby extend the capabilities of Applesoft BASIC.  It was written by Bob Nacon, one of our subscribers from New Jersey.  For $75, you get a 51-page reference manual; an administrative program; and a collection of 23 subroutines, to be added to your programs.


Why We Need It

Here are some common problems that we have all had in developing machine language routines for Applesoft:
!lm17

*  Where do you put it?  You don't want to clobber
   Applesoft or DOS, and you don't want either of
   them to clobber your routines.
*  How do you get to it?  CALL? Ampersand? USR?
*  What do you do when you want to add a second routine?
*  How do you pass data to the subroutine, and get answers
   back?
!lm12

Most of the time we have put all of our routines at location $300-$3CF because that is a free area.  It works great until you need the same space for a second or third routine.  We also have been using the POKE technique of placing the machine language routine at location $300 and then calling it with CALL 768 or using the Ampersand command.  This is fine for 1 or 2 routines, but you lose the full advantage of the speed of these routines waiting for them to be POKEd into memory.  AMPER-MAGIC solves all of the above problems nicely.

AMPER-MAGIC hides your subroutines "underneath" your Applesoft program so that they are loaded automatically along with the Applesoft program.  AMPER-MAGIC can handle 255 different subroutines of varying lengths.  You can use as much space as necessary, up to the limit of memory.  That solves the problem finding space for your routines.

The Ampersand ("&") command of Applesoft followed by the name of your routine is used to gain access to your subroutines. More about subroutine names later.  By pointing the Ampersand vector at $3F5-$3F7 to the proper place, AMPER-MAGIC decodes the name of the routine desired and then transfers control to it.  That solves the problem of linkage to more than one subroutine, and in a way that is human readable!

There is one limitation to the subroutines which can be used within AMPER-MAGIC:  they must be fully relocatable subroutines. Without any change or reassembly they must be able to work at a new address.
!np
Why?  Because they are located at the end of your Applesoft program.  As you edit your program, even just a little, the subroutines will probably move to a different address.

A fully relocatable subroutine is one which does not make any direct references to any address WITHIN the subroutine.  There can not be any JMP, JSR, LDA, STA, etc. to an address within the subroutine.  Only relative addressing branch commands may be used within subroutines.

Many of the subroutines published within AAL this past year were not fully relocatable but they could be made so easily.  Maybe I will spend some time in a future issue discussing techniques on how to make subroutines fully relocatable.  Roger Wagner, in his "Assembly Lines" column in Softalk Magazine, explained many of the motives and methods involved.


AMPER-MAGIC lets you select any name you wish for your subroutines, even for the subroutines in the AMPER-MAGIC library.

Names may be up to 4 bytes long.  That is bytes, not necessarily characters.  Applesoft tokenizes every command name or function name into a one byte token.  Thus you can call your subroutines PRINT, INPUT, GET, etc. which only take up one byte each.  A name like CLEAREOL is a legal AMPER-MAGIC name and only takes up 4 bytes (one for CLEAR, three for EOL).  This allows you to name your own subroutines very descriptively for future reference.

To call a subroutine from within your program you simply use the & (Ampersand) followed by your subroutine name, followed by a "," and then your variables. The comma is not needed if there are no variables. For example:   &GOTO,A*5  or &CLEAREOL:.


The AMPER-MAGIC administrative program is a smooth operating menu driven program which prompts you all along the way.  Here is how you use it:
!lm17

1.  Load your Applesoft program.
2.  Put the AMPER-MAGIC diskette in a drive and type
    EXEC AMPER-MAGIC.  (Specify slot and drive if not
    the same as the last accessed one.)
3.  Fill in information after the prompts, as required.

!lm12
By following the menu and the well-written documentation, you can add, change, delete, and rename any subroutine in your program.  You may add or delete any number of subroutines in one session.

You can load a subroutine directly from the keyboard in either decimal or hex. Thus many of the routines published in AAL can just be typed directly into AMPER-MAGIC.
!np
If you have subroutines already assembled on disk, you simply tell AMPER-MAGIC the file names watch it work.  AMPER-MAGIC makes room in the subroutine table at the end of your program, and loads the subroutine into your program.  Really neat!  Everything is handled automatically except for the subroutine name, which you must supply.

There isn't enough room here to describe all the other functions available, but suffice to say that AMPER-MAGIC gives you all the administrative functions you need to selectively add or delete any subroutines from your program easily and quickly.

Once you have finished with AMPER-MAGIC you simply EXIT via the menu.  AMPER-MAGIC returns all your program pointers to their previous state, and clears itself out.  Your program has now been modified and you can run it to check out the new subroutine.  If you need to make further changes, just EXEC AMPER-MAGIC again.

The AMPER-MAGIC program alone is probably enough to justify its purchase, but you also get 23 ready to use subroutines.  Some of these were originally published right here in AAL.  Bob Nacon modified them wherever necessary to make them fully relocatable.

Here is a list of some of the subroutines on the disk:
!lm17

&FIND,v$,v$,v     Find a substring in a string.
&DARY,v           Delete an array.
&GET,v,v          PEEK a two-byte value.
&GOSUB,v          GOSUB to a variable line.
&GOTO,v           GOTO to a variable line.
&INPUT,v$         Input a line containing even commas,
                  quotation marks, or colons.
!lm12

The ones listed above only give you the flavor.  Remember, there are 23!

One of the best features of all of these subroutines is that all information is passed to and from the subroutines via variables, just like regular commands.  No peeking or poking to set up parameters.  This is a very professional touch, and makes the subroutines truly useful.

Each subroutine is described in detail, with all the information and examples you need to use them effectively.

As you can probably tell, I like this program.  It provides all of us an easy way to add all those neat routines we have been working on, or wanting to work on, and never had a good way of accessing them.

AMPER-MAGIC is available from your local dealer or from AURORA Systems Inc., Madison, WI 53704.
