How to Use a Dynamic Link Library (DLL)

How to Use a Dynamic Link Library (DLL)

In addition to standalone programs (.exe and .com), vTask can create Dynamic Link Libraries (DLL). DLLs are shared libraries, that allow other programs to access functionality provided in the DLL. Most modern computer features, and even parts of the operating system itself, are provided via DLLs.

How to Access a DLL created by vTask

Starting with version 7.30, vTask has the capability of compiling Dynamic Link Libraries. To create a new library module, choose the "DLL" option for the Platform:

DLLs created by vTask use "explicit run-time linking", instead of import library or other design-time methods. This method ensures that the largest possible number of programs can access the DLL (and due to technical necessity).

*Tip: As a general rule, DLLs should only be used for "processing" type of scripts, rather than user interface actions, due to the shared nature of DLLs. Certain User Interface and Wait commands may not work as expected. In these cases, when compiling DLLs, vTask will continue to compile rather than abort, but will show a warning message like "WARNING!! The selected PLATFORM is not compatible with some actions in "script.vxm". Some steps may not perform correctly."

When you create a DLL with vTask, it creates the DLL file, and an entry point function. To access the DLL, you must call this function. This entry function is always called "RunScript".

This function takes TWO parameters:

#1) An integer value which indicates which script step you want to start executing; This allows you to start running the DLL script at any point. This initial step must be between 1 and the total number of steps in your script. To start at the beginning, use "1".

#2) A string (text) that includes any information you want to pass to the DLL. This lets you pass data to your DLL. This is always a string (text) enclosed in quotes, so "Hello", "uno,dos,tres", and "1234" are all valid choices. To pass multiple values, send them as a single string, separated by a delimiter such as a semicolon or comma (and then parse them out inside the DLL Script). The passed string is available in the DLL as the {cmdline} system variable.

Putting it all together, you should then call your DLL as follows: RunScript ( 1, "Hello" ) to start running the script in the DLL at step #1 and use the data "Hello".

If your parameters are wrong, the DLL will display the following message:

If you use an invalid step number, your DLL will display the following error message:

If you want to test your DLL, a special function is included named "TEST" (all uppercase). This test function is very useful if you encounter problems calling other exported functions in the DLL. If you call the function TEST(), you should receive the following result:

When calling your DLL from external programs (like a Visual Basic or C++ program), here is the basic structure for calling a DLL. (This sample excludes error checking for clarity, but error checking is included in other samples):

        // Step 1: Declare Function Prototype
        typedef int (FAR PASCAL *RUNSCRIPT_FUNCTION)(int, LPCSTR);

        // Step 2: Load the DLL
        HINSTANCE hinstLib = LoadLibrary("C:\\Program Files\\Example.dll");

        // Step 3: Get the function pointer
        RUNSCRIPT_FUNCTION RunScript = (RUNSCRIPT_FUNCTION)GetProcAddress(hinstLib, "RunScript");

        // Step 4: Call the function with '1' as a parameter (start at Step #1)
        iReturn = (*RunScript)(1, "Hello");

        // Step 5: Unload the DLL
        FreeLibrary(hinstLib);

Visual Basic

Option Explicit
Declare Function RunScript Lib "Example.dll" (ByVal a As Integer, ByVal b As String) As Integer
 
Sub Main()
        Dim Result As Integer
        Result = RunScript(1, "Hello")
        MsgBox "The result was: " & Result
End Sub

C / C++ (Windows)

#include <windows.h>

// Function Prototype
typedef int (FAR PASCAL *RUNSCRIPT_FUNCTION)(int, LPCSTR);

int WINAPI WinMain (HINSTANCE hInstance, HINSTANCE hPrevInstance, LPSTR lpszCmdParam, int nCmdShow)
{
    RUNSCRIPT_FUNCTION  RunScript;
    int  iReturn;

    // Load the DLL
    HINSTANCE hinstLib = LoadLibrary("C:\\Program Files\\Example.dll");
    if(hinstLib == NULL)
    {
        MessageBox(NULL, "Unable to load library", "Error", MB_OK|MB_ICONERROR);
        return 0;
    }

    // Get the function pointer
    RunScript = (RUNSCRIPT_FUNCTION)GetProcAddress(hinstLib, "RunScript");
    if(RunScript == NULL)
    {
        FreeLibrary(hinstLib);
        MessageBox(NULL, "Unable to load function", "Error", MB_OK|MB_ICONERROR);
        return 0;
    }
    
    // Call the function with '1' as a parameter
    iReturn = (*RunScript)(1, "Hello");

    // Unload the DLL
    FreeLibrary(hinstLib);
    
    return iReturn;
}

C / C++ (Console)

#include <stdio.h>
#include <windows.h>      // "windows.h" is needed for "LoadLibrary" declarations, etc.

// Function Prototype
typedef int (FAR PASCAL *RUNSCRIPT_FUNCTION)(int, char*);

int main(int argc, char **argv)
{
    RUNSCRIPT_FUNCTION  RunScript;
    int  iReturn;

    // Load the DLL
    HINSTANCE hinstLib = LoadLibrary("C:\\Program Files\\Example.dll");
    if(hinstLib == NULL)
    {
        printf("Unable to load library\n");
        return 0;
    }

    // Get the function pointer
    RunScript = (RUNSCRIPT_FUNCTION)GetProcAddress(hinstLib, "RunScript");
    if(RunScript == NULL)
    {
        FreeLibrary(hinstLib);
        printf("Unable to load function\n");
        return 0;
    }
    
    // Call the function with '1' as a parameter
    iReturn = (*RunScript)(1, "Hello");
    printf("The result was: %d\n", iReturn);

    // Unload the DLL
    FreeLibrary(hinstLib);
    
    return iReturn;
}

Other DLL References

Also see the reference "Step by Step: Calling C++ DLLs from VC++ and VB" at http://www.codeproject.com/KB/DLL/XDllPt1.aspx

How to Access an external DLL from vTask

vTask provides an easy method to access external DLLs with the "Call DLL Function" action: