How to configure and setup a HLLAPI emulator with SecureLogin

(Last modified: 15Sep2003)

This document (10086884) is provided subject to the disclaimer at the end of this document.

fact

HLLAPI Emulator

Novell SecureLogin

symptom

How to configure and setup a HLLAPI emulator with SecureLogin

fix

SecureLogin ships with a number of predefined emulators. But many times it is necessary to use an emulator that is either not defined or is a later revision then what is included in the released product.

The purpose of this solution is to help customers to step through the process of creating a new emulator configuration with the HLLAPI interface.

HLLAPI or High Level Language Application Programmers Interface is nothing more then a set of API's that allow applications to communicate with a mainframe emulator. This set of API's allow applications to get status and read/write to the emulator window. Novell SecureLogin can work directly with any emulator that supports the HLLAPI interface. There are several different variations of the HLLAPI interface.

1. HLLAPI16 - This is the original HLLAPI interface that was included in most older DOS emulators. In basic terms this is a 16 bit interface.

2. HLLAPI - This is the newer 32 bit interface for emulators.

3. WinHLLAPI - This is the Windows interface for emulators. Most Windows emulators will support either WinHLLAPI or HLLAPI32 or both.

The first step in setting up an emulator will be to create a dummy application that the emulator will use. Right click on the SecureLogin icon in the system tray and select Manage Logins.

Next we need to ensure that we are on the Applications tab and then click on the New button.

 

 Now click on the radio button for New Application, change the Type to "Terminal Launcher", and finally enter a unique name for this application.

 Now we need to enter a script so we will know if our emulator ran successfully. Click on the Script tab and enter a MessageBox command.

Ok, Now we have our dummy application that will display a message box that says "My Emulator Ran". This will only be displayed if SecureLogin is able to launch the emulator and execute the script. The next thing we need to do is to create the emulator definition. We do this through the tlaunch utility. So click on the Start button and browse to Programs, Novell SecureLogin, Terminal Launcher.

 Click on the Edit Available Emulators button.

We now need to create a definition for our emulator. In this example we will create a definition for Quick3270. Click on the new button.

Let's first choose the emulator type. In our case Quick3270 is either a WinHLLAPI or HLLAPI program. At this point we really are not sure but a safe guess is usually to choose HLLAPI. You can consult the documentation on the emulator or try the steps below. If they fail then you can always create another definition with all 3 types to determine which one is correct.

Now we give our new emulator a name and then click the OK button.

The HLLAPI Emulator Configuration screen has multiple entries that we must provide.

Emulator Path - This is the path on the workstation to the actual emulator program.

Home Directory - This is the location where you want to program to run.

HLLAPI DLL - This is the vendors DLL file that provides the HLLAPI interface.

HLLAPI Function - This is the exported function from the HLLAPI DLL

Session Files - These are optional session files as defined by the emulator.

 Click on the browse button to the right of the Emulator Path entry to locate the emulator program.

 

 Click on the browse button to the right of the Home Directory entry to locate the path. This is typically the same directory as the emulator program.

 

Click on the browse button to the right of the HLLAPI DLL entry to locate the HLLAPI DLL. The browse window will filter on dll files so just browse to the directory that contains the emulator program. Then we need to identify the actual dll responsible for the exported HLLAPI functions. The name of the dll usually contains the word hllapi in some form. This holds true for most emulator vendors with the exception of IBM whose dll is called pcshell. If you are uncertain as to which module really provides the exported HLLAPI functions then skip this step and we will cover how to identify the exported functions.

 

If you selected the HLLAPI DLL then it will display in the correct entry. We now need to find out the HLLAPI function.

 

To find the exported function names and or identify the HLLAPI dll, we will need to utilize a 3rd party tool called Dependency Walker. You can download this tool from http://www.dependencywalker.com

Launch Dependency Walker and open the desired DLL.

 Dependency Walker will display the name of the DLL you opened in the title bar and list all of the DLL dependencies in the upper left window.

In the middle right window Dependency Walker lists the exported functions from this dll. We need to locate the function name hllapi or winhllapi. Once you have located one of these functions then you have identified the correct DLL utilized for the HLLAPI interface. Write down the name exactly as it appears in Dependency Walker.

Now in the HLLAPI Function field enter what we found in Dependency Walker. It is very important that you spell the function name correctly and use the exact upper/lower case syntax. For example Hllapi is not the same as hllapi and will cause a failure to locate the HLLAPI function.

 You may decide to create a session file for use with SecureLogin. This process will vary depending on the emulator program. But in general you configure the emulator for the type of terminal that will be emulated and the connection information.

 

 In this example, we are connecting to an AS400. So we select TN5250, the Server name/address, port, resource name, and AS400 terminal type to emulate.

Once we have these settings defined we can test to make sure that we connect to the AS400. Once this has been validated then we can save the session file.

 

 Some emulators require that you configure the HLLAPI short/long session names. With Quick3270 we define the session to be used with the HLLAPI session.

Back in the terminal launcher we now need to create a shortcut on our desktop to launch the emulator and our script. So we click on the Create Shortcut button. 

 The Tlaunch shortcut option window allows us to create the shortcut that will launch tlaunch and the configured emulator with all of the necessary configuration information.

 We want our shortcut to launch with a HLLAPI session so we select the configured HLLAPI Short Name. Then we click on the Create button.

 A new icon appears on the desktop for the new tlaunch configuration.

 When I click on the new icon I see that emulator is launched, my AS400 connection is made, and my message box is displayed indicating that my SecureLogin script ran.

To finish my emulator configuration, we just need to edit the script for the proper commands. Commands can be located in the SecureLogin scripting guide. For simplicity the below script does the following.

1. WaitForText "Sign On" - This script command will cause the script to wait until it see a screen with the text Sign On. If multiple screens have this same text then the script will attempt to execute for each screen. It is very important to find text on the screen that is unique to only the login screen. This way SecureLogin will always be able to detect the correct screen.

2. Type $Username - This script command will cause SecureLogin to send the contents of the Username variable to the Emulator. If this is the first time that the script has ran and the variable is not defined then SecureLogin will prompt the user for the correct value for the variable. When the user types in their Username then SecureLogin stores this into the Username variable for future use. The next time this script gets executed SecureLogin will read the contents of the variable and not prompt the user for their username.

3. Type @T - The script command causes SecureLogin to send a Tab key to the emulator.

4. Type $Password - This script command does the same thing as Type $Username. If the variable is undefined then SecureLogin will prompt the user for their password. Otherwise SecureLogin reads the password and then passes it on to the emulator session.

5. Type @E - This script command causes SecureLogin to send an Enter key to the emulator.

Note: It is important to remember where the cursor is located on the emulator screen prior to sending keystrokes. It may be necessary to issue a SetCursor command to position the cursor to the correct field prior to sending information. Another option might be to send Tab keys to move the cursor from one field to another. The easiest way to determine what to enter for your script is to manually launch the emulator and connect to your session. Then write down each key you must press to get logged into your session. For example on the initial connection I must press F3, then type logon, then hit tab twice, then enter username, then enter, then password, then enter. From this I could write the following script.

Type @F3

Type "logon"

WaitForText "Logon CICS"

Type @T@T

Type $Username

Type @E

WaitForText "Enter Password"

Type $Password

Type @E

For more information please refer to the scripting guide included with SecureLogin. Scripts can be used to automate your session to do many things. This might include accessing different mainframe applications/programs by scripting out the commands that you normally have to type over and over. The process is the same as the logon screen but will be identified with different keystrokes and screen text.

.

document

Document Title:	How to configure and setup a HLLAPI emulator with SecureLogin
Document ID:	10086884
Solution ID:	NOVL92365
Creation Date:	10Sep2003
Modified Date:	15Sep2003
Novell Product Class:	Novell eDirectory

disclaimer

The Origin of this information may be internal or external to Novell. Novell makes all reasonable efforts to verify this information. However, the information provided in this document is for your information only. Novell makes no explicit or implied claims to the validity of this information.
Any trademarks referenced in this document are the property of their respective owners. Consult your product manuals for complete trademark information.