The Pascal compiler company

• Pascal Compiler
• Web Programming
• About Irie Tools

As an extension to Standard Pascal, Irie Pascal supports calling functions and procedures in Windows DLLs, using the external directive. NOTE: Only 32-bit DLLs are currently supported.

A number of include files, with declarations for many of the Windows API functions, are distributed with Irie Pascal. You can use these include files to gain access to many pre-written declarations of Windows API functions without having to create your own declarations for these functions.

However if you decide to create your own declarations for external functions and procedures, you will need to understand a little bit about the calling convention used by Windows DLLs. Windows DLLs support two calling conventions, "stdcall" and "cdecl". The most popular calling convention is "stdcall".

By default Irie Pascal will assume that the calling convention is "stdcall" unless you specifiy "cdecl".

Unfortunately, calling conventions are not implemented in exactly the same way by all Windows compilers. So if you want to call a function or procedures in a DLL, you not only need to know the calling convention it uses, you may need to know which compiler was used to create it (and also what compiler options were used).

This document does not describe the various ways different compilers implement the "stdcall" and "cdecl" calling conventions. Instead what this document does is describe how Irie Pascal implements these conventions.

Details of how Irie Pascal calls external functions/procedures

How Irie Pascal stores values

First the simple types:

• byte - unsigned 8-bit value.
• char - unigned 8-bit value.
• double - 64-bit floating point value (see ANSI/IEC std 754-1985).
• enumerated (including boolean) - signed 32-bit value.
• integer - signed 32-bit value.
• real - 64-bit floating point value (see ANSI/IEC std 754-1985).
• shortint - signed 16-bit value.
• shortword - unsigned 16-bit value.
• single - 32-bit floating point value (see ANSI/IEC std 754-1985).
• word - unsigned 32-bit value.
• subrange - subrange types are stored like their host types (e.g. subranges of char are stored like chars, and subranges of integer are stored like integers).

• array - These are contiguous sequences of the elements. For example

     array[1..4] of integer

  is simply a sequence of 4 integers (with no gaps in between). Multi-demensional arrays are treated as follows:

     array[m][n][o][p] of type

  is treated like

     array[m] of array[n] of array[o] of array[p] of type.

  NOTE: This is the opposite of the way dimensions are ordered by C language compilers.

• address - This is a 32-bit value which is an operating system address (i.e. an address that is meaningful to external functions and procedures).
• cstring - These are null terminated sequences of characters (the same format used by C programs. to store strings.
• pointer - This is a 32-bit value which is a virtual address (i.e. an offset from the beginning of the IVM Executable's Data segment). Virtual address are probably meanless to external functions and procedures and therefore you should use the built-in function addr to convert virtual addresses into operating system addresses before passing them to external functions or procedures.
• record - These are simply sequences of the fields. The size of the gaps (if any) between fields is determined by the size of the fields and the current alignment setting.
• string - These are length prefixed sequences of characters. Strings with maximum lengths less than or equal to 255 are prefixed by a byte containing the actual length of the string. String with maximun lengths greater than or equal to 256 are prefixed by an integer containing the actual length of the string. NOTE: This representation is typical of the way strings are represented in Pascal programs, but is very different from the way way strings are repesented in C programs (i.e. null terminated sequences of char).
•  The other types (such as file and list) are not described here because they can not be passed to or from external functions or procedures.

Converting between C types and Irie Pascal types

NOTE: The C types in all capitals like BOOL, WORD, and DWORD are not actually defined as part of the C language, but are common types declared in C programs.

Using BOOL Parameters

The C languages does not define a boolean type so it is common for C programs to define one, however there are two popular ways this can be done. One way is to define the boolean type as char or unsigned char, in which case the nearest Irie Pascal type is byte. The other common way to define the boolean type is as a enumerated type with the values FALSE, and TRUE. However sometimes C compilers treat enumerated types with less than 256 elements as unsigned char, and at other times as int (the C name for the integer type). So if boolean type is defined as an enumerated type then it can either be treated as unsigned char, in which case the nearest Irie Pascal type is byte, or as int, in which case the nearest Irie Pascal type is boolean.

Using int And long Parameters

With most C compilers, the types int and long are signed 32-bit integral types so the nearest Irie Pascal type is integer.

Using DWORD, unsigned int And unsigned long Parameters

With most C compilers, the types DWORD, unsigned int, and unsigned long are unsigned 32-bit integral types so the nearest Irie Pascal type is word.

Using short Parameters

With most C compilers, the type short is a signed 16-bit integral type so the nearest Irie Pascal type is shortint.

Using unsigned short Parameters

With most C compilers, the type unsigned short is a unsigned 16-bit integral type so the nearest Irie Pascal type is shortword.

Using Array Parameters

Passing multi-dimensional arrays between Irie Pascal and C requires care since the ordering used by Pascal and C for the dimensions is opposite (i.e.

   a : array[1..4][1..2] of integer;

is equivalent to

   int a[2][4];

Using pointer Parameters

1. The C language does not support call by reference (only call by value). So when you pass an argument to a C function, a copy of the argument is passed. The function can modify the copy of the argument but the modifications are not visible to the caller, because the caller is using the argument itself and not the copy.

   This can be a problem if the function has to return more than one value. C programs commonly solve this problem by passing a pointer to the argument instead of the argument itself. The function will receive a copy of the pointer, but because the copy points at the argument the C function can modify the argument my modifying what the pointer is pointing to.

   Internally, Irie Pascal implements call be reference in the same way, so you can use call by reference in cases where the C function expects a pointer to a variable.

2. The C language also does not support passing arrays to functions, however the close relationship between arrays and pointers in C means that passing a pointer to the first element in an array is almost equivalent to passing the array. Irie Pascal supports passing arrays, so in this case you should pass an array by reference to the C function or procedure.
3. A special case of passing arrays, is passing C strings (arrays of null-terminated chars). In this case you may want to pass a cstring by reference.
4. In cases where the pointer is pointing to a variable whose type is not fixed, or a null value can be passed, or the pointer is pointing to a variable whose size is not fixed then you may want to pass the operating system address of the variable directly.

The sample program winhello.pas is an example of how to call a function in a Windows DLL. NOTE: This program uses the winuser.inc include file, distributed with Irie Pascal, to gain access to a pre-written declaration for the Windows API function MessageBox.