How to configure and setup an advanced generic emulator with SecureLogin
(Last modified: 05Dec2003)
This document (10086962) is provided subject to the disclaimer at the end of this document.
Advanced Generic Emulator
How to configure and setup an advanced generic emulator with SecureLogin
SecureLogin provides a mechanism to interface with most any emulator. This would include HLLPI, DDE, VBA, etc... For those emulators that do not support a standard interface then SecureLogin can communicate via the Windows Clipboard to the application. Any application that has the ability to Copy and Paste from the Windows Clipboard can utilize the generic or advanced generic interface method.
Generic -vs- Advanced Generic
The only difference between the Generic and the Advanced Generic is the Select all option. If your application supports a select all option then use the generic interface. If it only supports copy and paste then use the advanced generic interface.
In our example we will be setting up Quick3270 to login to an AS400 host. If we look under the edit menu we see that we have Copy and Paste. We also have a Select All option that will perform a select all. For this example we will setup Quick3270 as an Advanced Generic emulator and use only the copy and paste functions.
We must first create a dummy application that we will later modify to include our mainframe script. Right click on the SecureLogin icon in the system tray and select Manage Logins. Within the Manage Logins window click on the Applications tab. And finally click on the New button to create a new application.
Click on the New application radio button and then select the type "Terminal Launcher". Also provide a unique name for this application. In our example we will call this application "My Advanced Generic Emulator". Finally, click the Create button to create the application.
Click on the Script tab and enter a MessageBox command so that we can determine when our emulator launched. We will change this script later after we have successfully configured the Advanced Generic emulator. Click the OK button to complete this process.
Now we are ready to create the advanced generic emulator definition. We do this from with the terminal launcher (tlaunch) utility. Click on the Start menu and browse to Programs/Novell SecureLogin/Terminal Launcher.
We must first create the emulator definition so click on the Edit Available Emulators button.
Terminal Launcher will provide a list of currently defined emulators. A large number of emulators are already defined in SecureLogin. You may scroll through the list to see if one is already defined for the emulator you are trying to configure. For our example we will be adding a new definition for Quick3270. Click on the New button to create a new emulator.
Select the Emulator type of Generic and give it a unique name. In our case we will call this "Quick3270 Advanced Generic".
We need to identify several items for an Advanced Generic emulator.
1. Emulator Path - This is the path to the program.
2. Host Name - This is an optional field to pass a host name or address to the application. This field may or may not work with all emulators since it is passed as a command line option.
3. Output ID's - This is the Windows control ID of the Copy function in the edit menu. (Covered below)
4. Output Offsets - This is the location of the screen to perform our copy function. Since there is no Select All function with this type of emulator, SecureLogin positions the mouse pointer over the first text area of the emulator screen. This would normally be Row 0 Column 0. It then performs a click and drag to the bottom right of the applications screen. This is simulating the select all by marking the complete screen from the top to the bottom of the window. This value tells SecureLogin where the offset is for Row 0 Column 0. The offset is calculated from the top left of the title bar to the start of the emulator display window. (Covered below)
5. Startup ID's - 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.
6. Window Classes - This is the window class reported by the Window Finder tool. (Covered below)
7. Child ID's - This is the child ID's reported by the Window Finder tool. This is normally not needed unless the emulator spans a child window. (Covered below)
8. Window Title - This is the Title of the Window as reported by the Window Finder tool. (Covered below)
9. Use Advanced Enter Method - This checkbox tells SecureLogin to send a \n instead of the default \r\n character sequences for an Enter key.
So we first browse to the Quick3270 application by clicking the browse button to the very right of the Emulator Path field. If the path as in our example contains a long name with a space, then change the value to represent a short name. For example Program Files would be progra~1 instead. So we change our path to c:\progra~1\quick3270\quick3270.exe.
Now we need to find the Input and Output ID's of the emulators Copy and Paste functions. To do this we need to use a 3rd party tool called Winspector. If you have Microsoft's development tool SPY++ you can use it as well. Winspector is a free tool you can download from the Internet at http://www.windows-spy.com/.
Winspector will display all of the Windows system messages and is very configurable. We will need to configure Winspector so that it only displays the information we want to see. First download and install Winspector on your workstation.
With Winspector running launch your emulator. Within the Window List box of Winspector click on the Gun sight icon with the text "Click and drag to select a window" and drag it over the emulator title bar. Winspector will highlight the emulator box and display information about the emulator window in the upper left corner.
Now that the emulator has been selected we just need to trap for the messages being sent to the emulator window. Scroll down the Window list until you find the application, then right click on the application and select "Messages".
The messages window will now be displayed in the right pane. We now need to tell Winspector what messages we want to see.
Right click anywhere in the Messages window and select the option Edit message filter.
By default Winspector is not filter any messages. We want to filter all of the messages and then only display the one we want to see.
Click on the Filter all button.
Now we only want to see WM_COMMAND messages so we double click on the WM_COMMAND to move it to the unfiltered window on the right. Then we can click OK to return to the Messages window.
We only want to see the messages sent to the emulator window so right click on the Messages window and uncheck the option "Show return values".
Now in the emulator select the edit menu and then copy to get the ID for the copy menu option.
The Copy function is ID 4102.
Perform the same steps for the Paste operation and we see that the Paste function is ID 4103.
Enter the ID's that we found into the emulator configuration of Terminal Launcher.
Now we need to find the Output Offsets. To do this we need another tool called the Advanced Generic Offset Finder or AGOffsetFinder.exe. You can download the file called nslfindera.exe from Novell's support website.
The Offset Finder tool gives instructions on each step to identify the correct offsets. You can also click on the button with the "?" to see a graphical view.
Perform the steps as outlined by launching the emulator, placing the mouse pointer over the top left of the emulator window (in the title bar), and then press the Control key and the Left arrow key at the same time. You will see that numbers will appear in the Start field. Then place the mouse pointer over the top left of the text area and press the Control key and the Right arrow key at the same time. You will see numbers appear in the remaining End and Offset fields. The data that appears in the Offset field is what we need to use in our Terminal Launcher configuration.
Enter the Offset information in to our Advanced Generic emulator configuration.
Important: Offsets are a calculation of pixel width and height. The number of pixels change when you change screen resolution. So offsets will also change. For example an offset based on the screen resolution of 640x480 will be different from the offset of a screen resolution of 1024x768. You will most likely want to create emulator definitions for each screen resolution that your users might be using. If you have standardized on one specific screen resolution then you will only need to create the emulator definition for that screen resolution. This issue only exists with the Advanced Generic emulator.
Now we must find the Startup ID, Window Classes, Child ID and Window Title. All of these can be located with the Window Finder tool included with SecureLogin. Click on the Start menu and browse to Programs/Novell SecureLogin/Window Finder
Right click on the SecureLogin Icon in the Window Finder tool and drag it over the emulator title bar.
Copy the text from the Window Text field and paste it into our Terminal Launcher configuration. Only enter enough information to identify the application. This is what triggers SecureLogin to launch the script.
Click the Ok button and we have completed the definition of our Generic emulator. Now all we should have to do is test our configuration. From the Terminal Launcher main window we select our application "My Advanced Generic Emulator" and then select the Emulator "Quick3270 Advanced Generic" and finally click the Launch button.
The emulator should be launched and we should see our message box indicating that our script ran.
We can also have the Terminal Launcher create an Icon on the desktop that will launch the emulator. From the Terminal Launcher main screen select the application and emulator as we did before, but instead of clicking on the Launch button, click on the Create Shortcut button. Then from the TLaunch Shortcut Options window click on the Create button.
A new icon should now appear on the desktop.
All that needs to be done now is to edit our script for this application. Right click on the SecureLogin icon in the system tray and select Manage Logins. Then scroll to the "My Advanced Generic Emulator" application from the Applications tab. Finally click edit.
Enter the host script as if you were typing directly into the emulator. For example if you must press the tab key twice before entering your user name then use SendKey "\T\T". Note that the SendKey function is available for Generic and Advanced Generic emulators. For other emulators just use the normal Type command. For more information on script commands refer to the scripting guide included with SecureLogin.
In the below example we Remarked out the MessageBox command with a "#" or pound symbol.
WaitForText "Sign On" - Tells SecureLogin to wait until the words Sign On are located in the emulator text.
Type $Username - Tells SecureLogin to type the contents of the variable Username to the emulator. If Username is undefined SecureLogin will prompt for a value.
SendKey "\T" - Tells SecureLogin to send one tab key.
Type $Password - Tells SecureLogin to type the contents of the variable Password to the emulator. If Password is undefined SecureLogin will prompt for a value.
SendKey "\N" - Tells SecureLogin to send the enter key.
Note: You will see that the emulator screen will flash while it is performing the select all and copy functions looking for the sign on screen. This is normal since the emulator reverses the colors of the screen when text is marked for copy and paste. But this can be eliminated in one of two ways.
1. You can always configure the emulator to not invert the colors when data is copied and paste.
2. You can use the SecureLogin commands BeginSplashScreen and EndSplashScreen.
SecureLogin will now display the SecureLogin screen while we are waiting on the host screen to update. This way the flashing no longer occurs.
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.