Attachmate EXTRA! Terminal Viewers HLLAPI Client
Version 8

Release Notes
February 2005

Introduction
Installation Notes
DOS-Based HLLAPI Applications
Known Issues
- Technical Information
- Limitations
Troubleshooting

Introduction

EXTRA! Terminal Viewers from Attachmate provides a HLLAPI interface to the Java Viewers to enable you to run an existing Windows-based HLLAPI client application.

Installation Notes

Supported HLLAPI Interfaces

Interface	Component
32-bit Standard EHLLAPI	ehlapi32.dll pcshll32.dll
32-bit WinHLLAPI	whlapi32.dll
16-bit Standard EHLLAPI	acs3ehap.dll
16-bit WinHLLAPI	whllapi.dll
DOS EHLLAPI

Supported Web Browsers

For HLLAPI support, the Terminal Viewers require Microsoft Internet Explorer version 6.x (or later), with the most recent Microsoft Java VM upgrade available.

Client Installation

Before running any HLLAPI-enabled configurations from the Terminal Viewers, you must install the HLLAPI components needed to run HLLAPI-enabled Terminal Viewers sessions.

To install the HLLAPI Client Components

From the Terminal Viewers myAccess Links page, select Preferences.
From the Preferences page, click Install HLLAPI Client Components.
From the File Download dialog box, select the option Run This Program from its Current Location?, and then choose OK.
When the following security warning appears, choose Yes:
Authenticode signature not found.

If you choose the option Save this Program to Disk, the message won't appear.
Follow the instructions in the installation wizard.
This setup program copies several files to your computer.

You must re-start your computer after installation is complete.

To use your HLLAPI application with a Terminal Viewers session

From the myAccess Links page, highlight and click the HLLAPI terminal session name.

The HLLAPI short name appears at the bottom of the display on the status line.

Your System Administrator specifies which configurations assigned to you will support HLLAPI, and whether the "session short-name" (used by HLLAPI to identify a particular session) is a specific letter, or the first available letter.

DOS-Based HLLAPI Applications

If you are using DOS-based HLLAPI applications with Terminal Viewers, additional configuration of your system is necessary. Choose the procedure appropriate to the version of Windows you are using.

Windows NT/Windows 2000

The HLLAPI Client Components directory must be part of the system PATH environment variable. To do so, you must edit the config.nt file.

To edit the configuration for Windows NT/Windows 2000
In Notepad, open the config.nt file. At the end of the file, add the following line: device=path\hllinit.sys ...where path is the HLLAPI Client Components directory. You must enter the path using short directory names, such as: c:\MyDire~1\hllinit.sys ...instead of: c:\MyDirectory\hllinit.sys To verify that your system is properly configured, at the command prompt, type the following and verify that HLLINIT.SYS is listed in memory: mem /c -or- Verify that HLLAPI support is enabled by ensuring that the short session name is visible on the status line.

To edit the configuration for Windows NT/Windows 2000

In Notepad, open the config.nt file.
At the end of the file, add the following line:
device=path\hllinit.sys

...where path is the HLLAPI Client Components directory.

You must enter the path using short directory names, such as:

c:\MyDire~1\hllinit.sys

...instead of:

c:\MyDirectory\hllinit.sys
To verify that your system is properly configured, at the command prompt, type the following and verify that HLLINIT.SYS is listed in memory:
mem /c

-or-

Verify that HLLAPI support is enabled by ensuring that the short session name is visible on the status line.

Windows 98

The HLLAPI Client Components directory must be part of the system PATH environment variable. To do so, you must edit the system.ini file.

To edit the configuration for Windows 98
In Notepad, open the system.ini file. Under the heading, 386enh, add the following line: device=path\redir95.vxd ...where path is the HLLAPI Client Components directory. Enter the path using short directory names, as described earlier in the procedure for editing the configuration for Windows NT/Windows 2000. Restart Windows.

Before starting your DOS-HLLAPI application in Windows 98

Once you have edited the configuration and re-started Windows, you must start the HLL95.exe program before starting your DOS-HLLAPI application.

To start the HLL95.exe program
From the HLLAPI Client Components directory, start the HLL95.exe program. A small icon shaped like a computer monitor appears on the left side of the taskbar. Start a Terminal Viewers session.

Known Issues

Technical Information

Function 104: Query/Set Window Status

Terminal Viewers HLLAPI supports the use of function 104, Query/Set Window Status to show/hide/minimize a session.

For more information on this and other HLLAPI functions, see the Attachmate EHLLAPI Language Reference, which is distributed with the EXTRA! Developer Series API SDK.

Verifying HLLAPI Support

In Microsoft Internet Explorer, in the Java Console, you can verify that HLLAPI support is enabled for a session.

To verify that HLLAPI support is enabled
In the Java Console, enter "t" (to view threads). You should see a thread named HLLAPI-A, HLLAPI-B, and so forth. -or- Verify that the short session name is visible on the status line.

WinHLLAPIStartup and WinHLLAPICleanup Functions

In addition to the standard WinHLLAPI entry point, WinHLLAPIStartup and WinHLLAPICleanup functions are supported.

Limitations

Not Supported

WinHLLAPI async and blocking functions
Functions 41-43, Start/Query/Stop Close Intercept
Functions 90-91, SendFile/ReceiveFile, except for 3270 hosts using IND$FILE
Functions 120-127, Structured Field HLLAPI
HLLAPI in Asian DBCS languages
Certain HLLAPI functions in VAX/UNIX host environments, for example, functions relating to fields or field attributes (these features exist only in IBM Mainframe or AS/400 environments)

Calls Fail when Session is Closed

When you close a session to which a HLLAPI client application is currently connected, Terminal Viewers HLLAPI sessions are released immediately and subsequent HLLAPI calls fail.

Terminal Viewers Session Must be Launched First

It is necessary to launch a HLLAPI-enabled Terminal Viewers session before attempting to use your HLLAPI application. The HLLAPI function, ConnectmyAccess Linkspace, will return 1 (INVALIDPSID) if the requested session has not been opened first.

Session Parameter WRITE Client Threads

Session parameters WRITE_SUPER (default), WRITE_READ, and WRITE_NONE allow only one client thread to be HLLAPI-connected. Parameters SUPER_WRITE and WRITE_WRITE allow multiple client threads to connect to a single session.

Troubleshooting

If a viewer configuration assigned to you by your System Administrator is set up as a specific HLLAPI-named session, for example, "A", you cannot launch two instances of this configuration and open two HLLAPI sessions named "A". The second time the configuration is launched, the viewer sees that an "A" session already exists, and HLLAPI support on the second session is disabled.

Attachmate recommends that System Administrators use the Auto Name setting when creating viewer configurations, so that each HLLAPI-enabled session that is launched is given the first available letter name, up to a maximum of 26.

If you have set up the HLLAPI Client Components correctly on your computer, but still cannot see the HLLAPI session name on the status line of your session, view the Java Console in Microsoft Internet Explorer for diagnostic messages.

You may need to re-size the terminal window for the session name to appear.
Several of the HLLAPI Client Component files have the same names as those shipped with other emulation products, for example, Attachmate myEXTRA!. To avoid conflicts, either uninstall myEXTRA! (or other terminal emulation software) before using the Terminal Viewers HLLAPI, or make certain that the directory to which myEXTRA! is installed does not appear in the PATH.

Troubleshooting Log

To aid troubleshooting, you can create a log of HLLAPI function calls.

To create a log file
In the root directory of your C drive, create an empty text file, naming it as follows: AttachmateJavaHLLAPITrace.txt Run your HLLAPI application as usual. Information about each HLLAPI call is automatically recorded to the file.

It is important to remove or delete the log file when logging is no longer desired; otherwise it will continue to grow in size each time you run your HLLAPI applications.