Attachmate Worldwide  |   Contact Us  |   The Attachmate Group
Extend. Manage. Secure. More than 30 years in the business. Over 65,000 customers.

Technical Notes

Configuring DOS HLLAPI Pass-through with EXTRA! X-treme
Technical Note 2357
Last Reviewed 06-Jun-2008
Applies To
EXTRA! X-treme version 8.0 or higher
EXTRA! X-treme Options Pack
Summary

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.

This technical note contains the following sections:

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.

Although DOS HLLAPI pass-through functionality has been available for EXTRA! since version 6.10, this technical note is oriented towards the latest EXTRA! versions 8.0 and higher. For information on supported EXTRA! product versions, see also the Product Support Lifecycle at http://support.attachmate.com/programs/lifecycle/version-status.html?extra.

Information in this technical note was previously published as Attachmate SupportWeb Technical Bulletin 201 (TB201 published October 2002).

Setting up DOS HLLAPI Pass-through

To enable DOS HLLAPI Pass-through on Windows XP, Windows 2000, or Windows NT 4.0, complete the following steps.

  1. After installing EXTRA! X-treme, install the Options Pack.
    • Version 9.x: To download the Options Pack for version 9.x, see Technical Note 2142.
    • Version 8.0: Open the \EXTRA!OptPack\EXTRA!_Option_Pack directory on your EXTRA! X-treme 8.0 product CD (or CD #2 in EXTRA! Mainframe Server Edition version 8.0 or 8.1).
  1. Verify that the Attachmate EXTRA! directory is in your system search path:
    1. Open a DOS command prompt window (click Start > Run and enter cmd).
    2. At the > prompt, enter PATH.
    3. 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.
  2. Configure and save one or more EXTRA! session(s).
  3. Assign HLLAPI shortname(s) to configured session(s):
    1. In an EXTRA! session, click Options > Global Preferences > Advanced.
    2. Select a desired shortname from the list (A - Z).
    3. Click Browse.
    4. Select the session to which this shortname will be assigned.
    5. Click Open.

Tip: Make a note of the shortname association; later, you will need to enter it when Verifying DOS HLLAPI Pass-through, or to configure your DOS HLLAPI application.

    1. Repeat steps b through e for each session to be assigned an HLLAPI shortname.
    2. Click Apply and then click OK.
  1. 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.
    1. Open the %SystemRoot%\System32\CONFIG.NT file in a text editor such as Notepad.
    2. 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:
device=C:\Progra~1\Attach~1\EXTRA!\HLLinit.sys

Note: To determine DOS 8.3 short names, use dir /x commands in a DOS command prompt window.

    1. Save the updated CONFIG.NT file and exit the text editor.
  1. Proceed to Verifying DOS HLLAPI Pass-through to test your configuration.

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).

  1. Complete steps 1 through 4 in the previous section Setting up DOS HLLAPI Pass-through.
  2. Copy AUTOEXEC.NT from %SystemRoot%\System32 to the EXTRA! program files folder, and rename the file HLLDOS.BAT.
  3. Copy CONFIG.NT from %SystemRoot%\System32 to the EXTRA! program files folder, and rename the file HLLDOS.NT.
  4. Edit the HLLDOS.NT file to load HLLINIT.SYS. (The original system CONFIG.NT should not load HLLINIT.SYS.)
    1. Open the HLLDOS.NT file in a text editor such as Notepad.
    2. 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:
device=C:\Progra~1\Attach~1\EXTRA!\HLLinit.sys

Note: To determine DOS 8.3 short names, use dir /x commands in a DOS command prompt window.

    1. Save the updated HLLDOS.NT file and exit the text editor.
  1. For each DOS HLLAPI application (including Apicalls.exe), complete the following steps:
    1. In Windows Explorer, right click the DOS HLLAPI application *.exe file, and click Create Shortcut.
    2. Right-click the new shortcut icon, and click Properties.
    3. On the Program tab, in the Working field, enter the EXTRA! directory, such as "C:\Program Files\Attachmate\EXTRA!".

Note: Some applications require disabling Close on exit.

    1. Click Advanced (on Windows XP or Windows 2000) or Windows NT (on Windows NT 4.0). The Windows PIF settings dialog box displays.
View Full Size
Figure 1. Windows PIF Settings dialog box (steps 5.d. through 5.g.)
Figure 1. Windows PIF Settings dialog box (steps 5.d. through 5.g.)
    1. In the Autoexec filename field, type the path to the HLLDOS.BAT file (from step 2 in this section).
    2. In the Config filename field, type the path to the HLLDOS.NT file (from step 3 in this section).
    3. Click OK to save and close Windows PIF Settings.
    4. Click OK to save and close Properties.

To run each DOS HLLAPI application, double-click the shortcut icon. Note: Your DOS HLLAPI application(s) must be run using only the configured shortcut(s).

Verifying DOS HLLAPI Pass-through

To verify the operability of DOS HLLAPI Pass-through, perform the following steps.

  1. Download and save the test program Apicalls.exe.
  2. 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.
  3. 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).
View Full Size
Figure 2. Apicalls.exe running in a DOS window
Figure 2. Apicalls.exe running in a DOS window
  1. In the Apicalls.exe window, at the Enter the function code prompt, input 1 (for Connect) and press Enter.
  2. When prompted for a Session ID, enter a HLLAPI shortname previously associated with a session (configured earlier in step 4 of Setting up DOS HLLAPI Pass-through).
  3. 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.

View Full Size
Figure 3. Apicalls.exe Connect successful return code
Figure 3. Apicalls.exe Connect successful return code
  1. Press any key to return to the function code prompt. Input 5 (for Copy Entire PS) and press Enter.
  2. You should see host terminal text from the sessionís presentation space displaying in the DOS window.
View Full Size
Figure 4. Sample Apicalls.exe display of host screen
Figure 4. Sample Apicalls.exe display of host screen
  1. Press any key to return to the function code prompt. Input 21 (for Reset System) and press Enter.
  2. Press any key to return to the function code prompt. Input 0 (for Exit) and press Enter. If the Apicalls.exe window does not automatically close, click the upper-right X.
Related Technical Notes
2142 EXTRA! 9.x Options Pack and Connections Pack
2164 EXTRA! Developer Tools: API Code Samples and Manuals
2183 Developer Tools for Attachmate Products
2319 Support Status of 16-bit API Options in EXTRA! X-treme

horizontal line

Did this technical note answer your question?

           


Need further help? For technical support, please contact Support.