Tech Articles


PowerBuilder Equivalents to Windows API Datatypes


At some point in your PowerBuilder career, you will need to call a Windows API (or WinAPI, for short) function. The WinAPI specifications are heavily dependent on type definitions created in C/C++ via the #define preprocessor directive. The use of type defintions helps the readability of Windows code, but it unfortunately and effectively hides the actual underlying datatype - making it difficult for you to correctly code the PowerBuilder external function declaration needed to call the API function.

Some time ago I published a four-part series of PowerBuilder tutorials that explain the ins and outs of interfacting PowerBuilder apps with the Windows API, but I realize the many developers are very busy and do not have the luxury of sufficient spare time needed to read that much material. In case you are interested and have the time, I have included URLs to those tutorials at the end of this article.

This article consists of two tables. The first table lists many of the most commonly-seen WinAPI type definitions and their PowerBuilder equivalents. The second table lists the PowerBuilder datatypes and their WinAPI equivalents, if any. For your convenience, I am also providing the URLs to several useful resources you may find helpful when coding external function declarations.

Common Windows API Type Definitions to PowerBuilder Datatypes

The following table maps many of the most commonly-used WinAPI type definitions to their PowerBuilder equivalents:

WinAPI Type Definition or Datatype Equivalent PB Datatype
Comment
BOOL Boolean Boolean (True/False) value. A 4-byte integer in Windows. A 2-byte integer in PowerBuilder. PB automatically promotes/demotes the value to the appropriate datatype when it is used as an argument in an external function call.
BOOLEAN Byte Boolean (True/False) value. An 8-bit, unsigned integer. NOTE: Not the same datatype as BOOL, yet it is also used for True/False values.
BYTE Byte An 8-bit, unsigned integer.
Byte Array (block of memory Blob A block of memory is typically referenced by a pointer (the address of the first array element) in Windows.
CONST** Constant** A directive that conveys to the compiler that the value is to remain unchanged during execution. (** => NOT a datatype)
double (C/C++) Double A basic C/C++ language datatype, not a WinAPI-defined type definition.
DWORD UnsignedLong or ULong A 32-bit unsigned integer.
FLOAT Real Rarely used in WinAPI, but included here for completness.
HANDLE Longptr A generic handle (ID number) to an undetermined Windows resource.
HBITMAP Longptr A handle to a bitmap.
HBRUSH Longptr A handle to a brush.
HDC Longptr A handle to a device context.
HDROP Longptr A handle to an internal drop structure, used in drag/drop operations.
HFILE Longptr A handle to a file.
HFONT Longptr A handle to a font.
HICON Longptr A handle to an icon (you should be starting to see a pattern by now, I hope).
HINSTANCE Longptr A handle to an instance (same as HMODULE).
HMENU Longptr A handle to a menu.
HMODULE Longptr A handle to a module (same as HINSTANCE).
HMONITOR Longptr A handle to a display monitor.
HRESULT Long A return code used by COM interfaces. NOTE: This is NOT a Windows handle, although its name would imply that it contains a Windows handle.
HWND Longptr A handle to a window or a control. All controls are implemented as subclassed windows, so a handle for a control is actually a handle to a window.
INT Long A signed 32-bit integer (NOT a PowerBuilder Int, which is 16-bits long.
INT16 Integer (or Int) A signed 16-bit integer.
INT32 Long A signed 32-bit integer.
INT64 LongLong A signed 64-bit integer.
INT8 -none- A signed 8-bit integer. NOTE: The PowerBuilder Byte datatype is an unsigned 8-bit integer.
INT_PTR Longptr A signed integer (32-bit or 64-bit, depending on the process/app bitness. Used in Windows for pointer arithmetic.
LANGID Integer (or Int) A language identifier.
LONG Long A signed 32-bit integer.
LONGLONG LongLong A signed 64-bit integer.
LONG_PTR Longptr A signed integer (32-bit or 64-bit, depending on the process/app bitness. Used in Windows for pointer arithmetic.
LONG32 Long A signed 32-bit integer.
LONG64 LongLong A signed 64-bit integer.
LPARAM Longptr A Windows event message parameter.
LPCSTR Longptr A pointer to a constant, null-terminated string (array) or ANSI characters.
LPCVOID Longptr A pointer to a constant of undetermined datatype.
LPCWSTR Longptr A pointer to a constant, null-terminated string (array) of Unicode ("Wide") characters.
LPVOID Longptr A pointer to a value of undetermined datatype.
LPDWORD Longptr A pointer to a DWORD (an unsigned 32-bit integer).
LPWORD Longptr A pointer to a WORD (an unsigned 16-bit integer).
LPWSTR Longptr A pointer to a null-terminated string (array) of Unicode ("Wide") characters.
PVOID Longptr A pointer to a value of undetermined datatype.
QWORD -none- An unsigned 64-bit integer. NOTE: The PowerBuilder LongLong datatype is a signed 64-bit integer.
SHORT Integer (or Int) A signed 16-bit integer.
UINT UnsignedLong (or ULong) An unsigned 32-bit integer.
ULONG UnsignedLong (or ULong) An unsigned 32-bit integer.
ULONGLONG -none- An unsigned 64-bit integer. NOTE: The PowerBuilder LongLong datatype is a signed 64-bit integer.
USHORT UnsignedInt (or UInt) An unsigned 16-bit integer.
VOID Any A value of undetermined datatype. Means "returns no value" when describing a function's return value.
WCHAR Character (or Char) A Unicode ("Wide") character.
WORD Integer (or Int) A signed 16-bit integer.
WPARAM Longptr A Windows event message parameter.

Please be aware that WinAPI type definitions can be "nested." For example, HICON is defined as HANDLE. HANDLE is defined as PVOID. PVOID is defined as a pointer to any datatype. Therefore, HICON is a pointer, which can be either a 32-bit integer or a 64-bit integer, depending on the bitness of the application/process... and this translates to a Longptr in PowerBuilder.

Here is a URL to online documentation describing these and additional various WinAPI type definitions:

https://learn.microsoft.com/en-us/windows/win32/winprog/windows-data-types

The following URL is a staring point for documentation on Windows API functions and structures:

https://learn.microsoft.com/en-us/windows/win32/apiindex/api-index-portal

Many WinAPI functions indicate success/failure status via the function's return value. In the event of a failed call, an internal error number may be set within the Windows operating system. You can obtain this numeric error code via the GetLastError WinAPI function, but deciphering what an error code value means can be problematic. If you have Visual Studio installed, you can examing the header file named "winerror.h" to find the name of nearly all error codes, or you can instead visit the following URL:

https://learn.microsoft.com/en-us/windows/win32/debug/system-error-codes

PowerBuilder Datatypes to Windows Type Datatypes and Type Definitions

The following table maps the PowerBuilder datatypes to their WinAPI equivalents:

PowerBuilder Datatype Size (Bytes) Equivalent WinAPI Type Definition or Datatype Comment
Any 8 or 12 n/a An internal PowerBuilder structure. Its size depends on the target compilation bitness. When used in a structure object, an Any assumes the size and characteristics of the argument parameter is represents. There is no WinAPI equivalent.
Blob 4 or 8 BYTE array An array of type BYTE (i.e., a pointer), so the size depends on the target compilation bitness.
Boolean 2 BOOL BOOL is a 4-byte integer in WinAPI, but a PowerBuilder Boolean is 2 bytes. PB automatically promotes/demotes the value to the appropriate datatype when it is used as an argument in an external function call.
Character (or Char) 2 WCHAR Unicode character. "W" stands for "wide," i.e., Unicode.
Date 4 or 8 -none- A pointer to an internal PowerBuilder structure, so the size depends on the target compilation bitness. There is no WinAPI equivalent.
Datetime 4 or 8 -none- A pointer to an internal PowerBuilder structure, so the size depends on the target compilation bitness. There is no WinAPI equivalent. See the note that follows this table.
Decimal 8 -none- There is no WinAPI equivalent.
Double 8 double (C/C++)  
Integer (or Int) 2 SHORT  
Long 4 INT or Long  
LongLong 8 LONGLONG  
Longptr 4 or 8 LONG_PTR A signed 32-bit or 64-bit integers. Its size depends on the target compilation bitness.
Real 4 FLOAT Rarely used in WinAPI.
String 4 or 8 LPWSTR A null-terminated array of Unicode characters (i.e., a pointer), so the size depends on the target compilation bitness.
Time 4 or 8 -none- A pointer to an internal PowerBuilder structure, so the size depends on the target compilation bitness. There is no WinAPI equivalent.
UnsignedInteger (or UnsignedInt or UInt) 2 USHORT or WORD  
UnsignedLong (or ULong) 4 DWORD  

Note:

The SYSTEMTIME structure in the WinAPI specifies a date and time, using individual members for the month, day, year, weekday, hour, minute, second, and millisecond, which is roughly equivalent to the PowerBuilder Datetime datatype. There are no supplied functions to convert values between the two formats, but they can be created by a PB developer relatively easily.

Interfacing PowerBuilder Applications to Window API Functions

There is a series of PowerBuilder tutorials online in the Appeon Community that will help you master the intricacies of interfacing PB apps with Windows API functions. You can access this series of tutorials via the following URLs:

https://community.appeon.com/articles-blogs/tutorials-articles/2-powerbuilder/302-interfacing-pb-applications-with-the-windows-api-part-1

https://community.appeon.com/articles-blogs/tutorials-articles/2-powerbuilder/303-interfacing-pb-applications-with-the-windows-api-part-2

https://community.appeon.com/articles-blogs/tutorials-articles/2-powerbuilder/304-interfacing-pb-applications-with-the-windows-api-part-3

https://community.appeon.com/articles-blogs/tutorials-articles/2-powerbuilder/305-interfacing-pb-applications-with-the-windows-api-part-4

 

Comments (0)
There are no comments posted here yet

Find Articles by Tag

Text Elevate Conference PDF OAuth IDE ODBC Database Table Data C# Web Service Proxy Database Object Debugger ActiveX COM Resize BLOB Excel Source Code PowerScript (PS) PowerServer Web TreeView External Functions Outlook Class Branch & Merge Open Source Filter TortoiseGit Design Source Control Android Bug 32-bit SOAP RESTClient REST Migration Database Connection Visual Studio InfoMaker RibbonBar Web API Automated Testing UI Themes API DataWindow SqlExecutor Interface Windows 10 Icons Error SVN Database Table CoderObject Graph SQL Trial WebBrowser Jenkins TLS/SSL NativePDF Performance PBVM Expression Event Handling Validation Application SqlModelMapper PBDOM Database Profile SnapDevelop CrypterObject DragDrop Platform Database Painter GhostScript Syntax Testing License OrcaScript Event Handler Azure Database PBNI 64-bit Debugging Window iOS Array Database Table Schema .NET DataStore Windows OS PowerServer Mobile Git OAuth 2.0 Export SnapObjects DLL WinAPI Messagging Authentication PostgreSQL Icon TFS RichTextEdit Control Variable JSONGenerator MessageBox Sort DevOps Export JSON Mobile OLE Event XML PowerBuilder Stored Procedure UI JSON Import PDFlib Menu Configuration Import JSON PowerBuilder (Appeon) SDK Debug Transaction File Model .NET Assembly PFC PostgreSQL ODBC driver Data HTTPClient Service Linux OS .NET Std Framework DataWindow JSON CI/CD UI Modernization Authorization JSONParser RibbonBar Builder Oracle Script Encoding Repository Charts Encryption Installation Deployment PowerBuilder Compiler DataType SQL Server