The tens of thousands of function calls in the Windows environment can be helpful to PowerBuilder users, but documenting them is nearly impossible. After hundreds of user inquiries, Powersoft Technical Support compiled these technical tips to enable PowerBuilder developers to translate standard Microsoft function calls into PowerBuilder syntax, and to empower developers to use any of the external API calls within their owerBuilder environments..

The following information will help you translate and Windows SDK call to a PowerBuilder API function call. It doesn't matter whether you're using PowerBuilder 4.0, 5.0, 6.0, 7.0 or 8.0 but there are important differences between the 16- and 32-bit versions, as we'll discuss below.

Step 1: Converting an SDK Call to a PowerBuilder API Call.

First you need to get the syntax that wil be converted. This can be obtained from either a Windows API Bible or the MSDN (Microsoft Developers Network).

Step 2: Determining Whether it is a Function or a Subroutine.

Function calls return a value; subroutines do not.

Here is an example of a Microsoft function:

BOOL GetFileVersionInfo( LPTSTR lptstrFilename, DWORD dwHandle, DWORD dwLen, LPVOID lpData );

Here is an example of a Microsoft subroutine:

VOID GlobalMemoryStatus(LPMEMORYSTATUS lpBuffer);

Step 3: Converting the datatypes from Microsoft to PowerBuilder. MICROSOFT

PB(16Bit) PB(32Bit) Bool Boolean Boolean Char* Ref string Ref String Colorref Uint Ulong Dword Uint Ulong Handle Uint Ulong Hdc Uint Ulong Hfile Uint Ulong Hinstance Uint Ulong Hwnd Uint Ulong Int Int Int Lparam Uint Ulong Lpbyte Ref Int Ref Long Lpdword Ref Uint Ref Ulong Lpfiletime Ref Time Ref Time Lpint Ref Int Ref Long Lpstr,Lpststr Ref String Ref String Lpvoid Ref Structstruct_inst Ref Struct struct_inst Mcierror Long Long Lpstr,Lpststr Ref String Ref String Lpvoid Ref Structstruct_inst Ref Struct struct_inst Pbyte Ref Int[#] Ref Long[#] Short Int Int Structure Ref Struct struct_inst Ref Struct Struct_inst Uint Uint Uint Void** SUBROUTINE SUBROUTINE Word Int Ulong Wparam Uint Ulong Most of the datatypes are listed above, but some may be missing. When in doubt read the datatype description first. If still unsure, it is usually safe to assume a 16 bit datatype is a "uint" and a 32 bit datatype is a "ulong", since they are the most common. *If the word "Callback appears as a datatype, it cannot be performed by PowerBuilder. Callback routines are functions that are called from within functions. Step 4: Coding the Global/Local External Function:

This is a Microsoft function:

BOOL GetFileVersionInfo( LPTSTR lptstrFilename, DWORD dwHandle, DWORD dwLen, LPVOID lpData );

The BOOL represents a boolean return code, which is translated to "Boolean" in PB for both 16 and 32 bit. A LPCTSTR means a pointer to a string (see step 3). In PowerBuilder, simply use the word "ref" before declaring the string in either 16- or 32-bit platofrms. DWORD is translated to "uint" for 16 bit and "ulong" for 32 bit. An LPVOID indicates that a structure is being used. In PowerBuilder, create a structure, assign it to an instance variable of that structure and pass it by reference. As a result, the following function declarations can be derived:

PowerBuilder 16 bit:

FUNCTION boolean GetFileVersionInfo(ref string filename, uint f_handle, uint f_length, ref lpdata lpdata2) LIBRARY "ver.dll"

PowerBuilder 32 bit:

FUNCTION boolean GetFileVersionInfoA(ref string filename, ulong f_handle, ulong f_length, ref lpdata lpdata2) LIBRARY "version.dll"

Note: In the "gotchas" section listed below, you'll get a further explanation why an "A" is appended to the 32-bit function. You'll also find a handy technique to help you locate function calls within the DLLs.

Step 5: Creating a Structure

In this particular example a structure is needed so you'll need information on what elements are contained within this structure. The MSDN provides this information since the function being called is a Windows function.

In the MSDN the structure appears like this:

LPDATA = { DWORD dwSignature ; DWORD dwStrucVersion ; DWORD dwFileVersionMS ; DWORD dwFileVersionLS ; DWORD dwProductVersionMS ; DWORD dwProductVersionLS ; DWORD dwFileFlagsMask ; DWORD dwFileFlags ; DWORD dwFileOS ; DWORD dwFileType ; DWORD dwFileSubtype ; DWORD dwFileDateMS ; DWORD dwFileDateLS }

In PB you would go into the structure painter