home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Amiga MA Magazine 1998 #7
/
amigamamagazinepolishissue1998.iso
/
www
/
rwe
/
developer
/
blitz.doc
next >
Wrap
Text File
|
1997-07-03
|
24KB
|
818 lines
TABLE OF CONTENTS
blitz.library/AddTokenUpdate
blitz.library/AllocXtra
blitz.library/DelTokenUpdate
blitz.library/DetokeLine
blitz.library/DetokeMem
blitz.library/FindToken
blitz.library/FreeBlitzLibs
blitz.library/FreeTokeMem
blitz.library/FreeXtra
blitz.library/GetBlitzLibInfo
blitz.library/GetFirstToken
blitz.library/GetLineHeaderSize
blitz.library/GetObjectMaximum
blitz.library/GetObjectName
blitz.library/GetVersion
blitz.library/LoadBlitzLibs
blitz.library/LoadFile
blitz.library/LoadXtra
blitz.library/LockBlitzLibs
blitz.library/NewDetokeLine
blitz.library/NumMaximums
blitz.library/SaveXtra
blitz.library/SetObjectMaximum
blitz.library/SortTokens
blitz.library/TokeLine
blitz.library/TokeMem
blitz.library/UnLockBlitzLibs
blitz.library/AddTokenUpdate blitz.library/AddTokenUpdate
NAME
AddTokenUpdate -- install a notification hook for command-library updates.
SYNOPSIS
AddTokenUpdate(functionPtr);
A0
FUNCTION
This command lets you automatically have a function called whenever the
blitz command libraries are updated (i.e. calls to FreeBlitzLibs(),
LoadBlitzLibs() etc).
Any registers may be treated as scratch registers.
INPUTS
functionPtr - address of routine to call
RESULT
NONE
BUGS
A maximum of 16 notification hooks can be installed. No checking is
performed to ensure that the limit is not exceeded.
SEE ALSO
DelTokenUpdate()
blitz.library/AllocXtra blitz.library/AllocXtra
NAME
AllocXtra -- allocate and initialise a valid BlitzXtra structure.
SYNOPSIS
xtraFile = AllocXtra();
D0
struct BlitzXtra * AllocXtra(VOID);
FUNCTION
This command allocates a new BlitzXtra structure, filling fields
with default values.
INPUTS
NONE
RESULT
xtraFile - an initialized BlitzXtra structure, or NULL on failure.
SEE ALSO
FreeXtra(), <libraries/blitz.h>, <libraries/blitz.i>
blitz.library/DelTokenUpdate blitz.library/DelTokenUpdate
NAME
DelTokenUpdate -- remove a previously created notification hook for
command-library updates.
SYNOPSIS
DelTokenUpdate(functionPtr);
A0
FUNCTION
This command removes a notification request, as created by a previous
call to AddTokenUpdate().
INPUTS
functionPtr - address of routine to remove from notification list
RESULT
NONE
SEE ALSO
AddTokenUpdate()
blitz.library/DetokeLine blitz.library/DetokeLine
NAME
DetokeLine -- detokenise a line containing valid tokenised Blitz source
code.
SYNOPSIS
success = DetokeLine(tokenSource,asciiDest);
D0 A0 A1
BOOL = DetokeLine(char * tokenSource, char * asciiDest);
FUNCTION
This command will convert a line containing tokenised source into its
detokenised equivalent, placing the resulting string in the destination
buffer.
INPUTS
tokenSource - a pointer to a line containing tokenised source
(NOTE: the line should not contain any headers)
asciiDest - a pointer to a line buffer where the detokenised line is to
be placed
RESULT
success - indication of success or failure
NOTES
asciiDest should be at least 128 bytes in size. This routine will not
create a detokenised string of more than 128 bytes.
blitz.library/DetokeMem blitz.library/DetokeMem
NAME
DetokeMem -- detokenise a block of memory containing valid tokenised
Blitz source code.
** THIS FUNCTION IS NOT YET IMPLEMENTED **
SYNOPSIS
success = DetokeMem(tokenSource,asciiDest,length);
D0 A0 A1 D0
BOOL = DetokeLine(char * tokenSource, char * asciiDest, ULONG length);
FUNCTION
This function will detokenise a block of memory into its detokenised
ASCII equivalent, placing the resultant data in the destination buffer.
INPUTS
tokenSource - a pointer to a block of memory containing tokenised source
asciiDest - a pointer to the destination ASCII buffer. This must be at
least as big as numlines * 128 in size
length - the size of the source block
RESULT
success - indication of success or failre
NOTES
** THIS FUNCTION IS NOT YET IMPLEMENTED **
blitz.library/FindToken blitz.library/FindToken
NAME
FindToken -- retrieve the location inside the Blitz command libraries
of a given token.
SYNOPSIS
tokenptr = FindToken(token);
A3 D0:16
struct BlitzToken * tokenptr = FindToken(UWORD token);
FUNCTION
This function will traverse the Blitz command libraries. If the given
token is found, the address of the token is returned - else a standard
ERROR token.
INPUTS
token - a 2 byte token number
RESULT
tokenptr - a pointer to the token (or an ERROR token)
blitz.library/FreeBlitzLibs blitz.library/FreeBlitzLibs
NAME
FreeBlitzLibs -- free memory allocated to Blitz libraries
SYNOPSIS
FreeBlitzLibs();
FUNCTION
This function will free memory allocated by a previous call to
LoadBlitzLibs()
INPUTS
NONE
RESULT
NONE
NOTES
This call may fail if the Blitz libraries are currently locked.
Programs which installed a notification hook will NOT be notified of
this change, and are removed from the notification list.
This function is typically only called by the librarie's Expunge()
function, and not by applications.
SEE ALSO
LoadBlitzLibs()
blitz.library/FreeTokeMem blitz.library/FreeTokeMem
NAME
FreeTokeMem -- free memory allocated by a previous call to TokeMem()
SYNOPSIS
FreeTokeMem(tokeMem);
A0
FUNCTION
This function will free any memory allocated by a call to TokeMem().
INPUTS
tokeMem - a pointer to a block of tokenised source, as returned by the
call to TokeMem()
RESULT
NONE
NOTES
It is necessary for an application to keep a track of values returned
by TokeMem() and similar functions, since the library does not perform
any garbage collection upon expunge.
SEE ALSO
TokeMem()
blitz.library/FreeXtra blitz.library/FreeXtra
NAME
FreeXtra -- free memory allocated by the functions AllocXtra() and
LoadXtra()
SYNOPSIS
FreeXtra(xtraFile);
A0
void FreeXtra(struct BlitzXtra * xtraFile);
FUNCTION
This function will free any memory allocated by a call to AllocXtra()
or LoadXtra()
INPUTS
xtraFile - a pointer to a valid BlitzXtra structure, as returned by
either AllocXtra() or LoadXtra()
RESULT
NONE
NOTES
It is necessary for an application to keep a track of values returned
by AllocXtra(), LoadXtra() and similar functions, since the library does
not perform any garbage collection upon expunge.
SEE ALSO
AllocXtra(), LoadXtra()
blitz.library/GetBlitzLibInfo blitz.library/GetBlitzLibInfo
NAME
GetBlitzLibInfo -- fill out an applications BlitzLibComData structure with
relevant information
SYNOPSIS
success = GetBlitzLibInfo(comData);
D0 A0
BOOL success = GetBlitzLibInfo(struct BlitzLibComData * comData);
FUNCTION
Following a call to LoadBlitzLibs(), the Blitz compiler requires certain
information around the structure of the libraries. This function fills out
a structure with this information.
INPUTS
comData - a pointer to a previously created instance of a BlitzLibComData
structure
RESULT
success - an indication of success or failure
NOTES
This routine is typically only required by the Blitz compiler
SEE ALSO
LoadBlitzLibs(), <libraries/blitz.h>, <libraries/blitz.i>
blitz.library/GetFirstToken blitz.library/GetFirstToken
NAME
GetFirstToken -- obtain the address of the first token in the library list
SYNOPSIS
token = GetFirstToken();
D0
struct BlitzToken * token = GetFirstToken(VOID);
FUNCTION
This function returns the address of the first token in the library list,
as created by a previous call to LoadBlitzLibs()
INPUTS
NONE
RESULT
D0 - a pointer to the first token in memory, or NULL for failure
SEE ALSO
LoadBlitzLibs(), FindToken()
blitz.library/GetLineHeaderSize blitz.library/GetLineHeaderSize
NAME
GetLineHeaderSize -- get the size of the header prepended to Blitz source
code
SYNOPSIS
size = GetLineHeaderSize();
D0
UWORD size = GetLineHeaderSize(VOID);
FUNCTION
The standard Blitz line structure was fixed at 9 bytes. This consisted of
the usual Previous and Next pointers, as well as a byte indicating how
many characters are on the line. From v2.2 onwards, an extra control field
was inserted to allow procedure folding. To improve backwards compatibility
or programs it is necessary to know how large this header is. It can be
assumed that the following fields remain static :
NEXT 0
PREVIOUS 4
NUMCHARS HEADERSIZE-1
CHARS HEADERSIZE
This allows additional fields to be inserted without risking incompatibility
with older software.
INPUTS
NONE
RESULT
size - the number of bytes which make up the line header
blitz.library/GetObjectMaximum blitz.library/GetObjectMaximum
NAME
GetObjectMaximum -- get the maximum number of instances for a given Blitz
object
SYNOPSIS
maximum = GetObjectMaximum(xtraFile, libNum);
D0 A0 D0:16
WORD maximum = GetObjectMaximum(struct BlitzXtra * xtraFile, UWORD libNum);
FUNCTION
Each blitz library can have an associated 'object'. When compiling programs,
it is necessary for the compiler to allocate a fixed size object buffer. To
achieve this, a user-definable limit is set on the number of instances that
can be created for any given object. This information is stored in the
Blitz .xtra file. This function, when passed a valid library number and
BlitzXtra structure can return the maximum instances for the library's
associated object.
INPUTS
xtraFile - a pointer to a valid BlitzXtra structure, as returned by a call
to either AllocXtra() or LoadXtra()
libNum - the library's identification number
RESULT
maximum - the maximum number of instances that can be created for the
library's associated object (-1 indicated that no object
is associated with the given library)
SEE ALSO
GetObjectName(), AllocXtra(), LoadXtra(), <libraries/blitz.h>,
<libraries/blitz.i>
blitz.library/GetObjectName blitz.library/GetObjectName
NAME
GetObjectName -- get the name for a library's associated object
SYNOPSIS
name = GetObjectName(xtraFile, libNum);
D0 A0 D0:16
char * name = GetObjectName(struct BlitzXtra * xtraFile, UWORD libNum);
FUNCTION
Each blitz library can have an associated 'object'. Each object has a unique
name, which is used when a programmer wishes to access a particular instance
of the object, or adjust the maximum instances of the object. This function
returns the name of the object associated with the given library.
INPUTS
xtraFile - a pointer to a valid BlitzXtra structure, as returned by a call
to either AllocXtra() or LoadXtra()
libNum - the library's identification number
RESULT
name - a pointer to the object's name (or NULL if the library does not
have an associated object)
BUGS
The memory used to return the string is shared. This means that
should two applications call this function together, the result is
unpredictable
SEE ALSO
GetObjectMaximum(), AllocXtra(), LoadXtra(), <libraries/blitz.h>,
<libraries/blitz.i>
blitz.library/GetVersion blitz.library/GetVersion
NAME
GetVersion -- obtain a string indicating the version of the library
SYNOPSIS
version = GetVersion();
D0
char * version = GetVersion(VOID);
FUNCTION
This function simply returns the version of the library as a string.
INPUTS
NONE
RESULT
version - a pointer to a null terminated version string
NOTES
This function is primarily designed to be called by SuperTED - enabling
the version of the compiler to be adjusted.
Do NOT modify the contents of the string - make a copy if you need to
blitz.library/LoadBlitzLibs blitz.library/LoadBlitzLibs
NAME
LoadBlitzLibs -- load available Blitz libraries from disk
SYNOPSIS
success = LoadBlitzLibs();
D0
BOOL success = LoadBlitzLibs(VOID);
FUNCTION
This function will allocate memory for and read all available command
libraries from disk. The token and library tables are created. If the
libraries have already been loaded by a previous call, then this
function effectively does nothing.
INPUTS
NONE
RESULT
success - an indication of success or failure
NOTES
This function will fail if the libraries have been locked.
SEE ALSO
FreeBlitzLibs()
blitz.library/LoadFile blitz.library/LoadFile
NAME
LoadFile -- load a source code file into memory
SYNOPSIS
filePtr = LoadFile(fileName);
D0 A0
struct BlitzFile * filePtr = LoadFile(char * fileName);
FUNCTION
This function will load a file into memory. Memory required to store the
file is allocated by this function. This function can read ASCII files
as well as the standard Blitz tokenised source files. Tokenisation is
performed if required.
INPUTS
fileName - a pointer to a null-terminated string holding the name of the
file to load
RESULT
filePtr - a pointer to a BlitzFile structure (or NULL for failure)
blitz.library/LoadXtra blitz.library/LoadXtra
NAME
LoadXtra -- load a source file's .xtra file into memory
SYNOPSIS
xtraFile = LoadXtra(fileName);
D0 A0
struct BlitzXtra * xtraFile = LoadXtra(char * fileName);
FUNCTION
This function will allocate memory for and load into this memory a Blitz
.xtra file.
INPUTS
fileName - a pointer to a null-terminated string holding the name of the
.xtra file to load
RESULT
xtraFile - a pointer to the associated BlitzXtra structure (or NULL for
failure)
NOTES
No checking is made to ensure that the file passed is a valid .xtra file
blitz.library/LockBlitzLibs blitz.library/LockBlitzLibs
NAME
LockBlitzLibs -- prevent access or modification to the Blitz command
libraries in memory
SYNOPSIS
success = LockBlitzLibs(accessMode);
D0 D0
BOOL success = LockBlitzLibs(WORD accessMode);
FUNCTION
This function, given the appropriate access mode, will lock the Blitz
command libraries to prevent another task from either :
a) Accessing them
b) Modifying them
INPUTS
accessMode - a valid access mode. Can be one of either :
LIBS_ACCESS_EXCLUSIVE
LIBS_ACCESS_READ
RESULT
success - TRUE or FALSE if the lock was successful. FALSE indicates either :
An EXCLUSIVE lock was present
A READ lock was present and you requested an EXCLUSIVE lock
BUGS
No validation is performed on the accessMode. Therefore, invalid accessModes
will result in unpredictable behaviour
SEE ALSO
UnlockBlitzLibs()
blitz.library/NewDetokeLine blitz.library/NewDetokeLine
NAME
NewDetokeLine -- an experimental command design to make line detokenisation
more flexible
SYNOPSIS
success = NewDetokeLine(srcToken, destNonToken, destToken);
D0 A0 A1 A2
BOOL success = NewDetokeLine(char * srcToken, char * destNonToken,
char * destToken);
FUNCTION
This function is a prototype command designed to be used by the new version
of SuperTED, currently in development. In order to speed up the text displays,
a new approach to detoking lines was developed. The tokenised source line
is detoked into two buffers - one containing non-token source, the other
containing token-source (the latter which should be displayed in a 'special'
colour).
For example :
NPrint "This is a Test" : MouseWait
would be detokenised to :
"This is a test" : ; non-token source
NPrint MouseWait ; token source
INPUTS
srcToken - a pointer to the NULL terminated tokenised line of source code
destNonToken - a pointer to the buffer to be used to store non-token source
destToken - a pointer to the buffer to be used to store token source
RESULT
success - an indication of the commands success. This function will return
FALSE if the command libraries have not been loaded.
NOTES
Since this function is in prototype stage, it is not recommended that
application developers use this function.
blitz.library/NumMaximums blitz.library/NumMaximums
NAME
NumMaximums -- return the number of objects in the library list
SYNOPSIS
nummaxs = NumMaximums();
D0
UINT nummaxs = NumMaximums(VOID):
FUNCTION
Although slightly misleading by name, this function will return the total
number of objects associated with the various Blitz command libraries.
INPUTS
NONE
RESULT
nummaxs - the number of objects in the library list
BUGS
At preset (v2.2) this command ignores the Lock status of the libraries.
blitz.library/SaveXtra blitz.library/SaveXtra
NAME
SaveXtra -- save a .xtra file to disk
SYNOPSIS
success = SaveXtra(fileName, xtraFile);
D0 A0 A1
BOOL success = SaveXtra(char * fileName, struct BlitzXtra * xtraFile);
FUNCTION
This function will save a valid BlitzXtra structure to disk in the form
of a standard Blitz .xtra file.
INPUTS
fileName - a null-terminated string containing the name of the .xtra file
to save
xtraFile - a pointer to a valid BlitzXtra structure
RESULT
success - an indication of success or failure
SEE ALSO
AllocXtra(), FreeXtra(), LoadXtra(), <libraries/blitz.h>, <libraries/blitz.i>
blitz.library/SetObjectMaximum blitz.library/SetObjectMaximum
NAME
SetObjectMaximum -- set the maximum number of instances for a library's
associated object
SYNOPSIS
SetObjectMaximum(libNum, xtraFile);
D0:16 A0
void SetObjectMaximum(UINT libNum, struct BlitzXtra * xtraFile);
FUNCTION
Similar in operation to GetObjectMaximum(), this function will set the
limit.
INPUTS
libNum - the library ID which the object is associated with
xtraFile - a pointer to a valid BlitzXtra structure
RESULT
NONE
SEE ALSO
GetObjectMaximum()
blitz.library/SortTokens blitz.library/SortTokens
NAME
SortTokens -- create a sorted list of all Blitz command tokens
SYNOPSIS
SortTokens();
void SortTokens(VOID);
FUNCTION
This will create a sorted list of all Blitz comman tokens - used to improve
the speed of the tokenisation / detokenisation commands.
INPUTS
NONE
RESULT
NONE
NOTES
This function is designed to be called by SuperTED, and is not intended for
general use by applications.
blitz.library/TokeLine blitz.library/TokeLine
NAME
TokeLine() - tokenise a line of ASCII source into Blitz tokens
SYNOPSIS
success/len = TokeLine(srcAscii, destBuffer);
D0 D1 A0 A1
BOOL success = TokeLine(char * srcAscii, char * destBuffer);
FUNCTION
This function takes a standard null terminated line of ASCII text and
attempts to produce a tokenised version of it.
INPUTS
srcAscii - a null terminated string containing ASCII characters
destBuffer - the destination buffer to store the tokenised source in
RESULTS
success - an indication of whether the command was successful or not
len - the length of the tokenised line
NOTES
This command returns information in TWO registers, D0 and D1, and as
such the second argument can only be accessed by assembly code. C
programmers must calculate the length of the tokenised string themselves
(hunt for a 0 byte). This restriction may change in the future.
SEE ALSO
TokeLine()
blitz.library/TokeMem blitz.library/TokeMem
NAME
TokeMem - tokenise a block of text into Blitz tokens
SYNOPSIS
tokeBlock = TokeMem(srcAscii,maxBlockSize);
UINT = TokeMem(char * srcAscii, UINT maxBlockSize);
FUNCTION
This command takes a block of ASCII text (with each line terminated by
a LF, ASCII code 10) and creates a block of tokenised lines. The length
of the block is specified in the function call.
INPUTS
srcAscii - a pointer to a LF terminated block of ASCII text
maxBlockSize - the size of memory to allocate to hold the tokenised text
RESULT
tokeBlock - a pointer to the tokenised text block (or NULL for failure)
SEE ALSO
DetokeMem()
blitz.library/UnLockBlitzLibs blitz.library/UnLockBlitzLibs
NAME
UnLockBlitzLibs - release a lock on the Blitz command libraries
SYNOPSIS
UnLockBlitzLibs();
void UnLockBlitzLibs(VOID);
FUNCTION
Following a successful call to LockBlitzLibs(), the application must
release the lock when access is not required. This should be done at the
earliest opportunity to enable access for other applications.
INPUTS
NONE
RESULT
NONE
NOTES
This function does not attempt to check if the application already has
an open lock - care must be taken to ensure that calls to LockBlitzLibs()
and UnLockBlitzLibs() are paired.
SEE ALSO
LockBlitzLibs()