Calling procedures in DLLs

DLLs or Dynamic-link libraries are used extensively by engineers to access functions and subroutines located there. There are two main ways that BlueZone Basic can be extended:

call functions and subroutines in DLLs
call functions and subroutines located in the calling application

The mechanisms used for calling procedures in either place are similar.

Refer to the Declare statement for more details.

To declare a DLL procedure, or a procedure located in your calling application, place a declare statement in your declares file or outside the code area. All declarations in BlueZone Basic are Global to the run and accessible by all subroutines and functions. If the procedure does not return a value, declare it as a subroutine. If the procedure does have a return value, declare it as a function.

Example:

Declare Function GetPrivateProfileString Lib "Kernel32" _ 
(ByVal lpApplicationName As String, _ 
ByVal lpKeyName As String, ByVal lpDefault As String, _ 
		ByVal lpReturnedString As String, ByVal nSize _ 
As Integer, ByVal lpFileName As String) As Integer

Declare Sub InvertRect Lib “User” (ByVal hDC AS Integer, aRect As Rectangle)

In the above example, notice the use of the line extension character (_) the underscore. If a piece of code is too long to fit on one line, a line extension character can be used when needed.

Once a procedure is declared, you can call it just as you would any other BlueZone Basic function.

Important: BlueZone Basic cannot verify that you are passing correct values to a DLL procedure. If you pass incorrect values, the procedure can fail.

Passing and returning strings

BlueZone Basic maintains variable-length strings internally as BSTRs. BSTRs are defined in the OLE header files as OLECHAR FAR *. An OLECHAR is a UNICODE character in 32-bit OLE and an ANSI character in 16-bit OLE. A BSTR can contain NULL values because a length is also maintained with the BSTR. BSTRs are also NULL terminated so they can be treated as an LPSTR. Currently this length is stored immediately prior to the string. This may change in the future, however, so you should use the OLE APIs to access the string length.

You can pass a string from BlueZone Basic to a DLL in one of two ways. You can pass it "by value" (ByVal) or "by reference". When you pass a string ByVal, BlueZone Basic passes a pointer to the beginning of the string data (that is, it passes a BSTR). When a string is passed by reference, BlueZone Basic passes a pointer to a pointer to the string data (that is, it passes a BSTR *).

OLE API

SysAllocString/SysAllocStringLen

SysFreeString

SysStringLen

SysReAllocStringLen

SysReAllocString

Note: The BSTR is a pointer to the string; you do not need to dereference it.