Lotusscript and Windows APIs

Did you know that Lotusscript supports Windows APIs?  Windows APIs are routines that provide access to commonly used lower-level Windows functionality.  There are literally thousands of APIs that provide almost all of the functionality available through Windows.  For example, you could change the caption of a window using an API, you could add a printer to the list of available printers or you could complete many other tasks that cannot be achieved through Lotusscript alone.  Windows APIs are contained in DLL files that are installed when Windows is installed - so they will work on all Windows machines without any additional file installation required.

So, how do you import API functionality into your Lotusscript agent?  You use the Lotusscript Declare keyword. The Declare keyword tells the Lotusscript compiler that a subroutine is not defined in Lotusscript but can instead be found in an external DLL file.

The best way to demonstrate the use of this keyword is by example.  We will create a Lotusscript agent that flashes the foreground window on your desktop - something that cannot be achieved through Lotusscript alone.

In the Declarations section of your agent, enter the following code:

Declare Private Function GetForegroundWindow Lib "user32.dll" () As Long

This declaration imports the GetForegroundWindow API.  This API retrieves the handle to the desk-top foreground window (usually the active window on the desk-top).  A window handle is a unique number identifying a specific window to the Windows operating system.  The declaration tells the compiler that this API can be found in the user32.dll file.  It also tells the compiler that the API returns a value of type Long.  It is important to note that API names are case-sensitive - so, getforegroundwindow is not the same as GetForegroundWindow.

On the next line of the Declarations section of your agent, enter the following code:

Declare Private Function FlashWindow Lib "user32.dll" (Byval hwnd As Long, Byval bInvert As Long) As Long

This declaration imports a second API - FlashWindow.  As with the GetForegroundWindow API, it is  found in the user32.dll file and returns a Long variable.  However, unlike GetForegroundWindow, the FlashWindow API expects two parameters - hwnd and bInvert.  The Declare statement tells Lotusscript what parameters an API expects and the variable type of the parameters.  The purpose of these parameters for this particular API is discussed below.

Now that we have successfully told the Lotusscript compiler about the APIs we will be using, we can write the Lotusscript to call them.  In the Initialize section of your agent, enter the following code:

Dim hWnd As Long

hWnd = GetForegroundWindow()

Call FlashWindow(hWnd, 1)

The first line of code,

hWnd = GetForegroundWindow()

retrieves the handle to the desk-top foreground Window.

The second line of code,

Call FlashWindow(hWnd, 1)

actually causes the window to flash. The first argument (hwnd) is the handle of the window we wish to flash. The second argument (bInvert) is 0 if we want a window to stop flashing, or non-zero if we want a window to start flashing.

Save the agent, then run it.  You will see in the taskbar of Windows the tab for the active window flash. 
This basic structure can be followed for all Windows APIs - and there are thousands of them. They can be used to cleverly extend Lotusscript agents to perform functionality well beyond its standard limitations.