@DATABASE Tools.guide
@AUTHOR "Tor Erik Ottinsen"
@$VER: AMOSPro_Tools.Guide v1.01   (09.03.97)
@WIDTH 77
@NODE MAIN "Tools - An extension for AMOSPro"

                                  @{u}@{b}AMOSPro Tools Extension v1.01@{uu}@{ub}

     Release Date: 09.03.97

     @{" Introduction          " LINK Introduction}  -  A quick introduction
     @{" Installation          " LINK Installation}  -  How to install

     @{" Array Commands        " LINK ArrayCom}  -  Commands to deal with arrays
     @{" Memory Commands       " LINK MemCom}  -  Commands to move data to or from memory
     @{" Miscellanous Commands " LINK MiscCom}  -  Commands for various tasks
     @{" Interface Commands    " LINK InterfaceCom}  -  Internal commands

     @{" History               " LINK History}  -  A brief history
     @{" Disclaimer            " LINK Disclaimer}  -  IMPORTANT!
     @{" Contacting the author " LINK Contact}  -  How to get in touch with me
@ENDNODE

@NODE Introduction "Introduction"

The AMOSPro Tools extension was originally developed for personal use only.
As time passed it grew as I needed more commands. I think some of the
commands might be of use to others as well, so i wrote this doc and
released it to the public domain.

My apologies for any bad english you might find :)
@ENDNODE

@NODE Installation "Installing Tools"

The following files should be in the archive:

	AMOSPro_Tools.Lib
	AMOSPro_Tools.Guide
	AMOSPro_Tools.Guide.info

To install the Tools Extension for AMOS Professional, do the following:

 - Copy AMOSPro_Tools.Lib to AMOSPro_System:APSystem/

 - Load AMOSPro, and select "Set Interpreter" from the config menu.
   Load the default configuration and click on loaded extensions.
   Enter 'AMOSPro_Tools.Lib' into slot 23 and save the default
   configuration.

 - Quit and restart AMOSPro.
@ENDNODE



@NODE ArrayCom "Commands to deal with arrays"

When you dimension an array in AMOSPro, you have three choices. Either you
make it a string array, an array of longs, or an array of floats. This is ok
for most uses, but what if you need to dimension a very large array
containing normal numbers. Such arrays are often used in map based games.
Often, the numbers stored in the array never get any bigger than 255 and
could in fact fit into a byte. If such is the case, you are using four times
the memory actually needed. This is where the array commands come into use.
They allow you to create a two-dimensional array consisting of bytes, not
longwords as in AMOSPro arrays. The array is stored in a memory bank.

@{u}Commands to deal with arrays:@{uu}

@{" Set Array Bank " LINK ArraySetBank}  -  Choose an arraybank
@{" = Array Bank   " LINK ArrayBank}  -  Return the currently used arraybank
@{" Array Dim      " LINK ArrayDim}  -  Dimension an array
@{" Array Set      " LINK ArraySet}  -  Set an element of the array
@{" = Array Get    " LINK ArrayGet}  -  Get an element of the array
@ENDNODE

@NODE ArraySetBank "Choosing which bank to use"
@TOC ArrayCom

@{b}Set Array Bank@{ub} BANK

This command tells the Tools extension which memorybank should be used by
the other Array Commands. By changing the array bank in the middle of the
program, you can in fact have two or more arrays.
The default is bank number 23.

@{b}See also:@{ub}

@{" = Array Bank " LINK ArrayBank}
@ENDNODE

@NODE ArrayBank "Getting the currently used array bank"
@TOC ArrayCom

@{b}= Array Bank@{ub}

Returns the number of the currently used array bank.

@{b}See also:@{ub}

@{" Set Array Bank " LINK ArraySetBank}
@ENDNODE

@NODE ArrayDim "Dimensioning an array"
@TOC ArrayCom

@{b}Array Dim@{ub} SX, SY

This command reserves a memory bank to use for an array. SX and SY refers
to the size of the array. The AMOSPro Array equalient of this command would
be Dim _ARRAY(SX,SY). Which memory bank to use can be altered with the
@{b}Set Array Bank@{ub} Command. The default is bank number 23.

@{b}NOTE:@{ub} If the memory bank already exists,
      it will be erased before the array bank is created!

@{b}See also:@{ub}

@{" Set Array Bank " LINK ArraySetBank}
@ENDNODE

@NODE ArraySet "Setting an element of the array"
@TOC ArrayCom

@{b}Array Set@{ub} X, Y, DATA

Sets the element at position (X,Y) in the current array to DATA.
DATA should be a positive number between 0 and 255.

@{b}See also:@{ub}

@{" Array Dim   " LINK ArrayDim}
@{" = Array Get " LINK ArrayGet}
@ENDNODE

@NODE ArrayGet "Getting an element of the array"
@TOC ArrayCom

@{b}= Array Get@{ub} (X, Y)

Returns the data at position (X,Y) in the current array.

@{b}See also:@{ub}

@{" Array Dim " LINK ArrayDim}
@{" Array Set " LINK ArraySet}
@ENDNODE



@NODE MemCom "Commands to move data to or from memory"

The commands in this section move data (bytes, words, longwords, strings)
from variables to memory and vice versa. Using these commands to store
data in a memorybank, then saving it to a file, represents a much better
way of storing data than using Print # and Input #.

@{u}Commands to deal with data in memory:@{uu}

@{" Set Pos      " LINK MemSetPos}  -  Setting the current memory position
@{" = Get Pos    " LINK MemGetPos}  -  Getting the current memory position
@{" Add Pos      " LINK MemAddPos}  -  Incrementing the current memory position

@{" Set Byte     " LINK MemSetByte}  -  Storing a byte in memory
@{" Set Word     " LINK MemSetWord}  -  Storing a word in memory
@{" Set Long     " LINK MemSetLong}  -  Storing a longword in memory
@{" Set String   " LINK MemSetString}  -  Storing a string in memory
@{" Set Crypt    " LINK MemSetCrypt}  -  Storing an encrypted string in memory

@{" = Get Byte   " LINK MemGetByte}  -  Getting a byte from memory
@{" = Get Word   " LINK MemGetWord}  -  Getting a word from memory
@{" = Get Long   " LINK MemGetLong}  -  Getting a longword from memory
@{" = Get String " LINK MemGetString}  -  Getting a string from memory
@{" = Get Crypt  " LINK MemGetCrypt}  -  Getting an encrypted string from memory
@ENDNODE

@NODE MemSetPos "Setting the current memoryposition"
@TOC MemCom

@{b}Set Pos@{ub} ADDRESS

This command will set the @{"current memory position" LINK MemCurrMemPos} to ADDRESS.
You should always set the current memory position before using any of the
other Set and Get commands. Not doing this may crash the computer, as data
will be written or read from random memory addresses.

@{b}See also:@{ub}

@{" = Get Pos " LINK MemGetPos}
@{" Add Pos   " LINK MemAddPos}
@ENDNODE

@NODE MemGetPos "Getting the current memoryposition"
@TOC MemCom

@{b}= Get Pos@{ub}

Returns the @{"current memory position" LINK MemCurrMemPos}.

@{b}See also:@{ub}

@{" Set Pos " LINK MemSetPos}
@{" Add Pos " LINK MemAddPos}
@ENDNODE

@NODE MemAddPos "Incrementing the current memoryposition"
@TOC MemCom

@{b}Add Pos@{ub} INCREMENT

Increments the @{"current memory position" LINK MemCurrMemPos} with INCREMENT. To decrement the
current memory position, use a negative INCREMENT. This command can be
useful for skipping data.

@{b}See also:@{ub}

@{" Set Pos   " LINK MemSetPos}
@{" = Get Pos " LINK MemGetPos}
@ENDNODE

@NODE MemSetByte "Storing a byte in memory"
@TOC MemCom

@{b}Set Byte@{ub} BYTE

Set Byte will store BYTE at the @{"current memory position" LINK MemCurrMemPos}.
After the byte is stored, the current memory position will be
incremented by 1.

@{b}See also:@{ub}

@{" Set Pos    " LINK MemSetPos}
@{" = Get Byte " LINK MemGetByte}
@ENDNODE

@NODE MemSetWord "Storing a word in memory"
@TOC MemCom

@{b}Set Word@{ub} WORD

Set Word will store WORD at the @{"current memory position" LINK MemCurrMemPos}.
After the word is stored, the current memory position will be
incremented by 2.

@{b}See also:@{ub}

@{" Set Pos    " LINK MemSetPos}
@{" = Get Word " LINK MemGetWord}
@ENDNODE

@NODE MemSetLong "Storing a longword in memory"
@TOC MemCom

@{b}Set Long@{ub} LONGWORD

Set Long will store LONGWORD at the @{"current memory position" LINK MemCurrMemPos}.
After the longword is stored, the current memory position will be
incremented by 4.

@{b}See also:@{ub}

@{" Set Pos    " LINK MemSetPos}
@{" = Get Long " LINK MemGetLong}
@ENDNODE

@NODE MemSetString "Storing a string in memory"
@TOC MemCom

@{b}Set String@{ub} STRING$

Set String will store STRING$ at the @{"current memory position" LINK MemCurrMemPos}.
After the string is stored, the current memory position will be
incremented by @{i}the length of the string + 2.@{ui}

@{b}See also:@{ub}

@{" Set Pos      " LINK MemSetPos}
@{" = Get String " LINK MemGetString}
@ENDNODE

@NODE MemSetCrypt "Storing an encrypted string in memory"
@TOC MemCom

@{b}Set Crypt@{ub} STRING$

Set Crypt will store STRING$ at the @{"current memory position" LINK MemCurrMemPos}.
However before doing this, the string is encrypted making it unreadable.
The algorithm used for encryption isn't very secure, so please do not
store any sensitive data with this command.
After the string is stored, the current memory position will be
incremented by @{i}the length of the string + 2.@{ui}

@{b}See also:@{ub}

@{" Set Pos     " LINK MemSetPos}
@{" = Get Crypt " LINK MemGetCrypt}
@ENDNODE

@NODE MemGetByte "Getting a byte from memory"
@TOC MemCom

@{b}= Get Byte@{ub}

Get Byte will return the byte stored at the @{"current memory position" LINK MemCurrMemPos}.
After retrieving the byte, the current memory position will be
incremented by 1.

@{b}See also:@{ub}

@{" Set Pos  " LINK MemSetPos}
@{" Set Byte " LINK MemSetByte}
@ENDNODE

@NODE MemGetWord "Getting a word from memory"
@TOC MemCom

@{b}= Get Word@{ub}

Get Word will return the word stored at the @{"current memory position" LINK MemCurrMemPos}.
After retrieving the word, the current memory position will be
incremented by 2.

@{b}See also:@{ub}

@{" Set Pos  " LINK MemSetPos}
@{" Set Word " LINK MemSetWord}
@ENDNODE

@NODE MemGetLong "Getting a longword from memory"
@TOC MemCom

@{b}= Get Long@{ub}

Get Long will return the longword stored at the @{"current memory position" LINK MemCurrMemPos}.
After retrieving the longword, the current memory position will be
incremented by 4.

@{b}See also:@{ub}

@{" Set Pos  " LINK MemSetPos}
@{" Set Long " LINK MemSetLong}
@ENDNODE

@NODE MemGetString "Getting a string from memory"
@TOC MemCom

@{b}= Get String@{ub}

Get String will return the string stored at the @{"current memory position" LINK MemCurrMemPos}.
After retrieving the string, the current memory position will be
incremented by @{i}the length of the string + 2.@{ui}

@{b}See also:@{ub}

@{" Set Pos    " LINK MemSetPos}
@{" Set String " LINK MemSetString}
@ENDNODE

@NODE MemGetCrypt "Getting an encrypted string from memory"
@TOC MemCom

@{b}= Get Crypt@{ub}

Get Crypt will return the string stored at the @{"current memory position" LINK MemCurrMemPos}.
After retrieving the string, the current memory position will be
incremented by @{i}the length of the string + 2.@{ui}
The string will be decrypted before it is returned.

@{b}See also:@{ub}

@{" Set Pos   " LINK MemSetPos}
@{" Set Crypt " LINK MemSetCrypt}
@ENDNODE

@NODE MemCurrMemPos "The current memory position"
@TOC MemCom

The current memory position is where the Set commands (Set Byte etc.) will
store their data. The Get commands will also get their data from this
address. All Set and Get commands will increase the current memory position
by the length of their data after setting or getting. In other words,
Set Byte and Get Byte will increase the current memory position with 1,
Set Word and Get Word with 2, and so on.
@ENDNODE



@NODE InterfaceCom "Internal Interface Commands"

The Tools Extension has got a number of interface commands used by my so
far unreleased GUI System. These are internal commands of no use for
anybody except me. I therefore choose to leave them undocumented.
@ENDNODE

@NODE MiscCom "Commands for various tasks"

@{u}Miscellanous commands:@{uu}

@{" = Range    " LINK MiscRange}  -  Limit a number to a certain range

@{" Encode     " LINK MiscEncode}  -  Encode a piece of memory
@{" Decode     " LINK MiscDecode}  -  Decode a piece of memory

@{" = Checksum " LINK MiscChecksum}  -  Calculate checksum of a piece of memory
@ENDNODE

@NODE MiscRange "Limit a number to a certain range"
@TOC MiscCom

@{b}= Range@{ub} (A, MIN To MAX)

This command is a somewhat optimized version of the Range command in the
Shuffle Extension. If the number A lies between MIN and MAX, A is returned.
If A is less than MIN, MIN is returned. If A is greater than MAX, MAX is
returned.

@{b}See also:@{ub}
@ENDNODE

@NODE MiscEncode "Encode a piece of memory"
@TOC MiscCom

@{b}Encode@{ub} START, LENGTH, PASSWORD$

Encode will scramble the contents of memory between address START and
START+LENGTH. PASSWORD$ is a password used for encryption.
To unscramble, use the command @{b}Decode@{ub} with the same password.

@{b}See also:@{ub}

@{" Decode " LINK MiscDecode}
@ENDNODE

@NODE MiscDecode "Decode a piece of memory"
@TOC MiscCom

@{b}Decode@{ub} START, LENGTH, PASSWORD$

Use decode to unscramble something which you have already scrambled with
@{b}Encode@{ub}. START and LENGTH specifies the the start address and size
of the memory area you wish to decrypt. PASSWORD$ should be the same password
you used for encryption.

@{b}See also:@{ub}

@{" Encode " LINK MiscEncode}
@ENDNODE

@NODE MiscChecksum "Calculate checksum of a piece of memory"
@TOC MiscCom

@{b}= Checksum@{ub} (START To END)

Will return the checksum of the contents of memory between location START
and END.

@{b}See also:@{ub}
@ENDNODE



@NODE History "History"

 @{u}@{b}Version 1.00@{uu}     (26.02.97)@{ub}

    ° First public release

 @{u}@{b}Version 1.01@{uu}     (09.03.97)@{ub}

    ° Fixed a bug in the documentation concerning the format of
      the commands @{b}Encode@{ub} and @{b}Decode@{ub}.

    ° Added a new command - @{b}Checksum@{ub} - to calculate the checksum of a
      memory area.
@ENDNODE

@NODE Disclaimer "Disclaimer"

@{b}Disclaimer:@{ub}

I, the author, nor anybody else will take any responsibility whatsoever
for anything any of the files in this package might do to you, your computer,
or anything else. Use this product entirely at your own risk.

All files are PUBLIC DOMAIN, which means you might spread them all you want,
as long as you keep the archive complete, and do not modify any of the files.
@ENDNODE

@NODE Contact "Contacting the author"

Please let me know how you like this extension, and if you have any problems.
I would also appreciate any comments or suggestions you might have.

To reach me you can use one of the following addresses:

S-mail:
	Tor Erik Ottinsen
	Stovnerlia 33
	0983, Oslo
	NORWAY

E-mail:
	ottinst@pc.iu.hioslo.no

@ENDNODE