Using external functions or procedures

 

The first step in using external code blocks is declaring the function you want to use. Free Pascal supports Delphi syntax, i.e. you must use the external directive. The external directive replaces, in effect, the code block of the function. As such, It cannot be used in an interface section of a unit, but must always reside in the implementation section.

There exist four variants of the external direcive :

1. A simple external declaration:

   Procedure ProcName (Args : TPRocArgs); external;

   The external directive tells the compiler that the function resides in an external block of code. You can use this together with the {$L } or {$LinkLib } directives to link to a function or procedure in a library or external object file.
2. You can give the external directive a library name as an argument:

   Procedure ProcName (Args : TPRocArgs); external 'Name';

   This tells the compiler that the procedure resides in a library with name 'Name'. This method is equivalent to the following:

   Procedure ProcName (Args : TPRocArgs);external;
   {$LinkLib 'Name'}

3. The external can also be used with two arguments:

   Procedure ProcName (Args : TPRocArgs); external 'Name'
                                          name 'OtherProcName';

   This has the same meaning as the previous declaration, only the compiler will use the name 'OtherProcName' when linking to the library. This can be used to give different names to procedures and functions in an external library.

   This method is equivalent to the following code:

   Procedure OtherProcName (Args : TProcArgs); external;
   {$LinkLib 'Name'}
   
   Procedure ProcName (Args : TPRocArgs);
   
   begin
     OtherProcName (Args);
   end;

4. Lastly, onder WINDOWS and OS/2, there is a fourth possibility to specify an external function: In .DLL files, functionas also have a unique number (their index). It is possible to refer to these fuctions using their index:

   Procedure ProcName (Args : TPRocArgs); external 'Name' Index SomeIndex;

   This tells the compiler that the procedure ProcName resides in a dynamic link library, with index SomeIndex.

   Remark: Note that this is ONLY available under WINDOWS and OS/2.

In earlier versions of the Free Pascal compiler, the following construct was also possible :

Procedure ProcName (Args : TPRocArgs); [ C ];

This method is equivalent to the following statement:

Procedure ProcName (Args : TPRocArgs); cdecl; external;

However, the [ C ] directive is no longer supported as of version 0.99.5 of Free Pascal, therefore you should use the external directive, with the cdecl directive, if needed.