TECHNICAL INFORMATION about RAC.DLL


RAC.DLL is the 32 bit version (for windows 95, NT, and up) of the
DLL for accessing the Database on CD-ROM.


THE DLL

RAC.DLL (the DLL) grants access to the callbook on CD ROM.
The input the DLL needs is
* where to find the CD ROM and
* the call you are looking for.
The output the DLL delivers is the complete entry that belongs to the call.
If the call could not be found, an error is returned.

Basically, the DLL exports three types of routines:
xGetVersionNr, xCheckDatabaseFormat and xGetCallInfo,
where "x" stands for one of the letters "c", "p", "r" or "s".
This results in a total of twelve routines exported by the DLL.

Each version of xGetVersionNr etc. performs the same task, the difference
is only the calling convention used by the routine:

First letter Calling convention
"c" cdecl
"p" pascal
"r" register
"s" stdcall

The calling convention determines the method used for passing parameters
to procedures and functions.

Calling conventions differs in three areas:
Order of passing parameters
Responsibility for removing parameters from the stack ("cleanup")
Use of registers for passing parameters

The register and pascal conventions pass parameters from left to right,
that is the leftmost parameter is evaluated and passed first and the
rightmost parameter is evaluated and passed last. The cdecl and stdcall
conventions pass parameters from right to left. For all conventions except
cdecl, the procedure or function removes parameters from the stack upon
returning. With the cdecl convention, the caller must remove parameters
from the stack when the call returns. The register convention uses up to
three CPU registers to pass parameters, whereas the other conventions always
pass all parameters on the stack.

The calling conventions are summarized in the following table.

Directive Order Cleanup Registers
register Left-to-right Function Yes
pascal Left-to-right Function No
cdecl Right-to-left Caller No
stdcall Right-to-left Function No

The register convention is by far the most efficient, since it often
avoids the creation of a stack frame. The pascal and cdecl conventions
are mostly useful for calling routines in dynamic-link libraries written
in C, C++, or other languages. The stdcall convention is used for calling
Windows API routines.


Some programming languages or programs granting access to DLLs may not offer
to choose a calling convention. In such a case, try to find out the used
method (cdecl will be a good guess to start with).

Examples:
To use the cdecl calling convention routines, use
cGetVersionNr,
cGetCallInfo and
cCheckDatabaseFormat.

To use the pascal calling convention routines, use
pGetVersionNr,
pGetCallInfo and
pCheckDatabaseFormat.



Notes:
* In the text below, all routines are referenced like "xGetVersionNr". Replace
the "x" by one of the letters "c", "p", "r" or "s", as descripted above.

* Word means 16 bit unsigned integer, SmallInt means 16 bit signed integer.


PROCEDURE xGetVersionNr(
var AVersionNr : word);

Returns in AVersionNr the current version number for the DLL. For this
DLL, the number is 8.


PROCEDURE xGetCallInfo(
ADriveInfo : pointer;
ACall : pointer;
AInfo : pointer;
var AErrorCode : SmallInt);

Returns in AInfo the information for the call given in ACall.

ADriveInfo, ACall and AInfo are pointers to zero-terminated strings. These
strings has to exist at the moment of calling xGetCallInfo. The calling
program is responsible for creating them. AInfo must be long enough to
comfort xGetCallInfo (at least 400 characters).
Note: "Length of AInfo" refers to the length of the string AInfo points at.
ADriveInfo and ACall are treated in the same manner for short.

In ADriveInfo the procedure expects the path to the CD ROM drive. Use
"G:\"
if "G:" designates the CD ROM drive with the callbook CD ROM.
Keep in mind that this information is a *must* and the calling program
has to know it.
Note: If the active directory on drive G: is not the root, ADriveInfo = "G:"
will lead to an error 3. So always use "G:\".
The calling program has to ensure that the length of ADriveInfo does not
exceed 80 characters.

ACall contains the call you are looking for, all letters in lower case,
no additional spaces etc. The calling program has to ensure that ACall is
not longer than 15 characters. However, there is no call longer than 6
characters in the database.

In AErrorCode, xGetCallInfo delivers you an information about the success
of the search. For a successful search (ACall have been found) it is
zero. All other values indicate an error. Some meanings of AErrorCode:

-5: Internal error
-4: Decode error
-3: Wrong CD: DLL does not match the CD inserted- ask for a new DLL
-2: ACall or AInfo having strange values (i.e. nil, or ACall is empty)
2: File not found
3: Path not found
5: File access denied
1101: ACall is not in the database.
32000: Error allocating memory

xGetCallInfo delivers the data of a successful search in AInfo. For
AErrorCode <> 0, it is undefined.
In AInfo, the information is structured in fields.

An ascii null indicates the end of the record. The field deliminators
are always added, so an empty field should look like this: ...#7#8...
(#7 means ascii character 7).


PROCEDURE xCheckDatabaseFormat(
ADriveInfo : pointer;
var AResult : word;
var AErrorCode : SmallInt); export;

Resturns in AResult, whether this DLL will work with the CD ROM specified
in ADriveInfo.

ADriveInfo and AErrorCode are used in the same manner as in xGetCallInfo.
Like in xGetCallInfo, AResult is undefined for AErrorCode <> 0.
List of error codes is given in the documentation of xGetCall.

Values the routines return in AResult:
0: ok.
1: Wrong database format detected. Ask for a new DLL. Usage of
xGetCallInfo will then lead to an error.



PROGRAM DLLDemo

The program DLLDemo demonstrates the usage of the DLL and the
structure of AInfo. The sourcecode (Delphi 2.0) of DLLDemo (DLLDemo.dpr)
is on the CD, too.