Table of Contents

Calling DLL functions

Scripts can call functions exported by DLLs (dynamic link libraries), like the functions of the Windows API or of DLLs of your own. The script declares each function with its parameters and result types, the name of the DLL and, optionally, the calling convention and the name of the function in the DLL. Then the script calls the function like any other routine.

function MessageBox(hwnd: pointer; text, caption: string; msgtype: integer): integer;
  stdcall; external 'user32.dll' name 'MessageBoxW';

begin
  MessageBox(nil, 'Hello from a DLL', 'Script', 0);
end;

DLL calls are available on Windows only.

Note

DLL calls must be enabled by the application: set TatCustomScripter.​Allow​DLLCalls to True. Otherwise a script that calls a DLL function stops with the error "DLL calls not allowed in scripter".

The DLL is loaded when the script calls one of its functions for the first time. The LoadLibrary and FreeLibrary functions of the Windows library, when the application provides it, load and unload a DLL explicitly. If the DLL or the function cannot be found, the call is an error.

Pascal syntax

function Name(Parameters): ResultType; [CallingConvention;] external 'Library.dll' [name 'EntryName'];
procedure Name(Parameters); [CallingConvention;] external 'Library.dll' [name 'EntryName'];
  • CallingConvention is stdcall, cdecl, register, pascal or safecall. The default is register. Windows API functions use stdcall.
  • name gives the name of the function in the DLL, when it differs from the name used in the script. Without it, the function has the same name in the script and in the DLL.
  • Parameters passed by reference are declared with var.
function GetDiskFreeSpace(root: string; var sectorsPerCluster, bytesPerSector,
  freeClusters, totalClusters: integer): boolean;
  stdcall; external 'kernel32.dll' name 'GetDiskFreeSpaceW';

function Average(x, y: double): double; external 'MyLib.dll';

Basic syntax

Function Name Lib "Library.dll" [Alias "EntryName"] [CallingConvention] (Parameters) As ResultType
Sub Name Lib "Library.dll" [Alias "EntryName"] [CallingConvention] (Parameters)
  • CallingConvention is stdcall, cdecl, register, pascal or safecall. The default is stdcall, the calling convention of the Windows API.
  • Alias gives the name of the function in the DLL, when it differs from the name used in the script.
  • Parameters are declared with As Type; parameters passed by reference are declared with ByRef. A routine without parameters has no parentheses.
Function MessageBox Lib "user32.dll" Alias "MessageBoxW" (hwnd As pointer, text As string, caption As string, msgtype As integer) As integer

Function GetTickCount Lib "kernel32.dll" As integer

Sub SetLastError Lib "kernel32.dll" (code As integer)

JavaScript syntax

function name(parameters): resultType [callingConvention] external "Library.dll" [name "EntryName"];
  • Parameters are declared with their types, name: type, and parameters passed by reference with var name: type. Types are only allowed in DLL function declarations.
  • Without a result type, the function has no result (a procedure).
  • callingConvention is stdcall, cdecl, register, pascal or safecall. The default is stdcall, the calling convention of the Windows API.
  • name gives the name of the function in the DLL, when it differs from the name used in the script.
  • The declaration can span several lines; the final semicolon is optional. Like other functions, DLL functions can be called before their declaration.
function MessageBox(hwnd: pointer, text: string, caption: string, msgtype: integer): integer
  external "user32.dll" name "MessageBoxW";

function GetDiskFreeSpace(root: string, var sectorsPerCluster: integer,
  var bytesPerSector: integer, var freeClusters: integer, var totalClusters: integer): boolean
  external "kernel32.dll" name "GetDiskFreeSpaceW";

function CAbs(x: integer): integer cdecl external "msvcrt.dll" name "abs";

function SetLastError(code: integer) external "kernel32.dll";

Supported types

The types of the parameters and results tell how the values are passed to the DLL. These types are supported, as values and by reference:

Script type Passed as
integer, longint, cardinal, longword 32-bit integer
int64 64-bit integer
smallint, word, shortint, byte 16-bit and 8-bit integers
boolean Boolean
single, double, real, extended, comp, currency Floating-point and currency values
tdatetime Date and time (a double)
string Pointer to a Unicode (UTF-16) string, for functions with W names and PWideChar parameters
ansistring Pointer to an ANSI string, for functions with A names and PAnsiChar parameters
pchar, pwidechar Pointer to a Unicode string
pansichar Pointer to an ANSI string
widestring, shortstring Delphi string types
char, widechar Single character
pointer Pointer value (nil, Nothing or null for a null pointer)
variant, interface Variant and interface values
tobject, or a class name Object

Records and arrays are not supported. A type name is not case-sensitive.

The DLL must be compiled for the same platform as the application (32-bit or 64-bit). On 64-bit Windows, all calling conventions are the same.