@setfilename ilu-windows.info
@settitle Using ILU with Microsoft Windows
@ifclear largerdoc
@titlepage
@title ILU and Microsoft Windows
@author Dan Larner @code{<larner@@xenon.stanford.edu>}
@author Mark Davidson @code{<mdavidso@@parc.xerox.com>}
@sp
(typeset @today{})
@sp
Copyright @copyright{} 1994-1996 Xerox Corporation@*
All Rights Reserved.
@end titlepage
@end ifclear

@ifclear largerdoc
This document assumes that you are already somewhat familiar with @system{ILU}.
The @system{ILU} Reference Manual can be obtained via FTP from
@url{ftp://ftp.parc.xerox.com/pub/ilu/ilu-manual.ps} 
or use your Web browser to see the page
@url{ftp://ftp.parc.xerox.com/pub/ilu/ilu.html}.
@end ifclear

Note:  In this document, when you see a reference to @system{Windows NT}, it also applies to @system{Windows 95}
(unless otherwise stated).

@section Prerequisites for using @system{ILU} with Microsoft @system{Windows}

@subsection Using @system{ILU} applications on @system{Windows NT} and @system{Windows 95}

@system{Windows} must be set up to use @protocol{TCP/IP}. Use the @program{Network Configuration
and Control} Applet under the @system{Windows NT} control panel to install and
configure your @protocol{TCP/IP} setup.  For @system{Windows 95}, use the @program{Network} applet. 
(See your @system{Windows} documentation for further
details.) Try all the usual @protocol{TCP/IP} applications (e.g. @program{ping}, @program{ftp}, @program{telnet}) 
to ensure your @protocol{TCP/IP} is working properly.
 
You will also need the redistributable Microsoft @language{C} Runtime dynamic link
library for NT (@file{MSVCRT20.DLL} if using @system{Visual C++} 2.0 or @file{MSVCRT40.DLL} if using
@system{Visual C++} 4.0) on the system.  The @system{Visual C++} 
redistributable files are located in the @file{\MSVC20\REDIST} directory on the
Visual C++ Version 2.0 CD-ROM disc, or in the @file{\MSDEV\REDIST} directory on the @system{Visual C++}
4.0 CD-ROM.  Note there are different runtime DLL
files depending on whether you're on @system{Windows NT} or on @system{Windows} 3.1 with Win32s. Be sure
you use the one for @system{Windows NT} when on NT.

@strong{Be careful to use the right Visual C++ runtime DLL.  In particular,
@system{Windows 95} ships with one version of the DLL in the @file{\WINDOWS\SYSTEM} directory,
since many of the @system{Windows 95} system applets are written with @system{Visual C++}.}

@subsection  Prerequisite software to use AND develop @system{ILU} applications on @system{Windows NT} and 95.

This release of @system{ILU} for @system{Windows NT} was developed with Microsoft Visual 
@language{C++} Version 2.0, on @system{Windows NT} 3.5, and was built
 on @system{Windows 95} and NT under @system{Visual C++} 2.0 and 4.0.  It has not been tried with any other 
compiler or version of NT.	The @system{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 @system{ILU} or @system{ILU} applications for NT with a compiler other 
than Microsoft @system{Visual C++} 2.0 or 4.0, please report your findings.  We simply haven't had
time to test ILU with other @language{C} or @language{C++} compilers with @system{Windows}.


@subsection Prerequisite software to use @system{ILU} applications on @system{Windows} 3.1

You must have a Winsock compliant @protocol{TCP/IP} stack  installed and operating
on your system. This release of @system{ILU} for @system{Windows} has been tested only
on @system{Windows for Workgroups} (@system{Windows} 3.11) with Microsoft @protocol{TCP/IP}.  You can
obtain Microsoft's @protocol{TCP/IP} by anonymous ftp as
@url{ftp://ftp.microsoft.com/Softlib/MSLFILES/WFWT32.EXE}
Follow the directions supplied within that file to install and configure 
your @protocol{TCP/IP} setup. Try all the usual @protocol{TCP/IP} applications 
(e.g. @program{ping}, @program{ftp}, @program{telnet}) 
to ensure your @protocol{TCP/IP} is working properly.


@subsection Prerequisite software to use AND develop @system{ILU} applications on @system{Windows} 3.1

The @system{ILU} @language{C} and @language{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
@url{ftp://ftp.microsoft.com/Softlib/MSLFILES/PW1118.EXE}.

You also need to have a Winsock header file (@file{winsock.h}) and export library (@file{winsock.lib}).
For development of @system{ILU} the same header file as supplied with Microsoft Visual 
@language{C++} 2.0 was used.  The 
@program{implib} utility was run on the @file{WINSOCK.DLL} that came with Microsoft's @protocol{TCP/IP} to create 
the export library (@file{WINSOCK.LIB}).  For this release, the header file and library distributed
with @system{Visual C++} 1.52 was also tested.

You will need the redistributable Microsoft @language{C} Runtime Dynamic Link
Library for Win32s (@file{MSVCRT20.DLL}) on the system in order to run the 
stubbers. All of the @system{Visual C++} redistributable files for WIN32s are located in the 
@file{\WIN32S\REDIST} directory on the @system{Visual C++} Version 2.0 CD-ROM.  Note there are 
different @file{MSVCRT20.DLL} files depending on whether you're on @system{Windows NT} or on
@system{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 @system{Visual C++}.  If you recompile
@system{ILU} with @system{Visual C++} 4.0, use the DLL from your @system{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 @system{Windows} Win32s when on @system{Windows} 3.1.

Finally, don't be confused by the stubber names.  While WIN32s will load the @system{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 @program{c-stubber} and @program{c++-stubber}.


@section Installation

@system{ILU} comes prebuilt for @system{Windows NT} and @system{Windows} 3.1. For the current release of @system{ILU},
a single @file{.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 @system{Windows} 3.1 machine (FAT file system).  The @file{.ZIP}
file is created with Nico Mak Computing's @program{WINZIP}, which allows long file names and is available for all versions
of @system{Windows}.  However, if you only have @program{PKZIP}, you should be able to extract the files from the
@file{.ZIP} with no problems.  Just make sure you use the @switch{-d} when unzipping so that @program{PKZIP} will preserve
the directory structure contained within the @file{.ZIP} file.

Determine where you wish to install
@system{ILU}, e.g. @file{C:\ILUWIN}.  Set the environment variable @metavar{ILUHOME} to this directory (@metavar{ILUHOME} is needed
for building the examples).  Unpack the distribution into your installation directory using 
@code{pkzip -d iluwin20.zip}.  You should now have subdirectories in @metavar{ILUHOME} called @file{bin}, 
@file{examples}, @file{include}, @file{interfaces} 
and @file{lib}. 

If you'll be developing @system{ILU} apps, or building the examples, set the environment 
variable @metavar{ILUPATH} to include @file{@metavar{ILUHOME}\interfaces} (or @file{@metavar{ILUHOME}\intrface} for @system{Windows} 3.1 setups).
@metavar{ILUPATH} is the path of directories where interface (@file{.isl}) files can be found.  For example,
setting @metavar{ILUPATH} to @file{.;C:\ILUWIN\INTERFACES} will cause @system{ILU} stubbers to look for interfaces
first in the current directory, then in @file{C:\ILUWIN\INTERFACES}.
  
Add the @file{@metavar{ILUHOME}\bin} directory to your @metavar{PATH} environment variable.

Determine what common directory share will be used for your applications to publish
information about @system{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 
@metavar{ILU_BINDING_DIRECTORY} to this directory e.g. @code{@metavar{ILU_BINDING_DIRECTORY}=f:\iluwin\bindings}.  
If you do not set this, @system{ILU} will default to @file{\ilu\interfaces}.


@section Building @system{ILU}

(For those who just *must* have and build the source! :-)

If you wish to build the @system{ILU} system from source, begin by obtaining the source distribution 
(@file{ilu.tar.gz}).  There is no separate source tree for the @system{Windows} version; the same source code
is used for both @system{Unix} and @system{Windows}.  Set @metavar{ILUHOME} to where you will
want @system{ILU} to be installed.
Determine where you wish to install the @system{ILU} source, and set the environment 
variable @metavar{ILUSRC} to that directory e.g. @file{@metavar{ILUHOME}\src}. Unpack the
distribution into that
directory.  Change to the @metavar{ILUSRC} directory.  Having previously installed Visual
@language{C++}, perform 

@transcript
> @userinput{nmake -f ilunt35.mak}
@end transcript
@noindent
To subsequently install into @metavar{ILUHOME}, perform 

@transcript
> @userinput{nmake -f ilunt35.mak install}
@end transcript
@noindent 
Note that the default is to build a 'release' version.  If you wish to build a 
'debug' version perform 

@transcript
> @userinput{nmake -f ilunt35.mak CFG="Win32 Debug"}
@end transcript
@noindent
To clean up after installation perform 

@transcript
> @userinput{nmake -f ilunt35.mak clean}
@end transcript

When bulding the debug versions of the c, c++, and kernel runtimes, the values of the environment variables,
@metavar{ILU_DEBUG_CFLAGS} and @metavar{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/".

@strong{Note: "make clean" does not work across all versions of @system{Windows}.  In particular, it will not work on
any other system besides @system{Windows} NT.  If you are using @system{Windows} 95, just remove all occurrences of
the @file{WinDebug}, @file{WinDebugW}, @file{WinRel}, and @file{WinRelW} directories in the source tree and examples
directories.}

The @system{Windows} 3.1 version of @system{ILU} is also built on @system{Windows NT}.  Ensure that you've installed
@system{Visual C++} 1.5.  Edit the file @file{@metavar{ILUSRC}\iluwin31.mak}	to reflect the locations of your
@system{Visual C++} 1.5. components. Note that you must set the @metavar{WSOCKHDR} environment var
before running this makefile.  This variable should be set to the location of your 
winsock header file (typically named @file{WINSOCK.H}). Using the @system{Visual C++} 1.5 @program{nmake}
utility, perform

@transcript
> @userinput{nmake -f iluwin31.mak}
@end transcript

(or 

@transcript
> @userinput{nmake -f iluwin31.mak DEBUG=1}
@end transcript

if you wish to build a debug version.

Note:  The stubbers are WIN32 applications and can only be built under @system{Visual C++} 2.0 or 4.0
on @system{Windows NT}. It should be possible to rebuild the runtime under @system{Windows} 3.1 though.

To subsequently install into @metavar{ILUHOME}, perform 

@transcript
> @userinput{nmake -f iluwin31.mak install}
@end transcript
 
To clean up after installation perform 

@transcript
> @userinput{nmake -f iluwin31.mak clean}
@end transcript

Note that it is normal to see a number of compiler warnings during the @system{ILU} build process.
 

@section  Building the examples

To build the examples, cd to @file{@metavar{ILUHOME}\examples}.  Ensure that you have set @metavar{ILUPATH}
as previously discussed. 

Note:  It is important to note that the current versions of the @system{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 @system{Windows} 3.1 stubbers can be
executed via the batch file mentioned in the paragraphs below.

For @system{Windows NT} examples, perform 

@transcript
> @userinput{nmake -f iluwinnt.mak}
@end transcript

If you wish to build a 'debug' version perform 

@transcript
> @userinput{nmake -f ilunt35.mak CFG="Win32 Debug"}
@end transcript

This will create the example NT executables
in subdirectories of the @file{example} subdirectories, called @file{WinRel} and @file{WinRelW} (or
@file{WinDebug} and @file{WinDebugW} if you built a debug release) which correspond to the non-@system{Windows} and
@system{Windows} versions of the examples.

To build the @system{Windows} 3.1 examples, edit the makefile @file{@metavar{ILUHOME}\examples\iluwin31.mak}
to reflect the locations of your Visual @language{C} 1.5 components. Note that you must set @metavar{WSOCKLIB}
and @metavar{WSOCKHDR} environment vars before running this makefile.  These variables should be
set to the location of your winsock export library (@file{WINSOCK.LIB}) and winsock header file
(@file{WINSOCK.H}) respectively.

For the @system{Windows} 3.1 examples, there are two situations.  Building them on an @system{Windows NT} machine,
and building them on a @system{Windows} 3.1 machine.  Note that @system{Windows} 3.1 example executables 
appear directly in the @file{examples} subdirectory.

If you are building them on an NT machine,
cd to @file{@metavar{ILUHOME}\examples\test1} run the batch files @file{tstcw16.bat} and @file{tstcpw16.bat}.  This
uses the windowed versions of the stubbers to produce the @language{C} and @language{C++} stubs for the 
@system{Windows} 3.1 examples. 
(Note we could have just as well used the non @system{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 @system{Windows} 
stubbers and the WIN32 stubbers is
identical.  

If you are building on a @system{Windows} 3.1 machine, you can't run the stubbers this way since
you cannot launch @system{Windows} applications from a @system{DOS} box under @system{Windows} 3.1. There are some 
public domain (e.g. @file{run} by Frits Wiarda (@file{run18.zip})) and shareware (e.g. @file{unixcorn} 
by Randall Spangler (@file{unixcn20.zip}) $10) utilities that will let you launch @system{Windows} apps from
a @system{Windows} 3.1 @system{DOS} box. Unixcorn is probably the better bet since it 
provides an option to wait till the @system{Windows} app actually returns.  These utilities
should allow you to run the windowed stubbers from batch and make files. @system{Visual C++} 1.5 also comes with a program
called @file{WXServer} that allows you to invoke @system{Windows} apps from a @system{DOS} box.

(Since the following procedure is tedious, the @system{Win3.1} stubs are already included with the 
distribution.)

To create the stubs, you'll have to manually run the @language{C} stubber (@file{cstub32w.exe})
and @language{C++} stubber (@file{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 @file{@metavar{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 @file{.isl} files. For example,

@transcript
@userinput{ -tname t1true -sname t1surrgt -hname t1hdr -cname t1comm -hdrmap test1h.map Test1.isl}
@end transcript

So in all you'll run @file{cstub32w.exe}
3 times, once for each of @file{Test1.isl} @file{Test2.isl} and @file{Test3.isl}, and @file{cpstb32w.exe}
3 times, once for each of @file{Test1.isl} @file{Test2.isl} and @file{Test3.isl}. After doing this a few
times, you will probably @emph{want} to go get @file{unixcorn}!

Note that it is normal to see a number of compiler warnings during the examples
build process.


@section Running the examples

Ensure that you have set @metavar{ILU_BINDING_DIRECTORY} as previously discussed.
The non-@system{Windows NT} examples operate just like their
@system{Unix} counterparts.  The @system{Windows} examples are simple @system{Windows} versions of the same programs.
To execute them, launch the executables (from the @system{Windows} File Manager, a command prompt (if you
are running @system{Windows NT} or 95, or
whatever), and choose the 'Run' entry from the 'Action' menu.


@section Developing Windows Applications with @system{ILU}

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.

@subsection Running the stubbers 

There are console and windowed versions of the stubbers and @program{islscan} program. The
console versions can only be used on NT. The windowed versions are meant primarily 
to be used on @system{Windows} 3.1 machines with WIN32s, although they can also be used on @system{Windows NT}.

Prior to this release, the stubbers had a number of switches as described in the @system{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. @file{test1-common.c}).  However, this does not fit the 8.3 restriction.

The new switches for the @program{c-stubber} are

@itemize @bullet
@item @var{-tname TRUEFILENAME}
@item @var{-sname SURROGATEFILENAME} 
@item @var{-hname HEADERFILENAME}
@item @var{-cname COMMONFILENAME}
@end itemize 

and the new switches for the @program{c++-stubber} are

@itemize @bullet
@item @var{-hname HEADERFILENAME}
@item @var{-sname STUBSFILENAME}
@item @var{-cname CLIENTCOMMONFILENAME}
@end itemize

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
@itemize @bullet
@item @var{-hdrmap INTERFACEHEADERTRANSLATIONFILE}
@end itemize

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 @file{@metavar{ILUHOME}\examples}) called
@file{tstcw16.bat} and @file{test1h.map} for a @language{C} based example, and @file{tstcpw16.bat} and @file{test1hh.map} for
a @language{C++} based example of the use of these new switches.

The windowed stubbers also accept an additional switch, @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
@switch{-batch} switch, the windowed stubber will pause with its window on the screen to allow
the user to view the output.  If the @switch{-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.
 

@subsection Console Applications (@system{Windows NT} only)

Ensure that @metavar{WIN32} is defined to the preprocessor when building a 32 bit @system{ILU} application.
This is normally set by default by @system{Visual C++}, but you should verify.

Link with the non-@system{Windows} (console) versions of the libraries for @system{Windows NT} console apps.
 You need
to link with the language specific runtime, the kernel runtime, and the winsock library.

Set the @system{Visual C++} 2.0 code generation compiler option to use the Multithreaded using DLL @language{C} 
runtime on @system{Windows NT}. This is @emph{very} important.

There is NO need to call @fn{ilu_StartWinsock} for a @system{Windows NT} @system{ILU} app.  (It is taken care of for
you internally in the runtime DLL process attach code). 


@subsection @system{Windows} Applications

We suggest you review and understand the test1 examples before you try to build a windowed @system{ILU} application.
This section tries to highlight some of the 
@emph{important} points.  Admittedly, the @system{Windows} examples are simple and crude as @system{Windows}
apps go, 
but they illustrate what you need to do in an application.


@subsection WINIO

@system{ILU} was originally developed for @system{Unix} machines where there is always a notion of 
standard input and output.  Error and Debug messages from the @system{ILU} runtime are
sent to standard output.  With @system{Windows NT} console applications, this same model
is present.  However with @system{Windows} 3.1 applications there is no notion of a console to 
which standard input and output can be applied (although under @system{Windows NT} you can programatically
create a console; that is not addressed here). To provide a place for the @system{ILU} runtime
to write standard output, the winio library is used.  The winio library in @system{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 @system{ILU} runtime standard output
(and yours too if you want to use a few printf's) is sent. Try setting @metavar{ILU_DEBUG} (as
described in the @system{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 @symbol{_WINIO} to the preprocessor when building a 
@system{Windows} @system{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 @metavar{WINIO_ICON}.
That is, you'll have an line in your resource file  (.rc file) like:

@transcript
WINIO_ICON              ICON    DISCARDABLE     "clnconsl.ico"
@end transcript

Your @fn{WinMain} function will also contain a call (probably before you do your @fn{ShowWindow} call)
to create the console window that looks something like:

@codeexample
winio_console(hInstance, hPrevInstance, nCmdShow, 0, "clientw Console");
@end codeexample

See the @file{WINIO.H} header file for a description of winio functionality.  For more information,
see the Microsoft Systems Journal, 1991 #4 (July-Aug), and the @system{ILU} winio source code.


@subsection @system{Windows} - NT Specific

It is very important to set the @system{Visual C++} code generation compiler
option to use the Multithreaded DLL @language{C} 
runtime on @system{Windows NT}.

Ensure that @metavar{WIN32} is defined to the preprocessor when building a 32 bit @system{ILU} application.
This is normally set by default by @system{Visual C++}, but you should verify.

Link with the @system{Windows} versions of the libraries for @system{Windows NT} @system{ILU} apps. You need
to link with the language specific runtime, the kernel runtime, the winio library, 
and the winsock library.

There is @emph{no} need to call @fn{ilu_StartWinsock} for a @system{Windows NT} @system{ILU} app.  (It is taken care of for
you internally in the runtime DLL process attach code).

In @language{C++} @system{ILU} apps, you'll be including @file{@system{Windows}.h}.  However, @file{@system{Windows}.h} includes @file{winspool.h} 
and this file #defines @fn{AddPort} as @fn{AddPortA}.  This interferes with @fn{iluServer::AddPort()}, 
so you have to undefine it (temporarily at least).  See the @file{examples\test1\cppsrvrw.cpp}
file for an example.


@subsection @system{Windows} - 3.1	Specific

@system{Windows} 3.1 applications @emph{must} call @fn{ilu_StartWinsock} before performing any @system{ILU} calls.
For @language{C} based apps this is done directly by your code.  For @language{C++} based apps, a compiler pragma
must be used to ensure @fn{ilu_StartWinsock} is called early in the static object 
initialization phase of program startup. 

Under @system{WIN32}, you never need the call to @fn{ilu_StartupWinsock} since @system{ILU}
is implemented as a DLL, and DLLs under @system{Windows NT} have an entry that allows 
things to happen when a process attaches to the DLL.  It is at that point under @system{win32}
that the winsock startup is taken care of for you.  Under @system{Wdows} 3.1, @system{ILU} is in static
libraries, and there is no such mechanism.  It isn't a problem with the @language{C} 
runtime, since the app can call @fn{ilu_StartupWinsock} before it performs any @system{ILU}
functions.  With the @language{C++} runtime however, there are some static object initializers
that make use of winsock operations (and these are run before @fn{WinMain} is even entered).
So we have to insure that @fn{ilu_StartupWinsock} is somehow called before these other @system{ILU}
initializers.  We do this by having a static initializer ourselves that causes
@fn{ilu_StartupWinsock} to be called, and we ensure that this happens before the @system{ILU}
initializers by using the Microsoft pragma @code{init_seg(lib)} (Note that the @system{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 @system{Windows} 3.1 @language{C++} @system{ILU} app, you use something like:

@codeexample
#pragma init_seg(lib)     
/* initialize winsock when under WIN16 */
int g_i_force_initializer_run = @system{ILU}_StartupWinsock ();
@end codeexample

See the @file{test1} examples, files @file{clntw.c} and @file{cppclntw.cpp}.
 	  
Use Large Memory Model for compiling / linking your 16 bit @system{Windows} 3.1 @system{ILU} apps. All the
libraries for @system{Windows} 3.1 are Large Model.  Do @emph{not} mix memory models!  This will cause
you more grief than you've ever encountered.

@code{#define} @metavar{WIN16} to the preprocessor when building a 16 bit @system{ILU} application. Note that the
compiler does not automatically define this.

Link with the static @system{Windows} versions (there are no others) of the runtime libraries,
the winio library, and the winsock library for @system{Windows} apps.


@subsection Message Loop

See the windowed test1 server examples for a simplistic timer based means of using @system{ILU}
in the presence of a @system{Windows} message loop. (@file{msgalarm.c}).  You'll want to do something
about the message loop since otherwise your @system{Windows} app won't service the GUI - it'll
just be blocked in an internal call to @fn{select()} waiting to deal with @system{ILU} activity.
This simple timer approach makes use of the ability to associate an 'alarm' function
with the @system{ILU} mainloop.  When the alarm goes off (the example uses every 500 milliseconds),
the alarm function processes any @system{Windows} messages that are waiting, then sets the
alarm for another period.
  
Note that the test1 examples were developed with Microsoft's @protocol{TCP/IP} for @system{Windows for 
Workgroups}.  Some of the behavior may be different under a different winsock implementation
(especially with respect to message dispatch during @C{select()} calls). If so, please let us
know.


@section Files in the distribution

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 @system{ILU} 2.0 becomes finalized, this list will be
corrected.

bin directory
-------------
@itemize @bullet
@item @file{c++-stubber.exe} -- console C++ stubber for NT
@item @file{c-stubber.exe} -- console C stubber for NT
@item @file{cpstb32w.exe} -- windowed C++ stubber for NT or @system{Windows} 3.1 with Win32s
@item @file{cstub32w.exe} -- windowed C stubber for NT or @system{Windows} 3.1 with Win32s
@item @file{ilu32.dll} -- kernel runtime DLL for NT console apps
@item @file{ilu32w.dll} -- kernel runtime DLL for NT window apps
@item @file{iluc32.dll} -- C runtime DLL for NT console apps
@item @file{iluc32w.dll} -- C runtime DLL for NT window apps
@item @file{ilucp32w.dll} -- C++ runtime DLL for NT window apps
@item @file{ilucpp32.dll} -- C++ runtime DLL for NT console apps
@item @file{iscan32w.exe} -- windowed ISL scanner for NT or @system{Windows} 3.1 with Win32s
@item @file{islscan.exe} -- console ISL scanner for NT
@item @file{parser32.dll} -- parser DLL for NT console stubbers 
@item @file{parsr32w.dll} -- parser DLL for NT or @system{Windows} 3.1 with Win32s windowed stubbers
@item @file{winio32w.dll} -- DLL to provide a window for stdio on NT or @system{Windows} 3.1 with Win32s
@end itemize

@noindent
lib directory

(Note unlabeled entries are the import export libraries for their 
counterparts in the bin directory)

@itemize @bullet
@item @file{ilu16W.LIB} -- kernel runtime large model static lib for @system{Windows} 3.1 apps
@item @file{ilu32.exp}
@item @file{ilu32.lib}
@item @file{ilu32w.exp}
@item @file{ilu32w.lib}
@item @file{iluC16W.LIB} -- C runtime large model static lib for @system{Windows} 3.1 apps
@item @file{iluc32.exp}
@item @file{iluc32.lib}
@item @file{iluc32w.exp}
@item @file{iluc32w.lib}
@item @file{iluCP16W.LIB} -- C++ runtime large model static lib for @system{Windows} 3.1 apps
@item @file{ilucp32w.exp}
@item @file{ilucp32w.lib}
@item @file{ilucpp32.exp}
@item @file{ilucpp32.lib}
@item @file{parser32.exp}
@item @file{parser32.lib}
@item @file{parsr32w.exp}
@item @file{parsr32w.lib}
@item @file{WINIO16W.LIB} -- Large model static lib to provide a window for stdio on @system{Windows} 3.1
@item @file{winio32w.exp}
@item @file{winio32w.lib}
@end itemize

@noindent
include directory  (header files need for building @system{ILU} apps)

@itemize @bullet
@item @file{ilu.H}
@item @file{ilubasic.h}
@item @file{iluchdrs.h}
@item @file{iludebug.h}
@item @file{iluerror.h}
@item @file{iluerrs.h}
@item @file{iluhash.h}
@item @file{iluntrnl.h}
@item @file{iluptype.h}
@item @file{iluxport.h}
@item @file{winio.h}
@item @file{winiodef.h}
@end itemize

@noindent
interfaces (or intrface on Win3.1)

@itemize @bullet
@item @file{ilu.isl}
@end itemize

@noindent
examples/timeit (currently only as console apps for Win NT)

@itemize @bullet
@item @file{client.c}
@item @file{CLIENT.MAK}
@item @file{iluNT35.MAK}
@item @file{README}
@item @file{server.c}
@item @file{SERVER.MAK}
@item @file{timeit.isl}
@end itemize

@noindent
examples/test1

@itemize @bullet
@item @file{clnconsl.ico}
@item @file{clnt.c}
@item @file{CLNT.MAK}
@item @file{clntw.c}
@item @file{clntw.ico}
@item @file{CLNTW.MAK}
@item @file{clntw.rc}
@item @file{CLNTW16.DEF}
@item @file{CLNTW16.MAK}
@item @file{clntw16.rc}
@item @file{CPLNTW16.DEF}
@item @file{CPLNTW16.MAK}
@item @file{cppclnt.cpp}
@item @file{CPPCLNT.MAK}
@item @file{CPPCLNTW.CPP}
@item @file{CPPCLNTW.MAK}
@item @file{cppsrvr.cpp}
@item @file{CPPSRVR.MAK}
@item @file{cppsrvrw.cpp}
@item @file{CPPSRVRW.MAK}
@item @file{CPSVRW16.DEF}
@item @file{CPSVRW16.MAK}
@item @file{iluNT35.MAK}
@item @file{iluWIN31.MAK}
@item @file{msgalarm.c}
@item @file{README}
@item @file{resource.h}
@item @file{srvr.c}
@item @file{SRVR.MAK}
@item @file{srvrw.c}
@item @file{srvrw.ico}
@item @file{SRVRW.MAK}
@item @file{srvrw.rc}
@item @file{SRVRW16.DEF}
@item @file{SRVRW16.MAK}
@item @file{srvrw16.rc}
@item @file{svrconsl.ico}
@item @file{t1clicom.cpp}
@item @file{t1comm.c}
@item @file{t1hdr.h}
@item @file{t1hdr.hh}
@item @file{t1stubs.cpp}
@item @file{t1surrgt.c}
@item @file{t1true.c}
@item @file{t2clicom.cpp}
@item @file{t2comm.c}
@item @file{t2hdr.h}
@item @file{t2hdr.hh}
@item @file{t2stubs.cpp}
@item @file{t2surrgt.c}
@item @file{t2true.c}
@item @file{t3clicom.cpp}
@item @file{t3comm.c}
@item @file{t3hdr.h}
@item @file{t3hdr.hh}
@item @file{t3stubs.cpp}
@item @file{t3surrgt.c}
@item @file{t3true.c}
@item @file{Test1.isl}
@item @file{test1h.map}
@item @file{TEST1HH.MAP}
@item @file{Test2.isl}
@item @file{Test3.isl}
@item @file{TSTCPW16.BAT}
@item @file{TSTCW16.BAT}
@end itemize
