External Functions Section

This section lists all functions that are available through dynamic link libraries. All external functions declared in a dynamic link library that are called from the script must be declared before they are used. Use the keyword dll.

Syntax

DllDecl       = "dll" DllName Prototype { Prototype }.

Prototype     = ExtFuncName [ @deprecated [ "(" NewFuncName  ")" ] ] "function" FuncName
                [ "(" ParamList ")" ] [ ":" RetType ].

ParamList     = ParamDecl { "," ParamDecl }.

ParamDecl     = [ ParamName ":" ] [ PassMode ]
                ( BDL_Type | C_Type ) { ParamModifier }.

PassMode      = "in" | "inout" | "out".

ParamModifier = "allownull" | "explicit" | 
                  "lenspec" | "sizespec" |
                  "optional"[":=" (signum | float | boolean | ident)].

BDL_Type      = "number" | "float" | "string" | "boolean" | "list".

C_Type        = "ptr" | "dstring" | "union" | "long" |
                "short" | "char" | "unsigned short" |
                "unsigned char" | "double".

RetType       = "number" | "float" | "string" |
                "dstring" | "boolean" | "long" |
                "short" | "char" | "unsigned short" |
                "unsigned char" | "double".
Section Description
DllName A constant string that specifies the name of the DLL file that contains the function(s) you want to call
Prototype The definition of the function prototype of a DLL function you want to call
ExtFuncName A constant string that specifies the name of the function as used inside the DLL (case-sensitive)
FuncName An identifier that specifies the name of the function as used inside the BDL script (case-insensitive)
ParamName An identifier that specifies the name of the parameter (optional).
PassMode Indicates whether the parameter is passed into the function by reference (out and inout) or by value (in). The default is in. (Optional)
C_Type The data type of a function parameter specified using C data types
BDL_Type The data type of a parameter of a function using BDL data types. The BDL data types correspond to the C data types in the table below
RetType The data type of the return value of the function using BDL data types or C data types, explained in the table below
BDL data type C data type Description
number long BDL data type number represents a 4-byte signed integer value
float double BDL data type float represents an 8-byte floating point value
string char* BDL data type string represents a null terminated character string value
boolean long BDL data type boolean represents a 4-byte integer value where 1 represents true and 0 represents false

The following table shows valid data type combinations between actual parameters (BDL data types) and formal parameters of external functions using C data types.

Actual BDL parameter type Formal BDL parameter type Formal C/C++ parameter type Internal Type (accessible via rtPlugInLib.lib)
number char char TByte1
number unsigned, char unsigned, char TUByte1
number short short TByte2
number unsigned, short unsigned, short TUByte2
number number, long long TByte4
number number, long unsigned, long TUByte4
number number, long, ptr void* TPointer
float float float Real4
float double double Real8
string, in <number> string char* TString
string, in <number> ptr void* TPointer
string, in <number> dstring void* CBdlStr*
boolean boolean int TBool
boolean, number, float, string, boolean[], number[], float[], string[] union void* CBdlUnion*
Note: If you use ptr as data type for your external function, the compiler does not perform a type check between actual and formal parameters. Actual parameters of type number can be passed to DLL functions by reference (default) or by value using the ptr data type for the formal parameter. To pass an argument by value, preface the argument with the in keyword in the call to the DLL function.
Note: Functions marked with @deprecated issue a warning during compiling and highlight the new function to use instead.

Example

dll "odbc32.dll" 
  "SQLConnect"
    function SqlConnect(in number, in string, in number,
                        in string, in number,
                        in string, in number): short;

dll "testdll.dll"
  "MyStrlen"
    function StrLen(inout string): number;

dcltrans
  transaction TConnect
  const
    SQL_NTS := -3;
  var
    hdbc, retcode : number;
    dsn_name : string;
  begin
    dsn_name := "dsn_sample";
    retcode := SqlConnect(hdbc, dsn_name, SQL_NTS, "u1",
    SQL_NTS, "u1", SQL_NTS);
  end TConnect;