Novell Documentation: Novell SecureLogin 3.51 SP2 - Enabling an Emulator Application for Single Sign-On

Enabling an Emulator Application for Single Sign-On

The main steps to enable an application include the following:

Creating a Terminal Emulation Session File

Before enabling any terminal emulator for single sign-on, you need to create a session file. This file includes the following:

All the required settings for the server to connect to.
Any other parameters required for deployment to users.

The session file can be saved locally or on the server. You configure SecureLogin to access the file in the specified location. When SecureLogin launches the emulator, SecureLogin executes this session file.

To create a session file:

Start the terminal emulator application.
Connect to the required host.
Modify the terminal emulator settings as required.
Save the session.

By default, the session file is typically saved to the application's installation directory.
From the Connection menu, select Disconnect.

The session file remains loaded, but you have disconnected from the host.
From the File menu, select Save [session name].
Quit the terminal emulator application.

Creating a Script for the Emulator Application

The following example sets up SecureLogin Terminal Launcher to single sign-on to a session using Eicon* Aviva*.

Double-click the SecureLogin icon on the task bar, click Applications, then click New.
Select New Application, type a name in the Name text box, type a description, select Terminal Launcher as the type, then click Create.
Click Script.
Ensure that Enabled is checked, type a script, then click OK.

Type screen syntax accurately in the script. Otherwise, the script won't work. Whenever possible, copy and paste from the emulator screen into the script editor window.

To find out whether Terminal Launcher is working as expected, you might want to type only a MessageBox command.

For example, type
```
MessageBox "The emulator and Terminal Launcher are working as expected."
```
Then after confirmation, enter the complete script.
Save the data and close open windows by clicking OK.

Configuring the Emulator

This section provides information on the following:

Configuring WinHLLAPI, HLLAPI, or 16-Bit HLLAPI Emulators

This section can help you configure WinHLLAPI, HLLAPI, or 16-bit HLLAPI emulators. If you select the wrong HLLAPI type, however, Terminal Launcher will fail. To find out the HLLAPI type, do one of the following:

Consult the documentation on the emulator to find out the following:
- Whether the emulator supports HLLAPI
- The type of HLLAPI that the emulator supports (WinHLLAPI, HLLAPI, or 16-bit HLLAPI)
Check the .dll files by using Dependency Walker.
NOTE: Dependency Walker won't open 16-bit.dll files.
Create a configuration for each of the three HLLAPI types.

HINT: Most HLLAPI-based emulators require you to configure HLLAPI short session names (normally A-Z) and link them with the session files or the main application. Otherwise, SecureLogin won' t be able to determine which HLLAPI session to send responses to, and it will appear that SecureLogin isn't working. This will be the case even though everything within the SecureLogin configuration is correct.

Click Start > Programs > Novell SecureLogin > Terminal Launcher.

As the following figure illustrates, Terminal Launcher displays the application that you created the script for:
Click Edit Available Emulators > New.
Type a name for the emulator, select WinHLLAPI, HLLAPI, or HLLAPI16 as the emulator type, then click OK.

Type values, then click OK.

Field	Description
Emulator Path	The directory path and executable filename of the emulator. Either type the path or use the Browse button located to the right of the text box. You can type short (8.3 format) or long filenames. Enclose long filenames in quotes (for example, "c:\Program Files\emulator").
Home Directory	The directory path to files for this emulator.
HLLAPI.DLL	The directory path to the .dll file for this emulator, along with the .dll filename. This file is in the Home directory. Typically, the filename contains "hllapi" in the name, but on occasion you need to refer to the documentation on the emulator. Validate the .dll file by using Dependency Walker (depends.exe), which is available from the Dependency Walker Web site.
HLAPPI Function	The name of the HLLAPI function contained within the hllapi.dll file. Find or validate this information by using Dependency Walker. The function is case sensitive. Enter the function name exactly as you find it in Dependency Walker.
Session Files	The session files for the emulator. Type the path and session file name. Enclose long names within quotes (for example, "C:\Program Files\Sessions\Session1.xxx").

In the Available Emulators dialog box, click Done.

Configuring a DDE Emulator

Click Start > Programs > Novell SecureLogin > Terminal Launcher.

As the following figure illustrates, Terminal Launcher displays the application that you created the script for:
Click Edit Available Emulators > New.
Type a name for the emulator, select DDE as the emulator type, then click OK.

Type values, then click OK.

Field	Description
Emulator Path	The directory path and executable filename of the emulator. Either type the path or use the Browse button located to the right of the text box. You can type short (8.3 format) or long filenames. Enclose long filenames in quotes (for example, "c:\Program Files\emulator").
Home Directory	The directory path to where the executable is located.

In the Available Emulators dialog box, click Done.

Configuring a VBA Emulator

VBA emulators support the Visual Basic* scripting language. In most cases, it is possible to write a macro for the emulator. The macro prompts SecureLogin to enter credentials.

Configuring VBA emulators to work with Terminal Launcher is a specialized field and is specific to each emulator.

VBA emulators can often be configured as Generic emulators. However, generic configuration offers limited functionality.

Click Start > Programs > Novell SecureLogin > Terminal Launcher.

As the following figure illustrates, Terminal Launcher displays the application that you created the script for:
Click Edit Available Emulators > New.
Type a name for the emulator, select VBA as the emulator type, then click OK

Type values, then click OK.

Field	Description
Emulator Path	The directory path and executable filename of the emulator. Either type the path or use the Browse button located to the right of the text box. You can type short (8.3 format) or long filenames. Enclose long filenames in quotes (for example, "c:\Program Files\emulator").
Emulator Session	The session file for the emulator. Type the path and session file name. Enclose the path and filename within quotes (for example, "C:\Program Files\Sessions\Session1.xxx").

In the Available Emulators dialog box, click Done.

Configuring a Generic Emulator

The Generic Emulator option enables you to configure SecureLogin's Terminal Launcher to interface with emulators that do not provide HLLAPI, VBA, or DDE support. Terminal Launcher interfaces with generic emulators though the Windows Clipboard by copying and pasting.

Because an emulator doesn't have to be programmed to allow external programs to interface with it, almost any emulator can be configured as a generic emulator.

Normal generic emulators have Select All, Copy, and Paste functions. These functions are most often found in the Edit menu, which is at the top of the emulator screen. However, buttons or keyboard shortcuts might be available.

Terminal Launcher uses these functions to interface with the emulator. Upon running a WaitForText command in a script, Terminal Launcher repeatedly simulates the selection of Select All, then Copy, which places the content of the emulator's screen on the Windows Clipboard. Terminal Launcher then searches the content of the Clipboard for the text it is waiting for.

If the text is not found, Terminal Launcher repeats the procedure, which usually takes about half a second.

Also, the emulator screen flickers while the WaitForText command is being executed. This is normal. See "BeginSplashScreen / EndSplashScreen" in the Nsure SecureLogin 3.51.2 Scripting Guide.

If Terminal Launcher finds the text it is looking for, Terminal Launcher goes to the next line of the script, which is most often a Type command. The Type command enters a username or password. To enter the text into the emulator, you can configure Terminal Launcher to type the text in, or to use the Clipboard.

When using the Clipboard, Terminal Launcher copies the text (for example, a username) to the Clipboard and then simulates the selection of the Paste function of the emulator. This procedure copies the text to the screen of the emulator. When using the direct typing method, Terminal Launcher simulates pressing the applicable keys on the keyboard.

The process is then repeated for the password, and the user's login to the mainframe session is complete.

Click Start > Programs > Novell SecureLogin > Terminal Launcher.

As the following figure illustrates, Terminal Launcher displays the application that you created the script for:
Click Edit Available Emulators > New.
Type a name for the emulator, select Generic as the emulator type, then click OK.

Type values, then click OK.

Field	Description
Emulator Path	The directory path and executable filename of the emulator. Either type the path or use the Browse button located to the right of the text box. You can type short (8.3 format) or long filenames. Enclose long filenames in quotes (for example, "c:\Program Files\emulator").
Host Name	The IP address, host name, or emulator session file you want Terminal Launcher to connect to or load. Occasionally, emulators require command line switches before they accept connection commands at startup. If so, include the switches in the Host Name text box. Scenario for Including a Command Line Switch: Henri is configuring a generic emulator. The emulator requires the /h switch so that the emulator can accept an IP address at startup. Henri types /h 192.168.130.222 in the Host Name text box.
Output IDs	The Control ID for the Copy function of the emulator. For information on finding Output IDs, see Finding Control IDs and Offsets of an Emulator. Some emulators allow a keyboard simulation alternative (for example, CTRL+C) instead.
Input IDs	The Control ID for the Paste function of the emulator. For information on finding Input IDs, see Finding Control IDs and Offsets of an Emulator. Some emulators allow a keyboard simulation alternative (for example, CTRL+V) instead.
Window Title	Assists Terminal Launcher in detecting the emulator window. If no Window Title is specified, Terminal Launcher might not detect the emulator opening. To find the Window Title, use Window Finder. Run Window Finder, then right-click and drag the SecureLogin icon to the title bar of the emulator. The required value will be shown as the second-from-last entry (Window Text) in Window Finder. Some emulators hide the real Window Title. There is no rule to describe which text you should enter into the Terminal Launcher configuration. (It depends on how the emulator hides it.) First, try the configuration without a Window Title specified. Next, try the text that is actually displayed in the title bar of the emulator. Finally, try the real Window Title.
Use Advanced Enter Method	Enables you to use the Advanced Enter method. This method is necessary for Lawson and StarNavigator emulators. Advanced Enter sends the \n character sequence to the emulator for the Type @E command.

In the Available Emulators dialog box, click Done.

Configuring an Advanced Generic Emulator

Advanced generic emulators have Copy and Paste functions, but do not have a Select All function.

For advanced generic emulators, Terminal Launcher follows the same process as for generic emulators, except for one difference. Instead of simulating the selection of Select All, Terminal Launcher clicks and drags the mouse cursor over the emulator screen. This procedure selects all the text that the emulator is displaying.

Click Start > Programs > Novell SecureLogin > Terminal Launcher.

As the following figure illustrates, Terminal Launcher displays the application that you created the script for:
Click Edit Available Emulators > New.
Type a name for the emulator, select Advanced Generic as the emulator type, then click OK.

Type values, then click OK.

Field	Description
Emulator Path	The directory path and executable filename of the emulator. Either type the path or use the Browse button located to the right of the text box. You can type short (8.3 format) or long filenames. Enclose long filenames in quotes (for example, "c:\Program Files\emulator").
Host Name	The IP address, host name, or emulator session file you want Terminal Launcher to connect to or load. Occasionally, emulators require command line switches before they accept connection commands at startup. If so, include the switches in the Host Name text box. Scenario for Including a Command Line Switch: An emulator requires the /h switch so that the emulator can accept an IP address at startup. Henri types /h 192.168.130.222 in the Host Name text box.
Output IDs	The Control ID for the Copy function of the emulator. Some emulators allow a keyboard simulation alternative (for example, CTRL+C) instead. For information on finding Output IDs, see Finding Control IDs and Offsets of an Emulator.
Input IDs	The Control ID for the Paste function of the emulator. Some emulators allow a keyboard simulation alternative (for example, CTRL+V) instead. For information on finding Input IDs, see Finding Control IDs and Offsets of an Emulator.
Output Offsets	For Terminal Launcher to select the text on the screen without a Select All function, Terminal Launcher needs to use the mouse to copy from the screen. Select all the text by clicking and dragging the cursor over the entire emulator screen. For Terminal Launcher to do this correctly, you need to specify how much space to allow for the toolbar and other bars when Terminal Launcher starts to drag. The Output Offset is the specified number, which tells Terminal Launcher where to start the click-and-drag process. The Output Offset is a set of two numbers, separated with a comma and no space. The numbers can be anything from zero up to tens of thousands. However, 10,000 is generally the highest number that is needed. To find the Output Offsets, you can use nslfindera.exe or trial and error. To use nslfindera.exe, download the utility from the Novell Support Web site. A text file that explains how to use nslfinder is downloaded along with the utility. TID 2965468 provides the download. Also see Finding Offsets. To use the trial-and-error method, start with high numbers (for example: 10000,10000) and work your way down. The first number is the horizontal offset, and the second number is the vertical offset. Watch where the mouse starts to click and drag. Then lower the numbers until the mouse clicks in the top lefthand corner of the emulator screen. Normally, the Output Offset number is around 500,7000 or lower. Trial and error becomes easier with experience. IMPORTANT: The offsets for an Advanced Generic emulator depend on screen resolutions. Therefore, an offset for a workstation set to 800 x 600 pixels will differ from a workstation set to 1074 x 768 pixels. We recommend that you create multiple emulator definitions for each screen resolution. The actual SecureLogin script remains the same, but you deliver a unique Terminal Launcher configuration for each different screen resolution. WARNING: If you enter the wrong offsets, SecureLogin might select undesired locations on the workstation's desktop. These locations might close, maximize, or minimize other applications, resize the Windows task bar, or perform some other unwanted task.
Startup IDs	The Control ID numbers of any functions or buttons that you want Terminal Launcher to select before attempting to log in. An example of this is a Connect button if the emulator does not automatically connect If several functions or buttons are needed, separate them with a comma.
Windows Classes	Assist Terminal Launcher in detecting the emulator window. If no Window Class is specified, Terminal Launcher might not detect the emulator opening. To find the Window Class, use Window Finder. Run Window Finder, then right-click and drag the SecureLogin icon to the title bar of the emulator. The required value is shown as the third-from-last entry (Class Name) in Window Finder.
Child ID	A Child ID is given to each child window that the main application launches. Only enter a Child ID into the TLaunch configuration if it is necessary to interact with a child window.
Window Title	Assists Terminal Launcher in detecting the emulator window. If no Window Title is specified, Terminal Launcher might not detect the emulator opening. To find the Window Title, use Window Finder. Run Window Finder, then right-click and drag the SecureLogin icon to the title bar of the emulator. The required value will be shown as the second-from-last entry (Window Text) in Window Finder. Some emulators hide the real Window Title. There is no rule to describe which text you should enter into the Terminal Launcher configuration. (It depends on how the emulator hides it.) First, try the configuration without a Window Title specified. Next, try the text that is actually displayed in the title bar of the emulator. Finally, try the real Window Title.
Use Advanced Enter Method	Enables you to use the Advanced Enter method. This method is necessary for Lawson and StarNavigator emulators. Advanced Enter sends the \n character sequence to the emulator for the Type @E command.

In the Available Emulators dialog box, click Done.

Creating a Login for an Emulator

From the list in the Available Applications pane, click the application that you want to log in to, then click Add.

To move an entry from one side to the other, you can double-click it.
Select the emulator from the Emulator drop-down list, then click Launch.

The selected application script runs, using the selected emulator.

The first time the script is run, you encounter a prompt to enter your username and password. Enter the required values, then click OK. Terminal Launcher launches the emulator, enters your username and password, and logs you in to a session.

Setting Up a Shortcut

Terminal Launcher needs to start before the terminal emulator application for single sign-on starts. Therefore, you create a shortcut that has a command to first launch Terminal Launcher and then launch the emulator application. You can deploy the shortcut to user's desktops.

The following example shows how to create a terminal launcher desktop shortcut called Simple Login. This shortcut launches and logs the user into a Jolly Giant QWS3270 Plus session.

Record the exact name given to the terminal emulator in Terminal Launcher.
Right-click the desktop, then click New > Shortcut.
Enter (or browse to) the path for tlaunch.exe.

For example, enter "c:\Program Files\novell\securelogin\tlaunch.exe". Include quotation marks.
To the end of this line, add "/auto/p[application_name]/e[emulator_name]".

For example, type
```
"/auto/pSimple Login/eJolly Giant"
```
For information on the command line switches, see Command Line Parameters Used in Terminal Launcher.

The shortcut box contains this shortcut line:

"C:\Program Files\Novell\Securelogin\Tlaunch.exe" "/auto/pSimple Login/eJolly Giant"
Click Next, name the new application shortcut, then click Finish.

When you double-click the shortcut, the shortcut launches Jolly Giant and runs the selected script.

Command Line Parameters Used in Terminal Launcher

Terminal Launcher can use the following command line parameters.

Parameter	Description
/auto	Indicates to Terminal Launcher that a following parameter will request execution of an application that is enabled for single sign-on. This parameter must be in the command line for the other command line options to work.
/b	Specifies background authentication mode.
/eemulator_name	Launches the specified emulator. You must enter the emulator name exactly as it is listed in the Emulator drop-down list.
/hhllapi_short_name	Forces Terminal Launcher to connect to the specified HLLAPI session.
/kexecutable_name	Kills the specified executable before launching an emulator.
/L	Instructs Terminal Launcher to not launch the emulator. Terminal Launcher doesn't launch the emulator but tries to run the script, assuming that the emulator has already been launched.
/m	Enables multiple (concurrent) connections to particular sessions. This parameter is required for background authentication.
/n	Launches the selected emulator without running a script. This is equivalent to checking the Launch the Emulator Only check box in the main Terminal Launcher window. This parameter doesn't function with VBA emulators.
/nnumber_1-15	Launches the specified number of sessions without running scripts. This parameter doesn't function with VBA emulators.
/papplication_name	Runs the specified application. Type the application script name exactly as it is listed in Terminal Launcher's Available Emulators drop-down list. To run several applications scripts from a shortcut at once, add /panother application name for each extra application. SecureLogin Terminal Launcher can launch up to 15 application scripts at one time, provided there are enough sessions defined for the emulator named in the shortcut dialog box.
/q	Specifies Quiet Mode (no cancel dialog).
/s	Suppresses errors.
/t	Enables unlimited timeout when connecting to an emulator.
/wprocess name	Waits until the specified process name is running before running the script.
/xparameters	Sets HLLAPI session parameters before doing the HLLAPI connect. Not for general use.

The following examples include parameters that Terminal Launcher uses:

Tlaunch.exe /auto
Creates a shortcut that launches the SecureLogin Terminal Launcher.
Tlaunch.exe /auto /eEicon Aviva /pApplication1 /pApplication2
Launches two SecureLogin Terminal Launcher application scripts. The scripts launch two sessions of Eicon Aviva, one named Application1, the other named Application2.
Tlaunch.exe /auto /pTSO
Launches the SecureLogin Terminal Launcher application script named TSO.
Tlaunch.exe /auto /n3
Launches the SecureLogin Terminal Launcher and opens three sessions. The three sessions are whichever emulator was last used with the Launch the Emulator Only option selected and then closed with the Save Settings on Exit option selected.