**************************************************************
*     EXBANCAL - The Avigo Banked Function Call Extractor    *
*                         Version 1.0                        *
*                Copyright(c)1998 Randy Gill                 *
*                    rdgill@earthlink.net                    *
**************************************************************

LICENCE AGREEMENT: BY USING THIS SOFTWARE, OR BY USING THE INCLUDED SOURCE CODE OR OTHER FILES TO CREATE DERIVATIVE WORKS, YOU INDICATE YOUR AGREEMENT TO THE FOLLOWING TERMS:
1) This application is copyrighted "freeware", meaning it may be redistributed freely, provided no charge is made for its distribution or use.  The author does not require any "registration payment" for the use of this product.
2) You may use the included data files and source code in your own products, provided the resulting project is also distributed as "freeware", as defined in the previous paragraph, and provided the author of this package is creditted for the portions used.
3) The author is in no way responsible for damages, incidental or otherwise, resulting from the installation, use, or misuse, of this product.

============
INTRODUCTION
============
This program will take an Avigo .app file that was created using the Avocet compiler, and create an output text file with a listing of all the banked functions and banked function calls inside the program.

I wrote this primarily for myself, to help in my project of developing a GUI library for the Freeware SDK, so there is little error checking.  You may find it useful in descovering things about the operating system, or in trying to find out how certain applications work.  It is most useful when you have source code and/or a mapfile for the app you are examining.

This program is targetted toward the developer with a working knowledge of banked functions.  If you are not familiar with banked functions, please see my soon-to-be-expanded explanation of them on my website.  I will be upgrading it to describe how banked functions are defined and called in Avocet SDK programs, as well as Freeware SDK programs and the Avigo operating system itself (the last two are not supported in this program).

===================
SYSTEM REQUIREMENTS
===================
This program should run on any IBM-PC, PC compatible, or emulator, with at least 256K of available RAM, and DOS 2.0 or higher (it should be compatible with any version of Windows).

==============
INCLUDED FILES
==============
EXBANCAL.TXT - This Documentation File
EXBANCAL.EXE - The EXBANCAL Program
BANKCALL.DAT - The Banked Function Listing Data File
EXBANCAL.PAS - The Turbo Pascal source code for the program

=============
PROGRAM USAGE
=============
Start the program from the DOS command prompt using:

EXBANCAL <infile> <outfile>

For example:

EXBANCAL avpascal.app avpascal.cal

The <outfile> name can have any extension that's convenient for you.  The extension for <infile> will normally be '.app".

The program will begin and print its progress on the screen.  After a few minutes, the program will finish and you will have the output file requested, in ASCII text format.

The output file lists - ordered by bank number and address - the following possible records (all listed values are hexidecimal):

<aaaa> Begin banked function <iiii> **
--------------------------------------
This is the start address <aaaa> of the application's own banked function wilth index number <iiii>.

<aaaa>   Banked Application Call # <iiii>
----------------------------------------
The application calls its own banked function # <iiii> at address <aaaa>.

<aaaa>   <FunctionName>
-----------------------
The application calls banked function <FunctionName> at address <aaaa>.

<aaaa>   UNKNOWN CALL # <iiii>
------------------------------
The application calls a banked function <iiii> that is not an application banked call, and not in the BANKCALL.DAT list (unknown system or library call) at address <aaaa>.

<aaaa>   POSSIBLE MISSED CALL
-----------------------------
EXBANCAL has found what may be a banked call, or maybe just data that 'looks' like a banked call, at address <aaaa>.   This should be rare (I have yet to get this) but if it does occur, use a disassembler to determine whether this is truly a banked call.

============
HOW IT WORKS
============
First the program reads in the first 16k bank of the .app file (bank 0), and finds the applications own banked function table.  It then builds a database of the start addresses of all the applications banked functions.

The program then reads one 16k bank at a time and scans it for the sequence of bytes cooresponding to a banked function call:

  10 yy xx CD 03 30

This corresponds to the Z-80 assembly sequence:

  LD BC, xxyy
  CALL 3003

It cross references the xxyy word against the database loaded from 'BANKCALLS.DAT'.  If it finds a match, it prints the function name to the output file.  If there's no match, it prints either 'Banked Application Call # xxyy' or 'UNKNOWN CALL #xxyy' as appropriate.  If the program finds just the sequence 'CD 03 30' (CALL 3003) without the '10 yy xx' (LOAD BC,xxyy) instruction before it, it outputs 'POSSIBLE MISSED CALL'.

===========
LIMITATIONS
===========
Because of the way this program operates, I have decided not to try to extract non-banked function calls.  There is too much of a chance of 'false positives'.

This program is not designed for analyzing portions of the Avigo operating  systems, or code written with the Freeware SDK.  They all use different methods of handling banked declarations and calls.  Code written in assembler may be compatible with this program, depending on how the author implemented banked functions.  At this point, very few assembler programs use banked functions at all.

=============================================================
MODIFYING THE BANKED FUNCTION LISTING DATAFILE 'BANKCALL.DAT'
=============================================================
Most of the system calls used by the compiler are already discovered, but if you find more you can add them to the database (while you're at it, please notify the author also!)

The format of the data file is plain text, with entries in the format:
<FunctionName>=<BankIndex(hex)>
example:
GetRecordStatus=02F1

Rules for entries
1) No "whitespace" before the <FunctionName>.  Whitespace after the name (eg. "GetAvigoVersion  = 003F") is okay.
2) All entries must be completed on the same line, and only one entry per line.
3) <BankedFunctionName> must be no larger than 32 characters.  <BankIndex> (of course) no more than 4.

===============
PROGRAM SUPPORT
===============
This program is free, so support is very limited.  If you have questions or bug reports, please e-mail them to me, at rdgill@earthlink.net

================
REVISION HISTORY
================
11/15/98, Version 1.0: First public release of Exbancal
