View source for Windows Libraries for OS/2

[[Category:Preservation and Documentation]]
[[File:WLO_applets_on_OS2_1.3.png|400px|thumb|right|WLO 1.0 applets running on Microsoft OS/2 1.30.1]]
'''Microsoft Windows Libraries for OS/2''' (shortened to WLO) is an implementation of the Win16 API for OS/2 1.21 and higher, along with an SDK for converting existing Win16 applications to run on OS/2.

== History ==

The first version was 0.9, announced on February 4, 1991 as Microsoft Windows Libraries for OS/2 Development Kit<ref>https://web.archive.org/web/20060206232522/http://pages.prodigy.net/michaln/history/pr/wlo.html</ref><ref group="note">Wikipedia says April 2, 1987, but this is likely an error, since that pre-dates the release of OS/2 1.0 by a few months.</ref>. To make matters confusing, as is common with Microsoft, another "advanced" version named 0.9 was distrubuted on Compuserve earlier on January 1, 1991. This version is, according to Microsoft and unlike 0.9 DK, not compatible with later versions. It can be assumed that this is because both the "advanced" 0.9 and 1.0 are based on DLLs, while 0.9 was linked statically (see more in Implementation section).

Version 1.0 was released some time after that, along with a Demonstration Applications distribution (WLO10.ZIP), containing WLO DLLs and the so-called Windows 3.0 accessory applets, which are ports of Calc, Calendar, Cardfile, Clipboard, Clock, Notepad, Paintbrush, Reversi, Solitaire, Windows Help, and Write from Windows 3.0. This is the only known preserved distribution of WLO, hence most of the information in this article is derived from it, if not specified otherwise.

No later version is known to exist, and most likely it doesn't, since IBM and Microsoft parted ways later in 1991. OS/2 2.0 and later includes WinOS/2, which makes use of 386 specific features; however, WLO 1.0 still works at least up to OS/2 Warp 4.5<ref>https://web.archive.org/web/20011208005210/http://pages.prodigy.net/michaln/history/os213/index.html</ref><ref>https://www.betaarchive.com/forum/viewtopic.php?t=14196</ref>.

== Development ==

IBM mentions using PC-DOS 4.01, OS/2 SE 1.3, Microsoft OS/2 1.2 Toolkit, Microsoft C 6.00A, Windows 3.0 and the corresponding SDK, and IBM OS/2 1.3 toolkit as being used for WLO 0.9 development on their workshop machines. Re-linking with LIBMK_B.LIB, SLIBCEMK.LIB, and 0S2.LIB is all that is needed to port an Windows application to OS/2 using this version of WLO. For DLLs, library initialization source has to be modified, and SDLLCEMK.LIB linked instead of SLIBCEMK.LIB <ref name="psd">IBM Personal Systems Developer Magazine, Summer 1991, pages 32-38.</ref>.

A similar approach using just Microsoft C 6.00A and Windows 3.0 SDK on FLAGGEN, linking with Windows libraries (since no special libraries are required for WLO 1.0), works on OS/2 1.3, but it produces non-working binaries that call INT 21h.

== Implementation ==

Unlike the later WinOS/2, no virtualization is used to implement WLO. Instead, it makes use of the fact OS/2 and Windows executables have the same format, which is [[New Executable]] (NE, sometimes also called segmented executable). This is a rather complicated format, the precise description of which is out of the scope of this article. What is important here is that it contains a ''module reference'' and ''imported names'' table, which specify which modules are used by the program<ref>https://www.pcjs.org/documents/books/mspl13/msdos/encyclopedia/appendix-k/</ref>.

These are usually at the beginning of the file, hence they can be analyzed using simple string extraction:
<pre>
$ strings ie5win31.exe | head
This is a Windows self-extracting ZIP file.  You can run it from
Windows or unzip it with a utility like WinZip or PKUNZIP.$
WZ-SE-01
KERNEL
KEYBOARD
USER
</pre>
Here, the module names are KERNEL, KEYBOARD, and USER. These correspond to other New Executable files and contain functions that can be imported into and used to by the original program (more precisely, for this case these contain the functions exported by Windows itself). Windows can have various extensions here, for example on Windows 3.0, the corresponding files are KERNEL.EXE, USER.EXE, and KEYBOARD.DRV (all in C:\WINDOWS\SYSTEM), however, these are, in fact, of course all NE executables.

WLO ships its own version of these Windows modules, which are named KERNEL.DLL, USER.DLL, and KEYBOARD.DLL, and reside in C:\OS2\DLL (which is one of the default library paths, hence they will be found when launching an Windows executable). These are essentially a Windows implementation on top of OS/2 instead of DOS, making use of Presentation Manager for GUI.

When a Windows executable is launched on a OS/2 system with WLO installed, it is treated the same as an OS/2 executable linking to the aforementioned modules; if you are lucky (see the compatibility section below), it will work as expected. On WLO 0.9, relinking was necessary, but with WLO 1.0, this is no longer required<ref name="psd"/>.

== Interface compatibility ==

WLO implements the vast majority of functions in GDI, KERNEL, KEYBOARD, SOUND, SYSTEM, and USER. Currently only functions known to be missing are functions called by integral parts of Windows like Program Manager.

== Compatibility of executables ==
[[File:Stock CLOCK.EXE error under WLO.png|thumb|Trap triggered by an attempted INT 21h call from Windows 3.0's CLOCK.EXE. Note the AH value of 0x2C "Get system time".]]

Generally, Windows binaries that only use the C runtime and Windows functions should run without issue under WLO, provided they only use Win16 interfaces implemented by WLO (see above). Binaries using direct DOS calls using INT 21h or similar will trap, since this interface is not present under OS/2<ref group="note">Under real-mode Windows, these are handled by the underlying DOS directly; protected mode Windows works as a DOS extender.</ref>; DOS calls can still be accessed via KERNEL.DOS3CALL. These include stock Windows 3.0 applications like CLOCK (traps on DOS call to get time) and NOTEPAD (traps on DOS call to exit program).

Some (but not all) applications other than WLO applets display a compatiblity warning ("Application has not been tested to run compatibly on OS/2. Choose Cancel to quite or OK to proceed. If you choose OK, the application could terminate unexpectedly"). Setting OS2EXEFlags to 0x80, as done by the WLO SDK tool MARKWLO.EXE<ref>IBM OS/2 Developer's Toolkit Version 4.5 newexe.h</ref>, removes the warning (tested on [[Progress Pride Flag Generator for Windows 3.1|FLAGGEN.EXE]]).

Some applications, for example CONTROL.EXE and PROGMAN.EXE from Windows 3.0, are missing functions in DLLs, and fail with "SYS0182: The operating system cannot run %1."<ref group="note">While this is not officially confirmed to be the meaning of the error, it is heavily implied, since it is reported to happen when 1.2 DLLs are used with 1.3 code, and also happens when running 2.0 applications on 1.3.</ref>. Others, for example RECORDER.EXE, and most programs for Windows 3.1 (including PBRUSH.EXE, whose 3.0 version works), are missing DLLs, and fail with a rather generic error "Cannot find the file or directory. Be sure that the path(s) and file name(s) are entered correctly. (PMV1024)".

== Compatibility of DLLs ==

TODO: Add information from IBM PSD and do research on WLO 1.0

== Co-existing with WinOS/2 ==

On OS/2 2.0 and above, Win16 applications are run under WinOS/2, if installed. Executables with OS2EXEFlags set to 0x80 will run under WLO when launched via the command line, but will still run under WinOS/2 when launched through Workspace Shell. The WLO applets always launch with WLO, which hints at them being marked in another way in addition to OS2EXEFlags.

yksoft1 mentions in the BetaArchive post referenced earlier using a special "WLO's" stub and changing a byte to create a WLO executable from Windows 3.0 SDK examples. There is indeed a specific MS-DOS stub in the WLO applets (in contrast with their Windows 3.0 counterparts, whose MS-DOS stub only displays "Cannot be run in DOS mode"); when run in DOS mode, it prints '<executable-name>: can't open quotefile "quotes.txt"', pauses for a few seconds and exits. If quotes.txt exists, it prints its contents instead of the error mesasge. This stub somehow prevents the binary from being launched under WinOS/2; whether it is intentional is not clear.

WLO 0.9 did not have the stub, at least from what is known from the description on how a WLO 0.9 binary is created in IBM PSD.

== Static version of WLO ==

TODO: Microsoft Word and Excel for OS/2

==Notes==
<references group="note"/>

==References==
<references />