AMPLINEX unused word search utility – notes

Kevin Doyle

One of the key elements in AMPLE composition is experiment. Instruments can be altered, different mixes used, and parts added and deleted.

However, the end result of this can often be a cluttered program as well as a good piece of music. And if memory is getting short then extra, unused words need to be identified and deleted.

This utility will show user words which are not in use elsewhere in the program - you can then decide which ones can be deleted.

The utility is in EXEC format and can be read into an existing program using the command

*EXEC U.FREE

In order to disturb the existing contents of the screen as little as possible the screen display is turned off as the utility is read in and switched back on at the end. (If you press Escape whilst the utility is being read in you can turn the display back on with 6#OUT or any MODE command).

To use the utility type in the command

FREE

This will then list (in the same form as the SHOW command) all user words which are not used elsewhere. In a standard music piece some words (such as 'RUN') will always appear in the list. The 'mix' and 'part' words will also appear and the use of these can only be checked by examining the PLAY string in 'RUN'. The utility words 'FREE' and 'FREED' will also always appear.

Other words, which are recognised as redundant can then be deleted using

"wordname" DELETE

To delete the utility itself use the command

FREED

The utility uses 6 words out of the maximum allowed in AMPLE of 125 and therefore it can only be used with user program containing fewer than 120 words.

The utility works by identifying each user word and then searching for its occurrence in every user word. If the word is not found in use anywhere it is displayed on the screen. The time taken for the utility to do its search is therefore a function of the number of user words and their use in other user words. For programs with a large number of words, therefore, the search may take some time - perhaps 30 seconds for a program with 60-70 words.

For those interested in the programming, the utility makes use of some AMPLE Nucleus words which are not normally user-accessible. To access these words their tokens have been written directly into previously defined user words ('#3' to '#6'). These words are initially defined as variables (GVAR). This means that they occupy three bytes (one for the GVAR token and two for its data) and that their addresses are known (since GVAR leaves the address of the data bytes). The contents of the two data bytes are set to &0F00 - the AMPLE tokens for a zero-length comment - and then the GVAR token is overwritten with the AMPLE token required.

There are four such AMPLE words used:

"#3" (&2E) - this returns the address of the next occurrence of a specified byte (or token) in a word. The target byte and the starting address for the search are input to the word and it returns either the address where the byte is found and the ON flag or, if the byte is not found, the OFF flag.

byte startaddr &2E -> foundaddr ON

or

-> OFF

"#4" (&59) - this returns a string containing a word name from the address of the byte before the word name. Once the address of the start of a user word definition is known (see below) then 4 bytes can be added to it to give the address of the byte before the word name. This word can then be used to return the word name as a string.

wordnameaddress &59 -> wordnamestring

"#5" (&73) - this returns the address of the next user word in alphabetical sequence. The address of the start of a word definition and a code (6 for user words, 9 for modules) are input to the word. Its outputs are the address of the next word plus an OFF flag, or, if no more words are found, the same address and an ON flag. To find the first word the input address should be set to 0.

wordaddr code &73 -> nextwordaddr OFF

or

-> wordaddr ON

"#6" (&B8) - this displays a word name string padded with spaces to the right to produce an aligned display. It is used by words such as SHOW and FIND. Word names of less than 10 characters are padded out to 10; those of 10 or more are padded out to 20.

string &B8

Related file on this disc:

U.FREE - AMPLINEX unused word search utility