WINAPI

8.0.5, PLBCMP GUI or PLBLinux Only

The WINAPI instruction calls a 32 bit Dynamic-Link Library (DLL) Windows routine or a routine from a shared object library (.so) in Linux. The instruction uses the following format:

	[label]	WINAPI	{profile}[ GIVING {results}[ USING {parameters}...]]
	[label]	APICALL	{profile}[ GIVING {results}[ USING {parameters}...]]

Where:

label

Optional. A Program Execution Label.

profile

Required. The label of a PROFILE statement.

results

Optional. The name of the variable(s) to receive the return information from the called routine.

parameters

Optional. The name of any of the parameters passed to the called routine.

Flags Affected: NONE

Note the following:

APICALL is a synonym for WINAPI.
{profile} defines the various parameters to the WINAPI instruction.
If the function called is located in one of the basic Windows Dynamic-Link Library (DLL) modules, the function may be called directly. If the function is located in any other DLL, your program may first load the DLL using the 'LoadLibrary' function or the runtime will load it for you automatically. When you are finished with the DLL, you must unload it using the 'FreeLibrary' function.
NOTE: The standard Windows API functions that may be executed without having to load them are found in the Microsoft WIN32 Programmer Reference manual. Sunbelt is not responsible for indeterminate program operations due to inappropriate API function usage.
{results} is the name of the variable to receive the return information. The data type must match the information in the PROFILE statement.
{parameters} is the name of any of the parameters passed. The actual variable type must match the information in the PROFILE statement.
If a parameter is defined as a DIM variable and this parameter is modified by the call, it us up to the user to make sure the variable is large enough to hold all of the information returned. The Form Pointer is set to one (1) and the Length Pointer is set to the number of bytes returned.
A null parameter may be specified by using the *NULL keyword or by simply omitting the parameter in the list.
When using WINAPI in a PLBCLIENT/PLBSERVE application, the pDIM parameter type should be used in the PROFILE when remote data is retrieved from the client workstation into a function parameter. The Formpointer (FP) and Lengthpointer (LP) are both set to zero for the data returned into the function parameter when the ‘pDIM’ declaration is used. This is a noted/identified difference in the process/handling of PDIM declared item(s) in a PLBCLIENT/PLBSERVE environment for example executing in Linux using ‘plb’ versus a DIM declared item(s) used in WINDOWS using ‘plbwin’.
It is up to you to make sure that any DIM variables that are passed are properly terminated (ASCIIZ or UNICODE).
Null entries may be passed to the function by placing back to back commas in the argument list.
The WINAPI instruction does not support any function that requires callbacks.
WINAPI support is provided with PLBCE. The OS dll name for most functions is "COREDLL" instead of "KERNEL32" or "USER32".
When executing on a client that is connected to Linux/Linux server, use an exclamation mark (!) at the beginning of the function name in the PROFILE statement to signify that the DLL resides on the client rather than the server.
When using a PL/B Web Server, the WINAPI executes an API function as normally expected for any OS library functions (i.e., DLL or .so ) using all PL/B runtimes. However, if the PROFILE specified the '!JS' library type, a WINAPI using this PROFILE can only be executed using a PL/B Web Server.
When executing a WINAPI using the PL/B Web Server to execute a JavaScript function, all WINAPI DIM\PDIM parameter data must be formatted as valid JavaScript parameter(s) or unexpected JavaScript errors or behaviors can occur. See the following link for information on JavaScript function parameters:

http://www.w3schools.com/js/js_function_parameters.asp

When executing a WINAPI using the PL/B Web Server to execute a JavaScript function, only the logical length of any input DIM or PDIM variable is used. If the DIM\PDIM variable is NULL, no data is used for the WINAPI input parameter.