Introduction to the HOD container in composite applications 

The Host On-Demand (HOD) container provides access to host applications from within a composite application. A host application is a series of screens and landmark expressions are used to identify these screens. The container provides the means to publish and receive information to and from a region of the screen. In this article, Reader will get familiar with HOD (Host on Demand) container, then work through the creation of HOD container and demonstrate how HOD container reacts with other container. Before getting starting with the HOD container concept, you can refer to this link for generic concept of container InfoCenter

Supported field expressions

Fields in the HOD container are screen regions defined using the syntax of “Positions” and “Regions”, which would be described below soon. Be noticed that when setting a field, the value may be truncated if it exceeds the size of the screen region defined by the field.

'. E.g. '1'
2. Row, Column coordinate - ','. E.g. '5,10'
Regions:
Screen regions are represented using the following forms:
1. Linear region - ':'. E.g. '1:20' or '1,1:20'.
2. Rectangular region - -. E.g. '1-160' or '1,1-2,80'.

Supported actions

Publish - this action is used to publish the value of a field to property broker.

Receive - this action is used to set the value of a field to the value received from property broker. This action will work only if the document is being edited.
Play Macro – this action is used to play recorded Macro. A recorded Macro can be created from CAE tooling. See below section from details on how to create a Macro.
Send Keystrokes – this action is used to do operation(s) associated with this action.

Supported landmark identifiers

The landmark identifier defines a screen region to be used for comparison against landmark expressions. If no landmark identifier is defined, landmark expressions are compared against the entire contents of the screen.
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 '$=' where 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 screen. Richer screen descriptions can be specified using the syntax defined in the HOD macro programming guide - InfoCenter. These screen descriptions are not stored in the container configuration. They must be stored externally and referenced via the landmark expression using one of the following mechanisms:
1. External file: The landmark expression should be a file URL. Eg. 'file://D:/screen1.xml'
2. File in a bundle/plugin: The landmark expression should be of the form 'bundle://'Eg. 'bundle:/test.plugin/screens/screen2.xml'.
3. Component preference: component preferences can be used to store base64 encoded screen descriptions. The preference name must be of the form 'hod.screen.' and the landmark expression must be of the form 'screen:'. This is the mechanism used by the landmark editor tab in the Composite Application Editor.

Understanding 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 record macros and quickly create landmark actions.

Before exercise below tooling, we need to configure terminal setting. Opening Component editor dialog by right clicking HOD container and selecting “Edit Component” menu item, select “Terminal setting” tab, input “iserised.dfw.ibm.com” for session name, select “5250” as session type, input “iserised.dfw.ibm.com” as Host and leave other fields with default value. Click [OK] button to save and close “Edit Component” dialog. In HOD container, click [Connect] button on toolbar to connect Host application server.

Adding an action:

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. Repeat steps 1-4 and finally click the save and refresh button. The button will be enabled after the first action has been added.

Play Macro:

1. Click ‘Record Macro’ button

2. Input Username “ATDEMO” and password “DEMO4YOU”, then click “Enter” key to login
3. Click ‘Stop Recording Macro’ button

4. Input “Login Macro” as Macro name in prompted “Create new Macro definition” dialog, then click [Save] button.

5. Click “Play Macro” button, select “LoginMacro” to login automatically.

Toggle Keypad:

Click “Toggle Keypad” to show Keypad

Toggle OIA

Click “Toggle OIA” to show OIA

Other tooling

See descriptions in below picture for details.

Extending the HOD container

The HOD 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 HOD infocenter contains detailed information about the HOD APIs - http://publib.boulder.ibm.com/infocenter/hodhelp/v10r0/topic/com.ibm.hod.doc/Toolkitdocs.htm.

Scenario

In this scenario, the data in HOD container would be published to Symphony spreadsheet container. Then Symphony spreadsheet container shows the received data as chart. Before starting this scenario, please install the prerequisite first.

Prerequisite:
Install Lotus Notes 8.5.1 GM (or beta) build
Install HOD container for XPD 621
Install Symphony container
Install CAE

Step 1: - Create Composite Application
1. Start Notes Client by double-clicking Notes icon on your desktop
2. New a local CA file by selecting File – Application – New Composite Application…

3. Input File name “PlaywithHODContainer” and check option “Open the Composite Application Editor” if it is not checked. Click [OK] button.

Step 2: - Assemble the Composite Application
Now the screen should be in CAE.
1. Add HOD Container into CA by dragging and dropping HOD container from Component Palette into CA empty canvas.
2. Add Symphony Spreadsheet Container into CA on the button of page.


Step 3: - Configure HOD Container
1. In page Navigator on left panel, right click ‘HOD Container’.

2. Select “Edit Component Properties” menu item, then go to “Terminal Settings” tab on opened “Edit Component Properties” dialog.

3. Input ‘iseriesd.dfw.ibm.com’ in Session Name field. This one could be any value. Select ‘5250’ as Session Type. Input ‘iseriesd.dfw.ibm.com’ in Host field. Click [OK] button to save and close ‘Edit Component Properties’ dialog.
4. Click ‘Connect’ button on the tooling bar to connect to server.

5. Click ‘Record Macro’ button on the tooling bar to start recording. Input ‘ATDEMO’ as username, ‘DEMO4YOU’ as password, hit ‘Enter’ key, input ‘strqm’ command on next screen, hit ‘Enter’ key, input ‘3’ as selection on ‘DB2 UDB for iSeries Query Manager’ screen, hit ‘Enter’ key, input ’whidemo’ as library name, hit ‘Enter’ key, input Opt ‘5’ for table ‘JK_INV’, hit ‘Enter’ key, on next screen, input ‘product_category’ as Column, input ‘eq’ as Test, input ‘Sports’ as Value, then hit ‘Enter’ key.
6. Click ‘Stop Recording Macro’ button on tooling bar. Dialog ‘Create a new Macro Definition’ prompts.

7. Input ‘Login’ as Macro name, click [Save] button. Connection would be disconnected. Click [Connect] again to connect server.
8. Once connected to server, click ‘Play Macro’ button, select ‘Login’ Macro to play till this Macro finished. We are now on ‘Display Report’ screen.

9. From the tooling, select ‘Publish’ from action drop down list, input ‘part_no’ in property field, input ‘8,21-16,23’ in Field, click ‘Add Action’ button; input ‘part_name’ in property field, input ‘8,27-16,48’ in Field, click ‘Add Action’ button; input ‘inventory’ in property field, input ‘8,55-16,58’ in Field. The value of Field can be obtained by clicking on the beginning start position (upper left) and dropping to end position (lower right). Click ‘Save and Apply Changes’ button to save the action.
10. Check landmark and operations have been added. Open ‘Edit Component Properties’ dialog, go to ‘Landmark’ tab, make sure landmarks are what you created on above step.

11. Click [Cancel] button to close ‘Edit Component Properties’ dialog.

Step 4: - Configure Symphony Spreadsheet Container
1. Input ‘Part No’ in $A$1 cell, input “Part Name” in $B$1 cell and input “Inventory” in $C$1 cell.
2. Select region A3:A15. From tooling bar, select ‘Receive’ as action, input ‘part_no’ as property name, Field should be set with value ‘A!$A$3: A!$A$15’. Click ‘Add Action’ button.
3. Select region B3:B15. From tooling bar, select ‘Receive’ as action, input ‘part_name’ as property name, Field should be set with value ‘A!$B$3: A!$B$15’. Click ‘Add Action’ button.
4. Select region C3:C15. From tooling bar, select ‘Receive’ as action, input ‘inventory’ as property name, Field should be set with value ‘A!$C$3: A!$C$15’. Click ‘Add Action’ button.
5. Click “Save and apply changes”.
6. Select A3:A15 and C3:C15, then right click on cell

7. Select “Chart…” menu item, uncheck “First row as label” n Chart setup dialog, click [Create] button.

8. Click [Yes] button on the prompted dialog “Document-Save” if any to save to “c:\demo.ods” for example.
9. Open “Edit Component Properties” dialog, then go to ‘Component setting’ tab, click [Browse…] button to select “c:\demo.ods”.

10. Go ‘Landmark’ tab to check the landmarks are created as expected.

11. Click [OK] button to save and exit.

Step 5: - Wiring HOD Container and Symphony Spreadsheet Container
1. Right click HOD Container on page navigator, select ‘Wiring’

2. Select ‘inventory’ property on HOD container, drag and drop it to ‘Set inventory’ property on Symphony Spreadsheet Container.

3. Select ‘part_name’ property on HOD container, drag and drop it to ‘Set part_name’ property on Symphony Spreadsheet Container.

4. Select ‘part_no” property on HOD container, drag and drop it to ‘Set part_no” property on Symphony Spreadsheet Container.

5. Click [Apply] button at the button right of page.
6. Select File – Save and Exit menu to apply the changes and exit CAE.

Step 6: - Run Composite Application
1. Click [Connect] button on tool bar to connect server.
2. Play ‘Login’ Macro by clicking’ Play Macro’ button and select “Login” Macro.
3. When the Macro finishes, the query data should be published to Symphony Spreadsheet Container and a chart should be generated with the retrieved data.

Summary

Now reader should know how to use HOD container as a component of Composite Application: creating landmarks, interact with other component by wiring them together.