DOS HLLAPI Pass-through can be configured to enable legacy DOS applications to make HLLAPI calls to EXTRA! X-treme. This technical note explains how to configure and test the Attachmate DOS HLLAPI redirector.

Note: Use this 16-bit API at your own risk. Attachmate no longer tests this technology or provides patches or updates. For support status and alternatives, see Technical Note 2319.

What is DOS HLLAPI Pass-through?

DOS HLLAPI Pass-through enables DOS applications, originally written to communicate with DOS emulators using HLLAPI, to communicate with the 32-bit Windows emulator instead. This communication is accomplished by configuring the operating system to use an Attachmate redirector device driver. DOS HLLAPI calls are mapped to the appropriate Windows DLLs.

If your DOS application source code is unavailable, or conversion to native 32-bit operation is otherwise impractical, DOS HLLAPI Pass-through can preserve existing functionality with the EXTRA! emulator in Windows. Nonetheless, it is recommended that you migrate your applications to use modern technology as soon as possible. You should be aware of the risk associated with continued use of 16-bit technology, as it is no longer being developed, tested, or supported. For 16-bit API support status and alternatives, see also Technical Note 2319.

Verify that the Attachmate EXTRA! directory is in your system search path:

Open a DOS command prompt window (click Start > Run and enter cmd).

At the > prompt, enter PATH.

If C:\Program Files\Attachmate\EXTRA! (or equivalent) is not listed in the PATH environment variable output, add it in Control Panel > System > Advanced > Environment Variables > System variables. You may need to restart for changes to take effect.

Repeat steps b through e for each session to be assigned an HLLAPI shortname.

Click Apply and then click OK.

Update the operating system to load the DOS HLLAPI redirector file when any DOS application or command prompt window is opened. Note: If you prefer to load the redirector for specific DOS applications only, skip this step and proceed to Selective Redirector Loading.

Open the %SystemRoot%\System32\CONFIG.NT file in a text editor such as Notepad.

At the end of the file, add a device line to load HLLINIT.SYS using DOS 8.3 naming convention for the EXTRA! directory. For example:

Note: Steps 2 and 5 above vary for Windows 95 or Windows 98. On these older operating systems, the PATH is edited in Autoexec.bat, and the redirector file Redir95.vxd is added as a device line in the System.ini file [386Enh] section.

Selective Redirector Loading

On Windows XP, Windows 2000, or Windows NT 4.0, you can selectively load DOS HLLAPI pass-through support for only the specific DOS applications that require it (instead of all DOS applications).

This optional alternative can be used if your DOS application is invoked by simply double-clicking the executable (*.exe). The following steps cannot be used with batch (*.bat) files or executable command line parameters.

You must configure each DOS HLLAPI application separately. After completing the steps below, your DOS HLLAPI application(s) must be run using only the configured shortcut(s).

Verifying DOS HLLAPI Pass-through

Open the Apicalls.exe file to execute it in a DOS window. Note: If you use Selective Redirector Loading, create, modify, and open the Apicalls shortcut instead.

In the Apicalls.exe window, verify that the first line is blank (as shown in Figure 2). If text appears in the first line, it means the operating system was unable to load the redirector. Typically, this can be caused by a misspelling, or if DOS 8.3 file naming convention was not observed (when CONFIG.NT or HLLDOS.NT was edited).

If DOS HLLAPI Pass-through has been set up correctly, a splash screen may display briefly and the API return code will appear in the Apicalls.exe window. Return code 0 indicates success.

Note: For non-zero return codes, check your configuration. Return code 1 indicates the entered HLLAPI shortname is not associated with a configured EXTRA! session. Return code 9 indicates the system path is incorrect and files in the EXTRA! installation directory could not be found.