OS/2 Warp 4: Dedicated DOS/Windows Session

By Chris Perritt

This article discusses OS/2 Warp 4's dedicated DOS/Windows session, called Trapdoor. The article offers tips for using Trapdoor's hibernate feature by itself, how to use Trapdoor for Windows 95 programs, and how to install Trapdoor on SCSI drives.

OS/2 Warp 4 provides a new dedicated DOS/Windows session, which temporarily suspends all OS/2 activity and restores the OS/2 environment when the dedicated session completes. Called Trapdoor, this session gives DOS and Windows programs complete access to the system hardware. Programs that can benefit from this new feature include DOS games and Windows 3.1 programs that do not execute properly in OS/2's DOS or WinOS2 sessions.

Although some OS/2 Warp 3.0 preloads on OEM systems have a "trapdoor" feature for running DOS and Windows games that normally would not run in the WinOS2 environment, the dedicated DOS/Windows session in OS/2 Warp 4 provides an enhanced way to perform the dual boot function to run DOS and Windows programs. When you run a DOS or Windows program in this new environment, OS/2 Warp 4 does not shut down as it does when you use dual boot, but instead hibernates to disk and resumes after you complete your dedicated session.

Trapdoor Features
Additional features in OS/2 Warp 4 include:
 * The ability to create Trapdoor icons for:
 * DOS applications
 * DOS command prompt
 * Windows applications
 * Windows 3.1 Program Manager
 * Program template with a modified Settings page that includes the Trapdoor session type
 * MIGRATE.EXE file to check the application type and set up the proper session type

Rationale
The most desirable solution for running DOS/Windows applications under OS/2 Warp is for WinOS2 to support these applications in virtual DOS machine (VDM) sessions; however, VDM sessions are often incapable of handling the large number of interrupts required to run certain games while maintaining the same look and feel that they have in a native DOS environment. Also, exclusive device ownership and similar actions are not permitted in a protected, multitasking environment such as OS/2 Warp.

In addition, using OS/2 Warp's standard dual boot feature to enter a DOS environment requires shutting down OS/2 Warp, booting DOS, and then rebooting OS/2 Warp. In many instances, this consumes too much time.

The solution in OS/2 Warp 4 is to use a hibernate/resume operation as a trapdoor to a dedicated DOS/Windows environment. This solution provides a native DOS/Windows application environment while preserving the OS/2 environment in a suspended state, thus permitting the application to execute without interfering with the OS/2 Warp environment.

Overview
The Trapdoor environment is an enhanced method of performing the dual boot operation to load and execute specific DOS and Windows applications. You start Trapdoor applications from desktop icons just as you do any other application.

When a Trapdoor application is launched, the following actions occur:
 * 1) The OS/2 Warp 4 environment is hibernated to disk.
 * 2) A DOS/Windows environment (with a CONFIG.SYS file specific for each application if necessary) is loaded and the application starts. If the application is a Windows 3.1 application, the actual Windows code is loaded and the application is launched in place of the Windows Program Manager. (A method for accessing the Windows 95 desktop is described later.)
 * 3) When the application exits, the DOS kernel calls the OS/2 loader to restore the OS/2 Warp 4 desktop.

Figure 1 summarizes the resume behavior in the Trapdoor environment.

'''Figure 2. Trapdoor Code for Windows 95 Support''' /* Set up "Trapdoor" for Windows 95 */ "boot /dos /noboot /quiet" "hybernat -r" exit

Hibernation Setup
The OS/2 Warp hibernation feature is an integral part of the dedicated DOS/Windows session support. You can access the hibernation function from either an icon on the desktop or a button in the WarpCenter.

If you don't need to access the dedicated session, you can still take advantage of the hibernation function for a fast suspend/resume operation. Rather than shutting down and rebooting, you can hibernate OS/2 Warp prior to power-off and have it resume automatically on power-up. Restoring OS/2 Warp from a hibernated state takes only about 15 seconds, as opposed to minutes required for booting the system.

To invoke the hibernate function, create an OS/2 full-screen program object that points to \OS2\SYSTEM\HYBERNAT.EXE. When you launch this program, it displays a message that indicates if the hibernation was successful and when it is safe to power-off your machine. For almost all users (with the following exceptions), the hibernate function removes the need to reboot OS/2 Warp.


 * Some device drivers may not be enabled for the suspend/resume operation and will not work correctly when the system is powered on after hibernation. You may need to reboot your system to recover these devices.
 * Ejecting a PCMCIA adapter before hibernating and then inserting it after resuming will help preserve the correct operation of the adapter.

Windows 95 Setup
Although Windows 95 is not directly supported by OS/2 Warp's dedicated DOS/Windows session, you can set up your OS/2 Warp system so that it behaves as though it supports Windows 95.

Install OS/2 Warp and Windows 95 in the same partition using dual boot. Before continuing, use dual boot to ensure everything works properly.

Next, create an OS/2 Warp full-screen program object containing the code shown in Figure 2. Set the path name to a command file such as WIN95.CMD. You can use the Windows 95 icon to access the WIN95.CMD file.

Now, simply click on the object, and OS/2 Warp will hibernate itself and boot up Windows 95. When you return from Windows 95, OS/2 Warp will quickly restore the system to its previous state.

On your Windows 95 desktop, create a shortcut to \OS2\BOOT.COM /OS2 /QUIET. Use the Advanced Program Settings push button to execute the program in MS-DOS mode. Turn off the warning message checkbox and select the checkbox to use the current MS-DOS configuration. This makes the return to OS/2 Warp as seamless as possible.

You can migrate long file names from Windows 95 to OS/2 Warp's 8.3 naming convention with extended attributes by using the Just Add OS/2 Warp utility. You can also install Windows 95 without long file name support.

User Interfaces
When you select a Trapdoor icon, a message appears informing you that Trapdoor uses a special session that suspends other applications (see Figure 3).

If you choose to continue, you will have to restart any communications sessions that were running prior to suspension. In Figure 3, the OK button is an affirmative response to the question about continuing. The checkbox preceding the second question offers you a way to turn off future occurrences of this message. If you mark the checkbox, it means you want to continue seeing this message. (There is also a checkbox to disable this dialog on the Program page in the program object's Properties notebook.)

If there is insufficient space to create the hibernation file, you are informed that the Trapdoor request has failed.

The Migrate utility sets up a previously installed application to operate in the Trapdoor environment.

The Workplace Shell program template lets you create a program object for Trapdoor applications that do not exist in the migration database.

Device Drivers
Most of the base OS/2 device drivers have been enabled to save and restore device states during hibernation and resumption. The driver should be capable of restoring the device state if the device is reprogrammed, reset, or powered off. If there is no state information, the driver need not be enabled.

Device drivers are notified to save their states using the Suspend/Resume Strategy Command, 20h - SUSPEND/RESUME. The SUSPEND command saves any device state information to memory before relinquishing control of the device. To regain control of the device, the RESUME command restores any device state information from memory.

A device driver is called with this request packet only if it has turned on the SUSPEND/RESUME support flag of the Capabilities field found in the physical device driver header.

Installation
Install Trapdoor applications in a standard dual boot environment. This lets you verify that the application works correctly in its native environment, and it allows the DOS CONFIG.SYS file to be modified without interfering with the OS/2 CONFIG.SYS file. Then use Add Programs in the System Setup folder to migrate applications.

Trapdoor applications must be installed on a File Allocation Table (FAT) disk partition, because High-Performance File System (HPFS) partitions are not accessible from DOS/Windows. (Remember that, when you are executing in the Trapdoor environment, you are running the application in its native environment.) HPFS is permitted in extended partitions for use by OS/2 Warp.

The FAT disk partition must also be located on an integrated drive electronics (IDE) disk drive. The OS/2 Warp installation program will not install the Trapdoor feature if your system does not have the FAT partition on an IDE drive.

The hibernate/resume logic uses the generic INT 13 BIOS interface to perform its functions. This logic works with many small computer system interface (SCSI) disk devices; however, some SCSI device drivers put the disk or adapter in such a state that it cannot be accessed through the INT 13 BIOS interface, thus preventing the hibernation logic from working correctly.

If you want to install the Trapdoor feature on your SCSI disk, insert the following command in the CONFIG.SYS file after the first installation phase is complete: SET TRUEMODE=1 When the first installation phase is complete, you are instructed to reboot the system. Press F3 at this point to go to a command line and edit the CONFIG.SYS file.

Note: This method will work on many SCSI systems, but it is not supported.

If you want to use Trapdoor for Windows applications, you must have already installed Windows 3.1. If you installed Windows in a directory other than \WINDOWS and you want to use the dedicated Windows session, edit the OS/2 CONFIG.SYS file and add the following line to the bottom of the file: SET WIN3DIR=C:\WIN where C:\WIN is the path where you installed Windows 3.1.

Migration
If an application will operate in a WinOS2 session, then that is how it is migrated. If it will not operate in WinOS2, then it is migrated to use the Trapdoor environment.

Windows 3.1 and Win32S applications are migrated to the WinOS2 environment. If the application does not work suitably in WinOS2, you can modify the session type from WinOS2 to Trapdoor at a later time.

A new SESSION_MODE is provided in the migration database for Trapdoor applications. It is called DOS_MODE, to emphasize that this is a special environment for DOS/Windows applications. Figure 4 shows a sample entry for a Trapdoor application in the migration database.

The application can have a specific CONFIG.SYS file defined in its default directory if necessary. Otherwise, the standard dual boot CONFIG.SYS file is used.

'''Figure 4. Migration Database Entry for a Trapdoor Application''' REM -- - REM TOP GUN	BY SPECTRUM HALOBYTE CD VERSION REM -- -

NAME		TOPGUN.EXE TITLE		TOP GUN CD Version TYPE		DOS ASSOC_FILE	SETUP.EXE DEF_DIR		\TOPGUN SESSION_MODE	DOS_MODE FOLDER		{WP_GAMES} No special AUTOEXEC.BAT file is provided because most functions, including setting environment variables, can be handled in the CONFIG.SYS file. Few applications actually need anything specific in an AUTOEXEC.BAT file that is not already supported by the Trapdoor environment's CONFIG.SYS file.

Workplace Shell
You can create a Trapdoor icon when the application is not in the migration data-base. A program template lets you fill in the necessary parameters to launch the application in the Trapdoor environment. You can also change the session type for an existing program object, e.g., from WinOS2 to the Trapdoor session type.

The Properties notebook for a Trapdoor program object (as well as any other program object) contains modifications to the following pages:
 * Program--Provides the name of the application and its working directory. This page also contains the radio button for the dedicated DOS/Windows mode and a warning message checkbox to display a reminder when launching a Trapdoor application.
 * Session--Allows selection of session type, including the new Trapdoor type. The DOS Settings page is not selectable for this session type.
 * Icon--Allows selection of an icon and title for the program object.

Boot Manager
Trapdoor is installed in a dual boot partition. Dual boot is the mechanism used to switch between the OS/2 and Trapdoor environments.

Boot Manager is a superset of this function. If Boot Manager is enabled, it prompts you to select the operating system to be booted, which can be either another operating system or an OS/2 Warp system that does not support the Trapdoor environment. When the original OS/2 Warp partition supporting Trapdoor is selected, it resumes its normal dual boot operation.

Disk Space
The hibernation file can consume an amount of disk space equal to the size of real memory. Only the physical memory pages actually in use are written to the hibernation file.

The hibernation file space is dynamically allocated and deallocated. It does not exist during OS/2 Warp operation, but the space must be able to be allocated in order to enter the Trapdoor environment.

Hibernate/Restore Operation
Hibernation captures the state of the OS/2 Warp system and the hardware and quickly saves it to disk, allowing the system to be either rebooted or powered off. When the system is rebooted or powered on, the OS/2 loader recognizes that the system was hibernated and quickly restores OS/2 to its previous state.

With hibernation, the process of running a dedicated DOS/Windows session is simply a matter of clicking on a desktop icon, running the application in a dedicated DOS/Windows environment, and returning to OS/2 Warp when the application is complete. OS/2 Warp's multitasking capabilities are suspended during this operation.

When you launch the application, which behaves as if it were a normal OS/2 Warp application, the following steps occur:
 * 1) You click on an icon representing a Trapdoor application.
 * 2) The system performs the hibernation operations.
 * 3) The DOS kernel loads using the dual boot CONFIG.SYS file. A custom CONFIG.SYS file is used if one is located in the application's working directory.
 * 4) The application loads and initiates.
 * 5) Once the application exits or the system is reset, the OS/2 Warp loader is invoked. The loader detects a hibernated system and performs the resume operation.
 * 6) When the resume operation is complete, the OS/2 Warp 4 desktop is restored to the original state from which the Trapdoor application was started.

Details
The hibernation feature performs the following functions: When the Trapdoor application exits, the DOS kernel loads and executes the OS/2 Master Boot Record. The OS/2 boot loader detects that the system has been in hibernation and loads the resume program. The resume program restores the OS/2 Warp memory image and then:
 * Evaluates the current state of the system, determining whether hibernation is feasible
 * Displays appropriate messages for error conditions, e.g., not enough disk space
 * Acquires the disk space for the hibernation file
 * Sends suspend notifications to quiesce device drivers
 * Stops thread scheduling
 * Flushes file system buffer and cache
 * Directs the hibernate-to-disk process
 * Resumes scheduling of threads
 * Sends resume messages to device drivers to restore device states
 * Frees the disk space used by the hibernation file
 * Refreshes the FAT image in memory from the FAT on disk

DOS Kernel
Using a custom DOS kernel (as opposed to any DOS kernel found in the system) provides several benefits. The main benefit is that OS/2 Warp, even though it is not running, can remain in control of the system. Some features of the custom DOS kernel and its DOS wrapper program are:
 * DOS is loaded without any messages to the screen during DOS initialization, so that invocation of the application is seamless.
 * There is no need to rearrange the boot partition. If the system is rebooted or powered off or on, the OS/2 loader restores the suspended OS/2 Warp environment.
 * When the application exits, the OS/2 Master Boot Record is loaded so that the OS/2 loader operates correctly.

Windows 3.1 Initialization
Windows 3.1 applications are launched with a replacement SYSTEM.INI file in the following steps: If the OS/2 loader finds that the Windows SYSTEM.INI file still resides in \OS2\SYSTEM (which means that the SYSTEM.INI file was not restored properly), the loader program copies the SYSTEM.INI file to the \WINDOWS directory.
 * 1) The original Windows SYSTEM.INI file is saved in \OS2\SYSTEM.
 * 2) The file is then modified so that the original SHELL=PROGMAN.EXE file is replaced with SHELL=appname.EXE.
 * 3) The original SYSTEM.INI file is replaced immediately after restoring OS/2 Warp.
 * 4) The backup copy in \OS2\SYSTEM is erased, indicating that the application is successfully initialized.

Tips
This section provides several tips for effectively using the Trapdoor techniques covered in this article.

Hibernation and Trapdoor Sessions
Consider the following before performing hibernation or launching a Trapdoor session:
 * Saving data files--When you work with applications that create files or modify data on the hard disk, it is very important to save your work often. Although hibernation remembers the state of your computer and all open files, it does not save your open files or data files to the hard disk.
 * Communication programs--You should exit any communication program before using Trapdoor. When you use Trapdoor, all communication activity is stopped. The connection to the online service or host computer is broken and typically cannot be restored. Most communication programs will detect a communication error and notify you when you return to OS/2 Warp.
 * Networks--If you are connected to a network, you should log off the network before you use Trapdoor. When you return to OS/2 Warp, log on to the network again. This helps to reduce confusion to the network server and increases computer security. Some network connections cannot be restored without rebooting OS/2 Warp.

Installing OS/2 Warp Over Windows 3.1
OS/2 Warp has always provided support for running Windows 3.1 applications. Simply install OS/2 Warp over your existing DOS and Windows 3.1 installation, and OS/2 Warp automatically migrates and runs your Windows 3.1 programs. It also sets up dual boot automatically, so you can switch between OS/2 Warp and DOS/Windows.

Installing OS/2 Warp Over Windows 95
When installing OS/2 on a system that already has Windows 95, be careful about automatically migrating programs to the Workplace Shell desktop. While OS/2 Warp can run WIN32S applications, it cannot currently run Windows 95 programs. Messages such as "DOS Error 23" and "You need a new version of WIN-OS2" mean you're trying to run a Windows 95 application that does not run under OS/2 Warp.

When installing OS/2 Warp, instead of automatically migrating all applications to your Workplace Shell desktop, choose the "Select New Programs" option. This allows you to select which programs to add. Avoid migrating any applications in the \PROGRA~1 and the \WINDOWS directory (if that's where you installed Windows 95).

Installing Windows 95 Over OS/2 Warp
If your system already has DOS, Windows 3.1, and OS/2 Warp installed in a single disk partition, you can dual boot to DOS, load Windows, and run the Windows 95 setup program. Do not install Windows 95 in the \WINDOWS directory--you'll disable OS/2 Warp's capability to run Windows 3.1 applications (because Windows 95 overwrites Windows 3.1 programs to reuse disk space). Install Windows 95 in a separate directory.

After Windows 95 is installed, it won't allow OS/2's dual boot program (BOOT.COM) to run. There are two solutions:
 * Shut down Windows 95 into MS-DOS mode, and then run \OS2\BOOT /OS2.
 * Create a PIF file to run BOOT.COM /OS2, selecting the Advanced setting of "MS-DOS mode." (See the Windows 95 Setup section earlier in this article.)