Datatypes for external function arguments
When you declare an external function in PowerBuilder, the
datatypes of the arguments must correspond with the datatypes as
declared in the function’s source definition. This section documents the
correspondence between datatypes in external functions and datatypes in
PowerBuilder. It also includes information on byte alignment when
passing structures by value.
Use the tables to find out what PowerBuilder datatype to use in an
external function declaration. The PowerBuilder datatype you select
depends on the datatype in the source code for the function. The first
column lists datatypes in source code. The second column describes the
datatype so you know exactly what it is. The third column lists the
PowerBuilder datatype you should use in the external function
declaration.
Boolean
BOOL and Boolean on Windows are 16-bit, signed. Both are declared
in PowerBuilder as boolean.
Pointers
|
Datatype in source code |
Size, sign, precision |
PowerBuilder datatype |
|---|---|---|
|
* (any pointer) |
32-bit pointer |
Long |
|
char * |
Array of bytes of variable length |
Blob |
Windows 32-bit FAR pointers, such as LPBYTE, LPDWORD, LPINT,
LPLONG, LPVOID, and LPWORD, are declared in PowerBuilder as long
datatypes. HANDLE is defined as 32 bits unsigned and is declared in
PowerBuilder as an UnsignedLong.
Near-pointer datatypes (such as PSTR and NPSTR) are not supported
in PowerBuilder.
Characters and strings
|
Datatype in source code |
Size, sign, precision |
PowerBuilder datatype |
|---|---|---|
|
char |
8 bits, signed |
Char |
|
string |
32-bit pointer to a null-terminated array of bytes |
String |
The Windows 32-bit FAR pointer LPSTR is declared in PowerBuilder
as string.
Reference arguments
When you pass a string to an external function by reference, all
memory management is done in PowerBuilder. The string variable must be
long enough to hold the returned value. To ensure that this is true,
first declare the string variable, and then use the Space function to
fill the variable with blanks equal to the maximum number of
characters that you expect the function to return.
Fixed-point values
|
Datatype in source code |
Size, sign, precision |
PowerBuilder datatype |
|---|---|---|
|
byte |
8 bits, unsigned |
Byte |
|
short |
16 bits, signed |
Integer |
|
unsigned short |
16 bits, unsigned |
UnsignedInteger |
|
int |
32 bits, signed |
Long |
|
unsigned int |
32 bits, unsigned |
UnsignedLong |
|
long |
32 bits, signed |
Long |
|
unsigned long |
32 bits, unsigned |
UnsignedLong |
|
longlong |
64 bits, signed |
LongLong |
The Windows definition WORD is declared in PowerBuilder as
UnsignedInteger and the Windows definition DWORD is declared as an
UnsignedLong. You cannot call external functions with return values or
arguments of type short.
Floating-point values
|
Datatype in source code |
Size, sign, precision |
PowerBuilder datatype |
|---|---|---|
|
float |
32 bits, single precision |
Real |
|
double |
64 bits, double precision |
Double |
PowerBuilder does not support 80-bit doubles on Windows.
Date and time
The PowerBuilder datatypes Date, DateTime, and Time are structures
and have no direct equivalent for external functions in C.
Passing structures by
value
You can pass PowerBuilder structures to external C functions if
they have the same definitions and alignment as the structure’s
components. The DLL or shared library must be compiled using byte
alignment; no padding is added to align fields within the
structure.
Using 1-byte structure member alignment in
external function
When you use a structure or structure array as parameters to
external function in the older versions of PowerBuilder, the structure
member alignment was one byte. However, the default alignment is 8 bytes
on Windows platform, which means that most (if not all) Windows standard
APIs use this value to align arguments with structure members. This will
cause a mismatch between Windows APIs and PB applications in
PowerBuilder 12.5 and earlier versions. A well adopted solution to this
issue was to add some bytes within PowerBuilder structures manually to
fill those gaps. Such gap filling can be complex and error-prone if
involving complex nested structures. And what is worse, this solution
fails with the introduction of 64-bit application development in
PowerBuilder 12.6 because the number of bytes you have to fill may be
different between 64-bit and 32-bit applications. This was the major
reason to make this change in PowerBuilder 12.6. With PowerBuilder 12.6
for Windows API and Visual C++ the default structure member alignment is
now 8 bytes. The structure member alignment was changed to 8 bytes in
PowerBuilder 12.6 for both 64-bit and 32-bit applications. This was an
intentional change. Customers can now call Windows API easier and use
the same code for both 64-bit and 32-bit applications.
Customers can switch to the old behavior in two ways with
PowerBuilder 12.6 build 4058 and above.
1. Check “Use 1-byte structure member alignment in external
function” (or set UseZp1=1 in [pb] section, pb.ini, the results are the
same). The effect is global with this setting changed. To make this work
at runtime, please remember to deploy your pb.ini file with your
application.
2. Add “progma_pack(1)” external function’s declaration, like
this:
FUNCTION int STLAREGIO ( ref struc_kfzrechnerneu struc_kfz )
LIBRARY “KFZ_SS.DLL” alias for “STLAREGIO;Ansi” progma_pack(1)
progma_pack(1) is 1-byte align, progma_pack(8) is 8-bytes align.
In this way, the effect is only for external function that is declared
with this alignment.