ShowTable of Contents
The Host On-Demand container provides access to IBM Host On-Demand applications from within a composite application. It integrates with the generic container framework provided by the platform and uses the concepts of landmarks, events and actions provided by this framework. Information about the generic container framework can be found in the InfoCenter
. The Host On-Demand container takes the screens that make up a host application, and associates each screen of interest with a landmark. These landmarks specify the actions that should occur for different screen regions in the host application and the events that should trigger the actions. Using landmarks, the Host On-Demand container allows other components in the composite application to exchange information with a host application.
The Host On-Demand container is packaged in Rational Host On-Demand version 11.0. Host On-Demand provides Java™ based, secure host access. Host On-Demand is sold as part of IBM Host Access Client Package. Host Access Client Package includes Personal Communications for traditional terminal emulation and Rational® Host On-Demand for Java™ terminal emulation.
Landmark expressions and the landmark identifier
The landmark expressions and the landmark identifier are used together to identify a particular host application screen. Each container configuration has one landmark identifer and can have zero or more landmarks, each of these landmarks has a landmark expression. The landmark identifier defines a screen region to be used for comparison against the landmark expressions, the syntax for specifying screen regions is discussed later. If no landmark identifier is defined, landmark expressions are compared against the entire contents of the screen. If there is a match the container is considered to be on that landmark.
Simple Landmark expressions
Basic form -
In its most basic form a landmark expression specifies a value to be searched for in the region defined by the landmark identifier.
Regular expression form -
To specify a regular expression the landmark expression should be prefixed with a 'regex:'.
Overriding the landmark identifier
- To override the region specified by the landmark identifier, the landmark expression should be prefixed with a '$<region>=' where <region> specifies the new region. The value following the prefix can either be in the simple form or the regular expression form.
Advanced landmark expressions
Sometimes the simple landmark expressions may not be sufficient to describe a host application screen. Richer screen descriptions can be specified using the syntax defined in the Host On-Demand macro programming guide
. These screen descriptions cannot be stored in container configuration. They must be stored externally and referenced via the landmark expression using one of the following mechanisms:
- The landmark expression should be a file URL. Eg. 'file://D:/screen1.xml'
File in a bundle/plugin
- The landmark expression should be of the form 'bundle:/<bundle-symbolic-name>/<path>' Eg. 'bundle:/test.plugin/screens/screen2.xml'.
- component preferences can be used to store base64 encoded screen descriptions. The preference name must be of the form 'hod.screen.<name>' and the landmark expression must be of the form 'screen:<name>'. This is the mechanism used by the landmark editor tab in the Composite Application Editor.
- this action is used to publish the value of a field (region of the screen)to property broker.
- this action is used to set the value of a field (region of the screen) to the value received from property broker.
– this action is used to play a recorded Macro. Macros can be recorded using the CAE tooling, this is discussed later.
– this action is used to send keystorkes to the host applications. The keystroke string uses the same syntax as the SendKeys method in the ECLPS class, refer to the Javadoc
for more information.
Supported field expressions
Fields in the Host On-Demand container are screen regions defined using one of the forms described below. The same syntax is used by the landmark identifier. When setting a field, the value may be truncated if it exceeds the size of the screen region defined by the field.
Screen regions are represented using the following forms:
- '<position>:<length>'. Eg. '1:20' or '1.1:20'.
- <upper, left position>-<lower, right position>. Eg. '1-160' or '1,1-2,80'.
Screen positions are represented using the following forms:
- '<linear position>'. Eg. '1'
Row, Column coordinate
- '<row>,<column>'. Eg. '5,10'
Understanding the tooling
The composite application editor (CAE) can be used to add the HOD container to a composite application. The user interface in CAE is augmented with tools to configure the container, record macros, quickly create landmark actions, create rich landmark expressions...
Configuring the container
The container can be configured using the 'Terminal Settings' tab of the 'Edit Component Properties' dialog. The dialog can be launched by right clicking the component in the navigator and selecting the 'Edit Component' menu item. The 'Connection' sub tab allows the user to configure the basic connection properties.
The 'Properties' sub tab allows the user to configure more advanced properties. The complete list of suported properties can be found in the Host On-Demand Infocenter
Adding an action
The easiest way to add an action is to use the container's toolbar.
1. Use the events drop down to select the events to which the action will be added.
2. Use the actions drop down to select the action to be added.
3. Use the properties combo to define a new property or select an existing property
4. Enter the field expression or drag the pointer to select a region. The text box will be automatically populated with the field expression for the selected region.
5. Click the 'Add action' button.
6. A screen descriptor for the current screen will be generated when the first action is added to a landmark. The screen descriptor will be stored in a component preference and referenced by the landmark expression. A dialog with the screen descriptor will be displayed. Give the screen descriptor a name, and optionally edit the contents, then click the 'Save' button.
7. Repeat steps 1-5 and finally click the 'Save and apply changes' button. The button will be enabled after the first action has been added.
Recording and Playing a Macro
1. Click the ‘Record Macro’ button.
2. Interact and navigate through the host application.
3. Click the ‘Stop Recording Macro’ button
4. A dialog will be displayed that describes the recorded macro. Give the macro a name and optionally edit the macro description, then click the 'Save' button. The list of saved macros can be viewed/edited in the 'Macros' sub tab of the 'Terminal Settings' tab.
5. Click the 'Play Macro' button to select and play a recorded macro.
Displaying the keypad
Click the 'Toggle Keypad' button to show the Keypad.
Displaying the OIA
Click the 'Toggle OIA' button to show the OIA.
Extending the HOD container
The Host On-Demand container’s functionality can be extending by extending it’s view class - com.ibm.rcp.composite.container.hod.view.HODAppView. The HODAppContainer instance can be accessed using the getContainer method. The presentation space can be accessed using the getECLPS method, and the terminal bean can be accessed using the getTerminal method. The Host On-Demand Infocenter
contains detailed information about the HOD APIs - .
The following example demonstrates how to publish data from a Host On-Demand container to a Symphony spreadsheet container. The Symphony spreadsheet container will receive the data and visualize it in a chart. The example requires that the following prerequisites be met.
Lotus Notes 8.5.1
Lotus Symphony feature for Lotus Notes
Composite Application Editor feature for Lotus Notes
Host On-Demand container for Lotus Expeditor/Notes
Create the composite application
1. Launch Lotus Notes.
2. Create a new local composite application by selecting File –> Application –> New Composite Application…
3. Enter a name for the composite application and ensure that the 'Open the Composite Application Editor' option is checked, then click the 'OK' button.
4. Continue to the next section once the Composite Application Editor has loaded the application.
Assemble the composite application
1. Drag the 'HOD Container' component from the Component Palette and drop it on the empty application canvas.
2. Drag the 'Symphony Spreadsheet Container' component form the Component Palette and drop it below the 'HOD Container' component in the application canvas.
Configure the Host On-Demand Container
1. Launch the 'Edit Component Properties' dialog by right clicking the 'HOD Container' component in the 'Page Navigator' on the left panel.
2. Go to the 'Terminal Settings' tab in the 'Edit Component Properties' dialog.
3. Enter a name for the 'Session Name', select ‘5250’ for the 'Session Type', and enter 'iseriesd.dfw.ibm.com' for the 'Host'. Click the 'OK' button to save and close the dialog.
4. Click the ‘Connect’ button on the toolbar to start the session.
5. Click the ‘Record Macro’ button on the toolbar to start recording. Then perform the following actions:
On the 'Sign On' screen, enter 'ATDEMO' for the 'User' and 'DEMO4YOU' for the 'Password, then press the 'Enter' key.
On the 'i5/OS Main Menu' screen, enter 'strqm' for the command, then press the 'Enter' key.
On the 'DB2 UDB for iSeries Query Manager' screen, enter '3' as the selection, then press the 'Enter' key.
Enter 'whidemo' for the 'Library' and then press the 'Enter' key.
On the 'Work with Query Manager Tables' screen, enter '5' for table 'JK_INV'. then press the 'Enter' key.
On the 'Find Data in Query Manager Table' screen, enter 'product_category' for the 'Column', 'eq' for the 'Test' and 'Sports' for the Value, then press the 'Enter' key.
6. Click the ‘Stop Recording Macro’ button on the toolbar. The ‘Create a new Macro Definition’ dialog will pop up.
7. Enter ‘Login’ for the 'Macro name' and click the 'Save' button.
8. After connecting to the server, click the ‘Play Macro’ button and select the ‘Login’ menu item to replay the previously recorded macro. The host applicaiton should return to the ‘Display Report’ screen.
9. Use the toolbar to create the following actions:
Select 'Publish' as the action, enter 'part_no' for the property, enter '8,21-16,23' for the field and click the 'Add Action' button.
Select 'Publish' as the action, enter 'part_name' for the property, enter '8,27-16,48' for the field and click the 'Add Action' button.
Select 'Publish' as the action, enter 'inventory' for the property, enter '8,55-16,58' for the field and click the 'Add Action' button.
Once complete, click the 'Save and Apply Changes' button on the toolbar.
10. Launch the 'Edit Component Properties' dialog, go to the 'Landmarks' tab and verify that the actions have been created correctly.
11. Click the 'Cancel' button to close the 'Edit Component Properties' dialog.
Configure the Symphony Spreadsheet Container
1. Enter 'Part No' in cell $A$1 cell, 'Part Name' in cell $B$1, and 'Inventory' in cell $C$1.
2. Use the toolbar to create the following actions:
Select cells A3 to A15, select 'Publish' as the action, enter 'part_no' for the property, and click the 'Add Action' button (the field should be 'A!$A$3: A!$A$15').
Select cells B3 to B15, select 'Publish' as the action, enter 'part_name' for the property, and click the 'Add Action' button (the field should be 'A!$B$3: A!$B$15').
Select cells C3 to C15, select 'Publish' as the action, enter 'inventory' for the property, and click the 'Add Action' button (the field should be 'A!$C$3: A!$C$15').
Once complete, click the 'Save and Apply Changes' button on the toolbar.
3. Select cells A3 to A15 and cells C3 to C15, then right click and select the 'Chart' menu item.
4. In the 'Chart Setup' dilaog, uncheck the 'First row as label' option and then click the 'Create' button.
5. Save the document to a local file, for example 'C:\demo.ods'.
6. Launch the 'Edit Component Properties' dialog, go to the 'Component Settings' tab, then go to the 'Initial File' preference and enter the full path of the file name specified in the previous step.
7. Go to the 'Landmarks' tab and verify that the actions have been created correctly.
8. Click the 'OK' button to save and exit.
Wiring the containers
1. Right click the 'HOD Container' component in the 'Page Navigator' and select the 'Wiring' menu item to launch the wiring page.
2. Drag the HOD Container's 'inventory' property and drop it on the Symphony Spreadsheet Contianer's ‘Set inventory’ action.
3. Drag the HOD Container's 'part_name' property and drop it on the Symphony Spreadsheet Contianer's ‘Set part_name’ action.
4. Drag the HOD Container's 'part_no' property and drop it on the Symphony Spreadsheet Contianer's ‘Set part_no’ action.
5. Click the 'Apply' button at the button right of the page.
6. Select File –> Save and Exit to apply the changes and close the Composite Application Editor.
Run the Composite Application
1. Click the 'Connect' button on the tool bar to connect to the server if it is not already connected.
2. Click the 'Play Macro' button and select 'Login' to play the 'Login' macro.
3. When the macro finishes, the query results will be published to the Symphony Spreadsheet Container and a chart will be generated using the published data.