Creating
a
DLL

Building

DLL's are the easiest type of component to build.

There are certain minimum requirements of an DLL and these need to be provided to create an STMT DLL.

Because a DLL is a totally stand-alone component, it requires at least a message file to allow it to print out certain messages.

This is the simplest way to get started.

1. Create a Project directory for your Smalltalk MT project (e.g. CheckSumDLL). This directory will contain the project file or files(e.g CheckSumDLL.sp or CheckSumDLL.spx)

2. Create the resources. Go into the GUI Builder and select File menu->New->Resource script and point to your project directory. Select the things you need (typically About Box, Application Icon, Message File, Version resource). This will create a res folder in your project directory.

3. Compile the resources. With a command window, go to the res folder under your project. Type NMAKE. This will build a DLL with the same name as your project (important!). This DLL contains the resources you specified in step 2. This will only work if you have C/C++ installed.

What if you don't have C++? This means that you cannot use the NMAKE command to create a resource DLL. In that case, you can use one of the resource DLL's provided with STMT. Copy GenApp.Dll from Samples\Tutorial\Intro\GenApp\res into CheckSumDLL\res and rename this DLL to CheckSumDLL.dll

This DLL contains 6 resources. Namely an About Dialog, Large and Small Icon, a Message Table, a String Table and a Version resource. The DLL must be in the res subdirectory of the project and named the same as the prject for the STMT project builder to find it.

4. Add a class that is going to provide the DLL access point. Let us call this class CheckSum. Add this class to a new project and save the project into the CheckSumDLL directory as CheckSumDLL.spx

5. On the class side of CheckSum in the .EXPORT category (important!), create a class method as so:

 checkSum: szMessage
        "
        Calculate the checksum for the given string.
        Return the checksum value as an Integer
        "
        | checksum string |

        string := String fromAddress: szMessage.
        checksum := 0.
        1 to: string length do: [:i|
                checksum := checksum + (string at: i) asInteger.
        ].
        ^checksum \\ 256.

6. In your project folder, create a CheckSumDLL.def file which contains the instructions to build your DLL. In this case it will look like this.

LIBRARY CHECKSUMDLL
EXPORTS
CheckSum>>checkSum: :: CheckSum @2

This maps the class method to the name that the DLL caller will use.

Now your project will become buildable (the build button will be enabled in the Project Browser.

7. Check that all the pieces are in place. You should have a project directory CheckSumDLL containing three things, CheckSumDLL.spx (the project source file), CheckSumDLL.def (the DLL interface definition), and a res subdirectory. The res subdirectory must contain at least the CheckSumDLL.dll resource DLL.

8. Build your project. The CheckSumDLL.def will be loaded and used to create the exports section, and all of the resources from the resource DLL (in the res subdirectory) will also be loaded into your DLL.

The resulting CHECKSUMDLL.DLL will be placed in your STMT image directory by default.

Testing

You can test your new DLL from within Smalltalk MT by calling the function. It is important to note that methods in the .EXPORT category cannot be called directly from Smalltalk MT. To test this method use the following:

str := 'Here is a string'.
result := MemoryManager callAPI:
        (CheckSum methodAddressAt: #checkSum:)
        with: str basicAddress

The reason for this strange way of calling is that we must now follow the DLL calling convention rules. 'MemoryManager callAPI' does the call to an address (the address of the class method returned by methodAddressAt:) and a string pointer is passed as the argument.

Notice that since the API is passed a string pointer, it must create a Smalltalk string (using String fromAddress: szMessage) before it can send messages to this string.