Scripting Language Elements

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, one way is to call functions and subroutines in DLLs and the other way is to call functions and subroutines located in the calling application.  The mechanisms used for calling procedures in either place are similar.

SEE  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.

    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)

NOTE  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.

CAUTION  It is important to note that BlueZone Basic cannot verify that you are passing correct values to a DLL procedure.  If you pass incorrect values, the procedure may 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 (i.e. it passes a BSTR).  When a string is passed by reference, BlueZone Basic passes a pointer to a pointer to the string data (i.e. it passes a BSTR *).

OLE API

SysAllocString/SysAllocStringLen

SysAllocString/SysAllocStringLen

SysFreeString

SysStringLen

SysReAllocStringLen

SysReAllocString

NOTE  The BSTR is a pointer to the string, so you don't need to dereference it.