Technical Notes

Programmatically Controlling Reflection for the Web Embedded Sessions
Technical Note 1773
Last Reviewed 30-May-2008
Applies To
Reflection for the Web 2008 (All Editions)
Reflection for the Web version 8.x through 9.x
Summary

This technical note describes how to programmatically control Reflection for the Web sessions embedded in browser windows. The note outlines three different methods using JavaScript and the Reflection for the Web application programming interface (API) to control Reflection.

In addition, custom Jscript, VBScript, Java applets, and Java applications can use the Reflection for the Web (API) to control Reflection applets. For more information about the Reflection for the Web API, see the "Scripting with the Reflection API" section in the Administrative WebStation.

Note: This note covers Reflection sessions embedded in a browser window. For information about controlling framed (out-of-browser) sessions, see Technical Note Number 1776.

Available Methods for Programmatically Controlling Sessions

This note outlines three methods for programmatically controlling Reflection for the Web embedded sessions using JavaScript to access the Reflection for the Web API. Attachmate Technical Support recommends using Method 1 (below), which uses protected, dynamic sessions rather than static or unprotected sessions.

Term Definitions

The following terms are used throughout this document.

Dynamic sessions are created when a session is requested. These sessions are not associated with a physical HTML file on the web server. This is the default session type in Reflection for the Web. All dynamic sessions are protected sessions.

Static sessions are associated with an HTML file located on the web server. Static sessions can be either protected or unprotected sessions.

Protected sessions are only indirectly accessible from a web server. The request for a protected session goes through the Reflection for the Web authentication and authorization process before it is served.

Unprotected sessions are accessed by direct URL addresses and do not take advantage of the Reflection for the Web authentication and authorization process.

Summary of Available Methods

The following is a summary of the three available methods and their possible advantages and disadvantages. Specific configuration details are provided in subsequent sections.

Programmatically Controlling Protected Dynamic Sessions

We recommend using this method. Protected, dynamic sessions take full advantage of Reflection for the Web's features, including Reflection Server management and access control. Using this method, you can use an IFRAME tag to incorporate JavaScript into your dynamic Reflection sessions.

Possible disadvantage:

Both the session name and the HTML file name appear in the Reflection links list. For example, <Mainframe name>.html.

View details: Method 1: Programmatically Controlling Protected Dynamic Sessions with an IFRAME Tag

Programmatically Controlling Protected Static Sessions

Use this method if your Reflection sessions are protected, static sessions.

Possible disadvantages:

• The name of the HTML page is displayed in the links list. For example, <Mainframe name>.html.
• The Administrative WebStation cannot maintain the session.

View details: Method 2: Programmatically Controlling Protected Static Sessions

Programmatically Controlling Unprotected Static Sessions

Use this method if your Reflection sessions are unprotected, static sessions.

Possible disadvantages:

• The Administrative WebStation cannot maintain the session.
• Client Authorization has to be disabled in the Security Wizard for secure sessions to function. (This process is detailed in the last section that describes Method 3.)
• Users have to be directed to specific URLs for sessions.

View details: Method 3: Programmatically Controlling Unprotected Static Sessions

API Syntax for getAPI

The Reflection for the Web server generates HTML applet tags for all sessions using the Launcher (com.wrq.rweb.Launcher) applet, and the Launcher applet launches child Reflection emulation applets. With this launching methodology, the Launcher getAPI() method is needed to reference specific Reflection emulation child applet sessions. The syntax for the getAPI() Launcher method is getAPI("JSAPI", "<session_name>").

Example (VT session):

The first parameter is the API type you want to use, and the only API available at this time is the JavaScript API named "JSAPI." The second parameter assigns the getAPI() to the Reflection session you want to control. Generally, the session_name is the launcher.sessions value. Below is a list of launcher.sessions values for all of the Reflection for the Web emulations. (Alternatively, you can view the source of Reflection for the Web applet web pages and look for the "launcher.sessions" parameter name.)

Launcher.session Values

HP
IBM3270
IBM3287	for IBM 3270 printer sessions
IBM5250
IBM3812	for IBM 5250 printer sessions
IBM5250Xfer	for AS/400 data transfer sessions
VT

However, when controlling protected dynamic sessions with an IFRAME tag, the portal=true argument is typically used within the IFRAME tag to avoid refreshing the entire HTML page with a new Launcher applet session. This allows you to embed a Reflection session within existing HTML content. When using the portal=true argument, the literal session name as it appears in the links list is used for the getAPI session_name value.

Method 1: Programmatically Controlling Protected Dynamic Sessions with an IFRAME Tag

You can incorporate JavaScript into your dynamic sessions by using an IFRAME tag, which creates an inline frame containing the Reflection session. Follow the steps below to control protected, dynamic Reflection for the Web sessions.

1. To access the Reflection for the Web Administrative WebStation, follow these steps:
   1. In your web browser, access the Reflection for the Web links list page (where your available Reflection for the Web sessions are listed) at:

2. Log on with your administrator password and click the Administrative WebStation link.
2. In the Administrative WebStation, open the Session Manager tool and either open an existing terminal session or create a new terminal session. In Session Manager, click the Applet Parameters button in the "Configure a Web-Based Reflection Session" screen. Select the preloadJSAPI applet parameter from the Parameter drop-down list and type true for the value. Then, click Add, Continue, and Save Settings.
3. On the Reflection links list page, locate the terminal session you want to add to the web page you are creating. Make a note of the name. You will use the name in step 4 to define the "URL session name".

4. Create an HTML/JavaScript file, similar to the sample below, which contains an IFRAME tag (to include the dynamic Reflection for the Web session), JavaScript, and Reflection for the Web API code. In the following sample script, [literal session name] is the verbatim name that appears in the links list (for example, "Sales Data", not Sales*u0020Data), and [URL session name] is the link name you noted in step 3 above (for example, Sales*u0020Data).

5. Save the HTML file to the \ReflectionData\deploy directory. In a Windows installation of Reflection, the default path to this folder is

• If you choose to save the file to a folder other than "C:\Program Files\ReflectionServer\ReflectionData\deploy," Microsoft Internet Explorer may automatically block scripting with the session. For security reasons, the Microsoft browser does not allow scripting the contents of an IFRAME when the source of the IFRAME document is from a different domain than the main part of the html file. For more on this Internet Explorer security restriction, see http://msdn.microsoft.com/workshop/author/om/xframe_scripting_security.asp?frame=true
• If you want to add external elements (for example, graphic files) to the above example, the content must be placed in web-addressable space outside of the deploy directory. In a default Windows installation of Reflection for the Web, this includes the following directory and any subdirectories, except for the WEB-INF directory and any subdirectories:

6. Re-access the Reflection for the Web links list page. You will now see two links for the session you have been configuring, one named <session name> (the non-customized session), and the other named <session name>.html (the customized session). Click <session name>.html.

Method 2: Programmatically Controlling Protected Static Sessions

Follow the steps below to create a protected static Reflection for the Web HTML page and add any desired scripting code to the page.

1. To access the Reflection for the Web Administrative WebStation, follow these steps:
   1. In your web browser, access the Reflection for the Web links list page (where your available Reflection for the Web sessions are listed) at:

2. Log on with your administrator password and click the Administrative WebStation link.
2. In the Administrative WebStation, open the Session Manager tool and follow these steps:
   1. Select an existing terminal session or create a new terminal session to programmatically control.
   2. Click More.
   3. Select an appropriate browser type for your environment.
   4. Find the HTML applet code at the bottom of the page.
   5. Select all the HTML code. (In a Windows environment, press Ctrl+A on your keyboard.)
   6. Copy the code. (In a Windows environment, press Ctrl+C on your keyboard.)
3. Open an HTML editor of your choice and paste the clipboard data into a new HTML document.
4. Edit the HTML page, adding any desired scripting code directly to the page. See the HTML/JavaScript example below for a VT session.

5. Add a preloadJSAPI applet parameter to the above code and make the value true. See the example below:

6. Save the static Reflection for the Web HTML page to the \ReflectionData\deploy directory. In a default Windows installation, the path to this folder is

7. In the Session Manager, if you launched the Reflection for the Web session and saved settings, copy the Reflection session's confXXXXX.zip file from \ReflectionData\deploy\dyncfgs to \ReflectionData\deploy. If you're unable to determine which confXXXXX.zip file belongs to the session you saved in step 5 above, view the HTML applet source as described in step 2 above and find the confXXXXX.zip value in the below applet parameter.

8. Re-access or refresh the Reflection for the Web links list page. You will now see the new link for the session you have been configuring, <session name>.html. (If a non-customized version of this session exists, you will see a second link called <session name>, with no extension. This is the non-customized session.) Click <session name>.html.

Method 3: Programmatically Controlling Unprotected Static Sessions

Follow the steps below to create an unprotected static Reflection for the Web HTML page and add any desired scripting code to the page.

Note: This method is not an option if you are using an evaluation version of Reflection for the Web with secure sessions configured to use the Reflection for the Web security proxy. An evaluation version, configured in this manner, will display an error stating that the evaluation copy expired on January 1, 1970.

1. To access the Reflection for the Web Administrative WebStation, follow these steps:
   1. In your web browser, access the Reflection for the Web links list page (where your available Reflection for the Web sessions are listed) at:

2. Log on with your administrator password and click the Administrative WebStation link.
2. In the Reflection for the Web Administrative WebStation, open the Session Manager tool and follow these steps:
   1. Select an existing terminal session or create a new terminal session to programmatically control.
   2. Click More.
   3. Select an appropriate browser type for your environment.
   4. Find the HTML applet code at the bottom of the page.
   5. Select all the HTML code. (In a Windows environment, press Ctrl+A on your keyboard.)
   6. Copy the code. (In a Windows environment, press Ctrl+C on your keyboard.)
3. Open an HTML editor of your choice and paste the clipboard data into a new HTML document.
4. Edit the HTML page, adding any desired scripting code directly to the page. See the below HTML/JavaScript example for a VT session.

5. Add a preloadJSAPI applet parameter to the above code and make the value true. See the example below:

6. Save the static Reflection for the Web HTML page to the <path to Reflection for the Web application context>\session directory. In a default Windows installation, the path to this folder is

7. In the Session Manager, if you launched the Reflection for the Web session and saved settings, copy the Reflection session's confXXXXX.zip file from \ReflectionData\deploy\dyncfgs to <path to Reflection for the Web application context>\session. In a default Windows installation, the paths to these folders are

8. In your web browser, access the session directly:

Security Note

Since static, unprotected sessions don't use the Reflection for the Web management server to manage sessions, the Security Proxy client authorization feature (which uses tokens) is not supported, so client authorization must be disabled. After client authorization is disabled, a unique proxy and port must be defined for each host you access. (For details on enabling and configuring the Security Proxy Server, use the Search feature in the Administrative WebStation.) Once the Security Proxy Server is enabled, follow the steps below to turn off client authorization. (Note that beginning in Reflection for the Web 2008, the Security Proxy Server is not included in the Standard Edition.)

1. Start the Security Proxy Server Wizard. (For automated Windows installations: Start > Programs > Reflection for the Web > Utilities > Security Proxy Wizard. For other environments: See the section titled "Running the security proxy" in the Reflection for the Web Installation Guide > Configuring Components > Security Proxy Server.) This opens a Security Proxy Wizard dialog box.
2. On the Status tab, select your server.properties file.
3. On the Advanced Settings tab, clear the "Client authorization" check box.
4. Click Save.
5. On the Proxies tab:
   1. Click Add or Modify and define Local port, Remote host, and Remote port for each host connection.
   2. When prompted to "Export Settings to Management Server," click Export.
   3. Click Export Settings at the bottom of the Proxies tab.
6. Exit the Security Proxy Wizard.
7. Restart the Security Proxy.
8. Create new secure Reflection for the Web sessions or modify existing sessions to use the new proxy settings defined in step 5 above.

Related Technical Notes

1776	Programmatically Controlling Reflection for the Web Framed Sessions
2183	Developer Tools for Attachmate Products
9988	Reflection for the Web Technical Notes