Creating a Standalone DLL

Part X
Creating a Standalone DLL

In order for you to be able to add your new grid function to the PDE Toolkit, you must first create a DLL(dynamic link library) that includes your grid function. The grid function DLL (AKA Toolkit) can have more than one grid function included in it. I will create a standalone DLL from our finished program calendar.x which is derived from calendar10.x.

It is worth repeating that a grid function library is like a conventional program, except:

its PROGRAM statement argument must be the same as its filename.
its external variables are not accessible to other programs or dlls.
its entry function does little or nothing except initialization.
its entry function is called automatically when imported.
it doesn't usually perform a complete activity by itself.
it is compiled as a function library.

Modify the PROLOG
To obtain file calendar.x, I made a copy of calendar9.x. I then deleted the functions Calendar ( ) and Calendar ( ) since they are not needed in the library. After that, I needed to make a few changes to the PROLOG:

PROGRAM "calendar"
VERSION "0.0001"
'
IMPORT "xst"
IMPORT "xgr"
IMPORT "xui"
'
EXPORT
DECLARE FUNCTION Entry          ()
DECLARE FUNCTION Blowback       ()
END EXPORT
INTERNAL FUNCTION InitGui       ()
INTERNAL FUNCTION InitProgram   ()
INTERNAL FUNCTION CreateWindows ()
EXPORT
DECLARE FUNCTION Julian    (XLONG gregorian)
DECLARE FUNCTION Gregorian (XLONG julian)
DECLARE FUNCTION Weekday   (julian)
DECLARE FUNCTION XLONG DateToGregorianDayNumber (year, month, day)
DECLARE FUNCTION DsCalendar (grid, message, v0, v1, v2, v3, kid, ANY)
END EXPORT

There are two important things to mention about the above PROLOG. First, I have made sure to name the PROGRAM statement argument by the correct grid function filename "calendar".

The second item I should note is that you need to EXPORT any function that is needed by the calling program as well as the Entry ( ) function. As in a normal program, the first declared function is automatically called. So in the above example, Entry ( ) will be automatically called when the DLL is first imported. However, if we did not export Entry ( ), then our DLL would not initialize properly by calling the internal functions InitGui ( ), InitProgram ( ), and CreateWindows ( ).

The Blowback ( ) function is a callback function that is called when the calling program closes. It is only necessary if any of the DLL functions has made any system function calls to memory or files that need to be resolved/unloaded before the program finishes.

Initialize the grid function in InitProgram ( )
When our grid function is imported by our calling program, it will automatically call Entry ( ) which in turn will internally call InitProgram ( ). We need to make sure that our grid function is initialized before it is called by the calling program. The following line in InitProgram ( ) makes sure that DsCalendar ( ) is initialized:

DsCalendar (0, 0, 0, 0, 0, 0, 0, 0)

Compile and Build the Standalone DLL
I can now compile and build the standalone DLL. For Win9x systems this is most easily accomplished by starting a DOS session: Start > Programs > MS-DOS Prompt.

Then using calendar.x as our example file, at the DOS prompt, follow these steps:

    1. Make sure calendar.x is located in directory \xb
    2. Change to the xb directory by typing:
    cd \xb
    3. Then to compile the library type:
         xb calendar.x -lib
    4. To build the standalone DLL type:
         nmake -f calendar.mak

***Note: The above steps only apply to XB Windows version 6.0.

If the above steps are successful, then the file calendar.dll has been created in \xb.

Test the standalone DLL
We should now test our grid function library calendar.dll to make sure it works properly. Shown below is the PROLOG from the test program calendartest.x:

PROGRAM "calendertest"
VERSION "0.0001"
'
IMPORT "xst"
IMPORT "xgr"
IMPORT "xui"
IMPORT "calendar"
'
INTERNAL FUNCTION Entry         ()
INTERNAL FUNCTION InitGui       ()
INTERNAL FUNCTION InitProgram   ()
INTERNAL FUNCTION CreateWindows ()
INTERNAL FUNCTION InitWindows   ()
INTERNAL FUNCTION Calendar      (grid, message, v0, v1, v2, v3, r0, ANY)
INTERNAL FUNCTION CalendarCode (grid, message, v0, v1, v2, v3, kid, ANY)

In order to utilize calendar.dll I must import it using the IMPORT statement. Naturally, this test program does not include DsCalendar ( ) since that is the function we want to call and test in our grid function library.

Just one more step

Now that we have a working grid function library, we are now ready to add DsCalendar ( ) to the PDE Toolkit.

Previous Home Next