Go to the previous, next section.
Note: In this document, when you see a reference to Windows NT, it also applies to Windows 95 (unless otherwise stated).
Windows must be set up to use TCP/IP. Use the Network Configuration
and Control Applet under the Windows NT control panel to install and
configure your TCP/IP setup. For Windows 95, use the Network applet.
(See your Windows documentation for further
details.) Try all the usual TCP/IP applications (e.g. ping, ftp, telnet)
to ensure your TCP/IP is working properly.
You will also need the redistributable Microsoft C Runtime dynamic link
library for NT (`MSVCRT20.DLL' if using Visual C++ 2.0 or `MSVCRT40.DLL' if using
Visual C++ 4.0) on the system. The Visual C++
redistributable files are located in the `\MSVC20\REDIST' directory on the
Visual C++ Version 2.0 CD-ROM disc, or in the `\MSDEV\REDIST' directory on the Visual C++
4.0 CD-ROM. Note there are different runtime DLL
files depending on whether you're on Windows NT or on Windows 3.1 with Win32s. Be sure
you use the one for Windows NT when on NT.
Be careful to use the right Visual C++ runtime DLL. In particular, Windows 95 ships with one version of the DLL in the `\WINDOWS\SYSTEM' directory, since many of the Windows 95 system applets are written with Visual C++.
This release of ILU for Windows NT was developed with Microsoft Visual C++ Version 2.0, on Windows NT 3.5, and was built on Windows 95 and NT under Visual C++ 2.0 and 4.0. It has not been tried with any other compiler or version of NT. The ILU runtime DLLs for NT are 32 bit, and a 32 bit compiler is needed to develop applications that use them. If you succeed in building ILU or ILU applications for NT with a compiler other than Microsoft Visual C++ 2.0 or 4.0, please report your findings. We simply haven't had time to test ILU with other C or C++ compilers with Windows.
You must have a Winsock compliant TCP/IP stack installed and operating
on your system. This release of ILU for Windows has been tested only
on Windows for Workgroups (Windows 3.11) with Microsoft TCP/IP. You can
obtain Microsoft's TCP/IP by anonymous ftp as
ftp://ftp.microsoft.com/Softlib/MSLFILES/WFWT32.EXE
Follow the directions supplied within that file to install and configure
your TCP/IP setup. Try all the usual TCP/IP applications
(e.g. ping, ftp, telnet)
to ensure your TCP/IP is working properly.
The ILU C and C++ stubbers are WIN32 applications. In order to run them,
you must have Microsoft Win32s installed on your system. Microsoft Win32s
is available via anonymous ftp as
ftp://ftp.microsoft.com/Softlib/MSLFILES/PW1118.EXE.
You also need to have a Winsock header file (`winsock.h') and export library (`winsock.lib').
For development of ILU the same header file as supplied with Microsoft Visual
C++ 2.0 was used. The
implib utility was run on the `WINSOCK.DLL' that came with Microsoft's TCP/IP to create
the export library (`WINSOCK.LIB'). For this release, the header file and library distributed
with Visual C++ 1.52 was also tested.
You will need the redistributable Microsoft C Runtime Dynamic Link Library for Win32s (`MSVCRT20.DLL') on the system in order to run the stubbers. All of the Visual C++ redistributable files for WIN32s are located in the `\WIN32S\REDIST' directory on the Visual C++ Version 2.0 CD-ROM. Note there are different `MSVCRT20.DLL' files depending on whether you're on Windows NT or on Windows 3.1 with Win32s. Also, keep in mind that if you rebuild ILU yourself, you should use the Runtime DLL that ships with your copy of Microsoft Visual C++. If you recompile ILU with Visual C++ 4.0, use the DLL from your Visual C++ 4.0 CD-ROM. Mixing ILU and Microsoft DLLs that aren't the same version will definitely cause you problems. Be sure you use the one for Windows Win32s when on Windows 3.1.
Finally, don't be confused by the stubber names. While WIN32s will load the Windows NT version
of the stubbers, they won't run. The WIN32s stubbers all end with 32W in their name, while the NT
stubbers are just called c-stubber and c++-stubber.
ILU comes prebuilt for Windows NT and Windows 3.1. For the current release of ILU,
a single `.ZIP' file is the prebuilt version. Since some of the files meant for NT use long file names,
you'll see the 8.3 filename mapping of these on a Windows 3.1 machine (FAT file system). The `.ZIP'
file is created with Nico Mak Computing's WINZIP, which allows long file names and is available for all versions
of Windows. However, if you only have PKZIP, you should be able to extract the files from the
`.ZIP' with no problems. Just make sure you use the -d when unzipping so that PKZIP will preserve
the directory structure contained within the `.ZIP' file.
Determine where you wish to install
ILU, e.g. `C:\ILUWIN'. Set the environment variable ILUHOME to this directory (ILUHOME is needed
for building the examples). Unpack the distribution into your installation directory using
pkzip -d iluwin20.zip. You should now have subdirectories in ILUHOME called `bin',
`examples', `include', `interfaces'
and `lib'.
If you'll be developing ILU apps, or building the examples, set the environment variable ILUPATH to include `ILUHOME\interfaces' (or `ILUHOME\intrface' for Windows 3.1 setups). ILUPATH is the path of directories where interface (`.isl') files can be found. For example, setting ILUPATH to `.;C:\ILUWIN\INTERFACES' will cause ILU stubbers to look for interfaces first in the current directory, then in `C:\ILUWIN\INTERFACES'. Add the `ILUHOME\bin' directory to your PATH environment variable.
Determine what common directory share will be used for your applications to publish
information about ILU objects. This will commonly be a directory that is exported from
a file server and shared by all the systems. Set the environment variable
ILU_BINDING_DIRECTORY to this directory e.g. ILU_BINDING_DIRECTORY=f:\iluwin\bindings.
If you do not set this, ILU will default to `\ilu\interfaces'.
(For those who just *must* have and build the source! :-)
If you wish to build the ILU system from source, begin by obtaining the source distribution (`ilu.tar.gz'). There is no separate source tree for the Windows version; the same source code is used for both Unix and Windows. Set ILUHOME to where you will want ILU to be installed. Determine where you wish to install the ILU source, and set the environment variable ILUSRC to that directory e.g. `ILUHOME\src'. Unpack the distribution into that directory. Change to the ILUSRC directory. Having previously installed Visual C++, perform
> nmake -f ilunt35.makTo subsequently install into ILUHOME, perform
> nmake -f ilunt35.mak installNote that the default is to build a 'release' version. If you wish to build a 'debug' version perform
> nmake -f ilunt35.mak CFG="Win32 Debug"To clean up after installation perform
> nmake -f ilunt35.mak clean
When bulding the debug versions of the c, c++, and kernel runtimes, the values of the environment variables, ILU_DEBUG_CFLAGS and ILU_DEBUG_CPPFLAGS are passed to the c and c++ compiler command lines respectively. This allows the builder to do things like creating source browser files, e.g. set ILU_DEBUG_CFLAGS=/FR"/ilu/browsefiles/", set ILU_DEBUG_CPPFLAGS=/FR"/ilu/browsefiles/".
Note: "make clean" does not work across all versions of Windows. In particular, it will not work on any other system besides Windows NT. If you are using Windows 95, just remove all occurrences of the `WinDebug', `WinDebugW', `WinRel', and `WinRelW' directories in the source tree and examples directories.
The Windows 3.1 version of ILU is also built on Windows NT. Ensure that you've installed
Visual C++ 1.5. Edit the file `ILUSRC\iluwin31.mak' to reflect the locations of your
Visual C++ 1.5. components. Note that you must set the WSOCKHDR environment var
before running this makefile. This variable should be set to the location of your
winsock header file (typically named `WINSOCK.H'). Using the Visual C++ 1.5 nmake
utility, perform
> nmake -f iluwin31.mak
(or
> nmake -f iluwin31.mak DEBUG=1
if you wish to build a debug version.
Note: The stubbers are WIN32 applications and can only be built under Visual C++ 2.0 or 4.0 on Windows NT. It should be possible to rebuild the runtime under Windows 3.1 though.
To subsequently install into ILUHOME, perform
> nmake -f iluwin31.mak installTo clean up after installation perform
> nmake -f iluwin31.mak clean
Note that it is normal to see a number of compiler warnings during the ILU build process.
To build the examples, cd to `ILUHOME\examples'. Ensure that you have set ILUPATH as previously discussed.
Note: It is important to note that the current versions of the Windows makefiles do not execute the stubbers before compiling the actual programs. Be sure you run the stubbers yourself before attempting to build the examples, or you will get mysterious "don't know how to make" errors on header files that don't exist yet because the stubbers create them. The Windows 3.1 stubbers can be executed via the batch file mentioned in the paragraphs below.
For Windows NT examples, perform
> nmake -f iluwinnt.mak
If you wish to build a 'debug' version perform
> nmake -f ilunt35.mak CFG="Win32 Debug"
This will create the example NT executables in subdirectories of the `example' subdirectories, called `WinRel' and `WinRelW' (or `WinDebug' and `WinDebugW' if you built a debug release) which correspond to the non-Windows and Windows versions of the examples.
To build the Windows 3.1 examples, edit the makefile `ILUHOME\examples\iluwin31.mak' to reflect the locations of your Visual C 1.5 components. Note that you must set WSOCKLIB and WSOCKHDR environment vars before running this makefile. These variables should be set to the location of your winsock export library (`WINSOCK.LIB') and winsock header file (`WINSOCK.H') respectively.
For the Windows 3.1 examples, there are two situations. Building them on an Windows NT machine, and building them on a Windows 3.1 machine. Note that Windows 3.1 example executables appear directly in the `examples' subdirectory.
If you are building them on an NT machine, cd to `ILUHOME\examples\test1' run the batch files `tstcw16.bat' and `tstcpw16.bat'. This uses the windowed versions of the stubbers to produce the C and C++ stubs for the Windows 3.1 examples. (Note we could have just as well used the non Windows versions of the stubbers (sans the -batch switch you can see in the batch file.) to do this as well, since the output of the Windows stubbers and the WIN32 stubbers is identical.
If you are building on a Windows 3.1 machine, you can't run the stubbers this way since you cannot launch Windows applications from a DOS box under Windows 3.1. There are some public domain (e.g. `run' by Frits Wiarda (`run18.zip')) and shareware (e.g. `unixcorn' by Randall Spangler (`unixcn20.zip') $10) utilities that will let you launch Windows apps from a Windows 3.1 DOS box. Unixcorn is probably the better bet since it provides an option to wait till the Windows app actually returns. These utilities should allow you to run the windowed stubbers from batch and make files. Visual C++ 1.5 also comes with a program called `WXServer' that allows you to invoke Windows apps from a DOS box.
(Since the following procedure is tedious, the Win3.1 stubs are already included with the distribution.)
To create the stubs, you'll have to manually run the C stubber (`cstub32w.exe') and C++ stubber (`cpstb32w.exe') using the same arguments you see in the batch files, only omitting the -batch switch. When the stubber window appears, you'll also see a file selection box. This is used to set the default drive and directory for the stubber. Choose any file from the `ILUHOME\examples\test1' directory. Next, the main window will prompt you for arguments. Using the batch file contents as a guide, enter the appropriate arguments for each of the 3 `.isl' files. For example,
-tname t1true -sname t1surrgt -hname t1hdr -cname t1comm -hdrmap test1h.map Test1.isl
So in all you'll run `cstub32w.exe' 3 times, once for each of `Test1.isl' `Test2.isl' and `Test3.isl', and `cpstb32w.exe' 3 times, once for each of `Test1.isl' `Test2.isl' and `Test3.isl'. After doing this a few times, you will probably want to go get `unixcorn'!
Note that it is normal to see a number of compiler warnings during the examples build process.
Ensure that you have set ILU_BINDING_DIRECTORY as previously discussed. The non-Windows NT examples operate just like their Unix counterparts. The Windows examples are simple Windows versions of the same programs. To execute them, launch the executables (from the Windows File Manager, a command prompt (if you are running Windows NT or 95, or whatever), and choose the 'Run' entry from the 'Action' menu.
The basic process for using ILU in a Windows application is simple. You either write a new interface description or use an existing one. You run the stubbers against the interface description to generate stub code. You write calls to the methods exported from the interface in your application, or implement the object type in your application, depending on whether you're using the module, or providing it. Finally, you link your application code together with the generated stub code and the ILU libraries.
There are console and windowed versions of the stubbers and islscan program. The
console versions can only be used on NT. The windowed versions are meant primarily
to be used on Windows 3.1 machines with WIN32s, although they can also be used on Windows NT.
Prior to this release, the stubbers had a number of switches as described in the ILU reference manual. These switches are still valid, but a number of new switches have been added. These new switches are primarily intended to accomodate use on a FAT file system, where filenames are restriced to the 8.3 form. Normally, the stubbers produce files that are based on the name of the interface being processed, appended with some extension (e.g. `test1-common.c'). However, this does not fit the 8.3 restriction.
The new switches for the c-stubber are
-tname TRUEFILENAME
-sname SURROGATEFILENAME
-hname HEADERFILENAME
-cname COMMONFILENAME
and the new switches for the c++-stubber are
-hname HEADERFILENAME
-sname STUBSFILENAME
-cname CLIENTCOMMONFILENAME
allow you to specify exactly what the corresponding files should be named.
Because you can now specify the header filenames, there must be some means for the stubber to know what header is associated with what interface. Both stubbers also have the new switch
-hdrmap INTERFACEHEADERTRANSLATIONFILE
This switch specifies a mapping file from interface names to the header file that is to be associated with the interface. See the files (in `ILUHOME\examples') called `tstcw16.bat' and `test1h.map' for a C based example, and `tstcpw16.bat' and `test1hh.map' for a C++ based example of the use of these new switches.
The windowed stubbers also accept an additional switch, -batch, meant to facilitate their use from a command line (as you might use in a makefile or batch file). If this switch is used, it must be the first thing on the command line. If there is no -batch switch, the windowed stubber will pause with its window on the screen to allow the user to view the output. If the -batch switch is used and the stubber is successful, the window will dissappear and the stubber will exit. If the stubber is unsuccessful, the stubber will pause with its window on the screen to allow the user to view the output of the unsuccessful stubbing attempt.
Ensure that WIN32 is defined to the preprocessor when building a 32 bit ILU application. This is normally set by default by Visual C++, but you should verify.
Link with the non-Windows (console) versions of the libraries for Windows NT console apps. You need to link with the language specific runtime, the kernel runtime, and the winsock library.
Set the Visual C++ 2.0 code generation compiler option to use the Multithreaded using DLL C runtime on Windows NT. This is very important.
There is NO need to call ilu_StartWinsock for a Windows NT ILU app. (It is taken care of for
you internally in the runtime DLL process attach code).
We suggest you review and understand the test1 examples before you try to build a windowed ILU application. This section tries to highlight some of the important points. Admittedly, the Windows examples are simple and crude as Windows apps go, but they illustrate what you need to do in an application.
ILU was originally developed for Unix machines where there is always a notion of standard input and output. Error and Debug messages from the ILU runtime are sent to standard output. With Windows NT console applications, this same model is present. However with Windows 3.1 applications there is no notion of a console to which standard input and output can be applied (although under Windows NT you can programatically create a console; that is not addressed here). To provide a place for the ILU runtime to write standard output, the winio library is used. The winio library in ILU is an extension of the original very useful utility by Dave Maxey and Andrew Schulman - discussed in the Microsoft Systems Journal, 1991 #4 (July-Aug). When used properly, it causes an additional window to appear along with your application window, to which ILU runtime standard output (and yours too if you want to use a few printf's) is sent. Try setting ILU_DEBUG (as described in the ILU Reference manual) and you'll see the debug output get sent to the winio console window. If you make any nifty mods to this helpful library please pass them on!
To use the winio library, be sure to define _WINIO to the preprocessor when building a
Windows ILU application, and tell the linker to include the winio library. You'll also
likely want an icon for the console icon. This icon should be called WINIO_ICON.
That is, you'll have an line in your resource file (.rc file) like:
WINIO_ICON ICON DISCARDABLE "clnconsl.ico"
Your WinMain function will also contain a call (probably before you do your ShowWindow call)
to create the console window that looks something like:
winio_console(hInstance, hPrevInstance, nCmdShow, 0, "clientw Console");
See the `WINIO.H' header file for a description of winio functionality. For more information, see the Microsoft Systems Journal, 1991 #4 (July-Aug), and the ILU winio source code.
It is very important to set the Visual C++ code generation compiler option to use the Multithreaded DLL C runtime on Windows NT.
Ensure that WIN32 is defined to the preprocessor when building a 32 bit ILU application. This is normally set by default by Visual C++, but you should verify.
Link with the Windows versions of the libraries for Windows NT ILU apps. You need to link with the language specific runtime, the kernel runtime, the winio library, and the winsock library.
There is no need to call ilu_StartWinsock for a Windows NT ILU app. (It is taken care of for
you internally in the runtime DLL process attach code).
In C++ ILU apps, you'll be including `Windows.h'. However, `Windows.h' includes `winspool.h'
and this file #defines AddPort as AddPortA. This interferes with iluServer::AddPort(),
so you have to undefine it (temporarily at least). See the `examples\test1\cppsrvrw.cpp'
file for an example.
Windows 3.1 applications must call ilu_StartWinsock before performing any ILU calls.
For C based apps this is done directly by your code. For C++ based apps, a compiler pragma
must be used to ensure ilu_StartWinsock is called early in the static object
initialization phase of program startup.
Under WIN32, you never need the call to ilu_StartupWinsock since ILU
is implemented as a DLL, and DLLs under Windows NT have an entry that allows
things to happen when a process attaches to the DLL. It is at that point under win32
that the winsock startup is taken care of for you. Under Wdows 3.1, ILU is in static
libraries, and there is no such mechanism. It isn't a problem with the C
runtime, since the app can call ilu_StartupWinsock before it performs any ILU
functions. With the C++ runtime however, there are some static object initializers
that make use of winsock operations (and these are run before WinMain is even entered).
So we have to insure that ilu_StartupWinsock is somehow called before these other ILU
initializers. We do this by having a static initializer ourselves that causes
ilu_StartupWinsock to be called, and we ensure that this happens before the ILU
initializers by using the Microsoft pragma init_seg(lib) (Note that the ILU initializers
occur in the 'user' part of the startup sequence. See Microsoft Knowledge Base
artical PSS ID Number: Q104248 for more infomation on this static initializer ordering.)
For a Windows 3.1 C++ ILU app, you use something like:
#pragma init_seg(lib) /* initialize winsock when under WIN16 */ int g_i_force_initializer_run = ILU_StartupWinsock ();
See the `test1' examples, files `clntw.c' and `cppclntw.cpp'. Use Large Memory Model for compiling / linking your 16 bit Windows 3.1 ILU apps. All the libraries for Windows 3.1 are Large Model. Do not mix memory models! This will cause you more grief than you've ever encountered.
#define WIN16 to the preprocessor when building a 16 bit ILU application. Note that the
compiler does not automatically define this.
Link with the static Windows versions (there are no others) of the runtime libraries, the winio library, and the winsock library for Windows apps.
See the windowed test1 server examples for a simplistic timer based means of using ILU
in the presence of a Windows message loop. (`msgalarm.c'). You'll want to do something
about the message loop since otherwise your Windows app won't service the GUI - it'll
just be blocked in an internal call to select() waiting to deal with ILU activity.
This simple timer approach makes use of the ability to associate an 'alarm' function
with the ILU mainloop. When the alarm goes off (the example uses every 500 milliseconds),
the alarm function processes any Windows messages that are waiting, then sets the
alarm for another period.
Note that the test1 examples were developed with Microsoft's TCP/IP for Windows for
Workgroups. Some of the behavior may be different under a different winsock implementation
(especially with respect to message dispatch during select() calls). If so, please let us
know.
Note: this list is in the process of being updated. While there are errors in it, the distribution .ZIP file should not be missing any files. When ILU 2.0 becomes finalized, this list will be corrected.
bin directory -------------
lib directory
(Note unlabeled entries are the import export libraries for their counterparts in the bin directory)
include directory (header files need for building ILU apps)
interfaces (or intrface on Win3.1)
examples/timeit (currently only as console apps for Win NT)
examples/test1
Go to the previous, next section.