Examples

This section provides you with several code samples that illustrate the difference between DLL functions, and different ways to pass a reference to a pointer.

Example 1: DLL Function Returning a VOID vs. a Subroutine.

A DLL function that returns a VOID type is considered a subroutine. Conversely, a function returning anything else is considered a function. In the following example, ShowWindow is a subroutine that will change the display mode of a window (minimized, maximized, normal, etc.); FindWindow() is a function that will return the handle of a given window.

Declare Subroutine ShowWindow
Declare Function FindWindow

Note that the DLL functions are called in the same way as other BASIC+ functions or subroutines.

Example 2: Calling a DLL Function in a Window Event

The following code is associated with the CLICK event of a button.

Declare Subroutine ShowWindow
Equ HIDE$ To 0
Equ NORMAL$ To 1
Equ MINIMIZE$ To 2
Equ MAXIMIZE$ To 3
hWnd = Get_Property(@WINDOW, "HANDLE")
ShowWindow(hWnd, MINIMIZE$)
Return 0

Example 3: Choosing a Pointer Parameter Type.

The manner in which you prototype a function determines the way that you pass the reference to the pointer. There are two ways to pass the reference to the pointer:

Pass a variable and allow OpenInsight to determine the correct parameter type. Or,
Get the reference and pass it in yourself.

You must remain consistent in the manner in which you prototype your functions. If you set up the prototype so that you pass a variable, then you must always pass the variable. If you set up the prototype so that you pass the reference yourself, then you must always pass the reference.

Example 4: Passing a Variable to BASIC+:

Declare your variable type in the function prototype as LP<type> (where <type> is the type of variable that you are passing).

For example, if you are passing a pointer to a SHORT integer, the parameter is LPSHORT. In your program, pass a variable that contains a short integer (a two byte structure).

If the DLL requires a pointer to an allocated memory area, you must size the variable prior to the call. To do so, use the Str() function. For example, if you were passing a LONG (a 4 byte structure), your code would look something like this:

Subroutine Test(param)
Declare Subroutine MY_DLLFUNC
......
......
Var = Str(Char(0), 4 )
MY_DLLFUNC(Var, ...)
Return

Example 5: Passing the Reference

To pass the reference, declare the parameter as LPVOID in the function prototype. LPVOID assumes that you are passing in a long integer that is a far pointer to any arbitrary data.

To get reference to OpenInsight data, use the BASIC + functions LockVariable and GetPointer. The following code sample illustrates the use of these functions.

Subroutine Test(Param)
Declare Subroutine MY_DLLFUNC
.....
/* Locks the variable in a memory location. */
LockVariable Var as Char

/* Returns a 4 byte long integer that points to the location of variable Var. */
lprefdata = GetPointer(Var)

MY_DLLFUNC(Var)

/* The GetValue function de-references the pointer after the call. Note that the second parameter (Char) is not quoted. */
Length = 4
value = GetValue(Var, Char, Length)

/* Unlocks the memory area. */
UnlockVariable Var

Return