WIL Extender SDK

Keywords: WIL extender SDK

What's a WIL extender? It's a Windows DLL, written in a "real" programming language (ie, C or C++), which provides additional functionality to our Windows Interface Language (WIL), and, by extension, to any application which uses the WIL language (such as WinBatch).

Users can load your extender DLL in a WinBatch script file, using the WIL "AddExtender" command, and your functions become available in their WIL scripts, just as if they were built into the WIL language itself.

Third party developers can customize and develop their own function libraries with WIL Extender SDK. Custom extender Dlls may add nearly any sort of function to the WIL language, from the mundane network, math or database extensions, to items that can control fancy peripherals, including laboratory or manufacturing equipment. The Extender SDK is included with the WinBatch+Compiler. The source code to this extender, WILX is included as an example with the Extender SDK.

To use the Extender SDK you will need appropriate programming tools, such as Microsoft Visual C++ or the Borland Windows Development System.

The current versions of the WIL SDK are for WinBatch 2001 and newer only.

WIL SDK is available on:

On both the current Compiler and the WinBatch CDs.
Via FTP WIL SDK Zip

Here are some details about the WIL Extender SDK:

Requirements:

In order to create a WIL extender DLL, you'll need a compiler capable of creating Windows DLL's. Our source code was written for Microsoft Visual C++ 6.0 (32-bit), and can probably be compiled using any comparable C or C++ compiler with only minor modifications.

You should have a fair degree of competence in Windows programming. That is to say, you should at least have a "Hello, world" program under your belt before you attack your first WIL extender. Some experience writing Windows DLL's is helpful but not necessary. We give you a sample program (WILX.C) containing the framework in which to add your own functions and the "hooks" necessary to talk to the main WIL DLL. We can provide technical assistance with creating WIL DLL extenders, but we can't teach you how to program or how to use the Windows API.

If you're a really good programmer, you may be able to convert the supplied code to work with a language other than C/C++. Unfortunately, we program primarily in C/C++ here, and can therefore provide only minimal assistance with any other languages (hint: you can probably port our code to Delphi without too much difficulty, but Visual BASIC would be a much more daunting task).

Compile Procedure:

There are no unusual steps needed to compile a WIL extender DLL, and no extra DLL's or libraries that need to be linked into your project. Just make sure to put ADDONS.H and WWWPFORM.H in the current directory or in a directory on your INCLUDE path (ie, where your other Windows header files are located), open the workspace in Visual C++, fix the various settings to customize it to where you placed the files try a "Rebuild ALL" on the project.

File List:

The WIL Extender SDK distribution disk contains the following files:


    Source:

      ADDONS   H       required header file
      WWWPFORM H       required header file
      README   TXT     WIL SDK info
      WILX     C       commented WIL extender source code
      WILX     RC      required resource file
      WILX     PLG     a build log file
      WILX     OPT     workspace options file
      WILX     NCB     no compile browser file
      WILX     DSW     a project workspace
      WILX     DSP     single project file
      WILX     APS     binary version of the resource file
      

    Other:

      README           TXT     you're reading it
      RELEASE\TEST34I  DLL     compiled 32-bit DLL
      DEBUG\TEST34I    DLL     compiled 32-bit DLL
      WILXTEST         WBT     test script for WILX functions

Detailed Description:

A WIL extender is an external DLL designed to complement the WIL script processor. The WIL Processor has an "AddExtender" function that will load a WIL extender. It basically performs a Windows API "LoadLibrary" on the extender, and then proceeds to extract its capabilities by a series of calls:

WILExtenderQuery case 1 is designed for interrogation of the extender to determine what it is. This may or may not be used by the calling program.

Usually the WIL processor first calls the WILQueryExtender function case 2 to negotiate a parameter interface level and to decide it the WIL engine and the extender DLL are compatible. Old-style extenders that do not support the WILQueryExtender function are assumed to be interface level 1. This version of the sample supports interface level 2.

Then, assuming the Extender supports interface level 2, a call to the WILExtender2 function, case -1 is performed to determine the number of functions, constants, commands and other table items that the extender wishes to add to the WIL command table.

Next a series of calls to the same WILExtender2 function with case -2 is performed to copy table entries to the main WIL engine tables.

The WIL interpreter provides a pointer to a 32 bit memory location (LONG FAR *). This pointer provides 32 bits of storage associated with the currently running script. Different scripts will point to a different 32 bit location. This allows (if required) state information to be saved by the extender. In addition, the extender may allocate a global memory block for storage, and save the handle of the memory block in the memory location. This allows almost unlimited local data for the extender. Note that most extenders ignore this field completely. Just becasue it is there does not mean you have to use it.

When the WIL script processor shuts down, WILExtender2 case -3 will be called once to allow the extender to perform clean-up processing.

The CommandExtTable defines the commands that the extender responds to, and the case #'s that correspond with the commands.

Up to 16 parameters may be passed to the extender. Each parameter is passed as a vipervar structure containing an integer (long), a string, and a floating point member, as well as an inittype member indicating what type of parameter it actually is (ie, which member(s) of the structure contain valid values):


    typedef struct vipervariable
    {
      double  flt;  // 8-byte floating point number
      LONG    x;     // if int variable, value is here
      int     inittype; // 0=uninitialized 1=int 2=string 3=both  yes can have both sometimes
      union
      {
        LPSTR lpstr; // pointer to string in string table
        DWORD handle; // handle for miscellaneous object types
      };
    } vipervar, FAR *LPVIPERVAR;

inittype will be one (or more) of the following:


    VARTYPE_UNDEF       0 // undefined (ie, beyond nArgCount)
    VARTYPE_INT         1 // integer value (in 'x')
    VARTYPE_STRING      2 // string (pointed to by 'lpstr')
    VARTYPE_FILE        5 // FILE and INT bits set (in 'x')
    VARTYPE_OLEOBJECT  17 // OLE AND INT bits set (in 'x')
    VARTYPE_FLOATNUM   32 // floating point value (in 'flt')
    VARTYPE_BINARY     65 // BINARY and INT bits set (in 'x')
    VARTYPE_ARRAY     256 // an array (complex type using all structure elements)

Note that a variable can be a string and/or integer and/or float. The theory is that if a conversion from a string to a float had to occur, for example, both the float and string values are maintained until the varialbe changes. Use bit checking to see what kind of varialge you have.

Your function also receives a pointer to one of these structures to use for returning a value to the WIL DLL.

In order to avoid using C runtime acsii<->string conversion functions, a pair of conversion routines (MyLtoa and MyAtol) has been provided.

You should provide one function to return the version number of your extender. Your version number should start at 31000 and increment as the DLL is modified.

Adopt a naming convention so that all functions in the extender begin with the same group of letters. A function name must be 30 characters or less.

---------------------------------------------------------------------------

A number of macros have been provided to assist in returning values to the WIL interpreter. These are:


    RETLONG(num)
      Returns a long integer as the return value 
      of the function.

    RETFLOAT(floatnum)
      Returns a floating point value as the return
      value of the function.

    RETSTRING(string)
      Returns a string as the return value of 
      the function.

    RETERROR(level, rcfilestringid)
      Returns an error level (use -1, -2, or -3).  
      We recommend -1 and a string from the resource 
      file for the error.  The string itself should 
      start with a 3-digit error number, followed by 
      a colon.

    RETCANCEL
      Used if you pop up a dialog box and the user 
      hits the Cancel button.

    ANSWERSTRING(string)

      Allows the extender to return a string response, 
      but does not return to the WIL interpreter directly 
      as the other functions do. It allows a response to 
      be constucted in a global memory buffer, the buffer 
      contents returned, and then allows processing to
      continue, usually to free the global buffer.

    ANSWERLONG and ANSWERFLOAT

      Apparently useless functions to allow processing 
      after returning the result to the WIL processor.  
      I imagine that someone somewhere may find a use 
      for them.

---------------------------------------------------------------------------

One final word of advice for those of you who are new to the joys of writing DLL's. Without getting into a lot of technical detail about memory segments and heaps and stacks, let's just say that all programs have a data segment (DS, also known as the local heap) and a stack segment (SS). For EXE's, the data segment and stack segment are one and the same (DS == SS). But DLL's don't get their own stack segment; they share the stack of the EXE that is calling them, and therefore the data segment and stack segment are different (DS != SS).

That said, you need to keep these important points in mind:

You must ALWAYS use 32-bit pointers to access objects that are on the stack, such as arrays and structures.
You have no control over the size of the stack, which you may be sharing with other DLL's as well as with your calling EXE. It's a good idea to avoid putting large arrays and the like on the stack.
C Storage Classes 101. Automatic variables (variables defined within functions, also known as local variables) get created on the stack: char szBuffer[200]; // goes on the stack "Static" variables get created on the heap instead: static char szBuffer[200]; // goes on the local heap

Article ID:   W12587

Filename:   WIL SDK Description.txt

File Created: 2014:06:17:12:25:56

Last Updated: 2014:06:17:12:25:56

Database Search

TechHome

WIL Extender SDK

Requirements:

Compile Procedure:

File List:

Detailed Description: