Customizing the IBM Tivoli Monitoring Enhanced 3270 User Interface – Part 2
This article will describe how to customize or create your own IBM OMEGAMON XE Enhanced 3270 User Interface (E3270UI) workspaces.
Before modifying an product supplied workspace member it is recommended that you copy it from the hlq.TKANWENU or hlq.RKANWENU library to the hlq.UKANWENU library and make the modifications there. Remember that any changes you make will be seen by all users of the E3270UI therefore you might want to clone the E3270UI started task JCL and create you own instance of it with your own private WENU workspace library concatenated in front of the standard ones, so that you can develop and test your changes without impacting anyone else.
You could also allocate your own workspace library in front of the standard ones but allocate the concatenation to you own RKANWxxx library where xxx are the last three characters of the LOCALEID specification in your own profile member. See part 1 of this series for more details.
Standard Workspace Structure
The Workspace Header Section
In addition to the standard workspaces that you see on the E3270UI screen there are also popup and silent workspaces. In this article we shall just be looking at a standard workspace.
Within a workspace, comments on a line are indicated by a /* (slash asterisk) string. There is no need for a closing */ (asterisk slash). Comments are NOT continued across lines so each must be preceded by a /*.
A workspace definition consists of a header section that starts with a <WORKSPACE> stanza followed by one or more sub panel definitions and ending with a </WORKSPACEEND> stanza.
The <WORKSPACE> stanza must be the first non-comment line in the workspace source member.
A typical workspace header might look like this:
HEADER=’CICS Region Overview’
The HEADER text ‘CICS Region Overview’ appears on the fourth line of the screen.
The two navigation fields in the top right corner are referred to as NAV1 and NAV2. You set the text to be displayed in the caption (in blue on the above screen shot) using the NAV1TEXT and NAV2TEXT keywords.
If you set the appropriate ZOMEGLOCK1 or ZOMEGLOCK2 to NO then the user can overtype the corresponding input field to change the context of the data being displayed on the workspace, such as overtyping the ‘Region’ name in the above screen shot of an OMEGAMON XE for CICS on z/OS workspace to change to a different CICS region within the same CICSplex. The actual implementation and use of these two fields is product specific. Setting ZOMEGLOCK1 or ZOMEGLOCK2 to YES will prevent the user from overtyping the corresponding field.
A sub panel definition within a workspace starts with a <SUBPANEL> stanza. There is NO corresponding closing stanza, the next <SUBPANEL> or </WORSPACEEND> stanza defines the end of the sub panel definition.
There are two different type of sub panel, DETAIL and SUMMARY. A DETAIL sub panel is used to show data about a single row of data as a block on the screen:
If you know that there will only ever be ONE row of data returned, you can use either style of sub panel. Be aware though that there are differences in the way navigation to other workspaces works between the two styles of sub panel, as described in my earlier E3270 Overview article.
A Typical Sub Panel header might like this:
The TYPE=DETAIL line defines this as a detail sub panel.
The HEADER line creates a sub panel header. Notice that it contains a variable, &CICSNAME. This variable would have been set by an earlier workspace by the navigation process. We will look at setting variables later.
The LINES statement defines the number of lines that the sub panel should occupy. For a detail sub panel you must ensure that you have enough lines and columns to display all the attributes specified by the DISPALYCOLS keyword. For example, if you specify LINES=5 and COLUMNS=2 but then specify eleven attribute names in the DISPLAYCOLS statement, you will not see the eleventh attribute!
This defines the number of columns of data to be shown. For example, this is a two-column detail display:
The default is DYNAMIC, which allows the E3270UI to control the formatting of the sub panel.
There are also COLUMNS132 and COLUMNS160 keywords that can be used to specify the number of columns to be displayed on 3270 screens with a 130 or 160 character wide display.
Following the sub panel header section are the following lines:
These relate to the way the sub panel query is run. DO NOT MESS WITH THESE!
If the QUERYWHEN option is NOT specified then after having navigated forward from this workspace, as you navigate back to it using F3 the previous data is displayed. The query associated with the sub panel is NOT run again.
If you specify QUERYWHEN=RETURN then as you navigate backwards to the workspace, the query is run so that the sub panel shows the latest data, not the old data.
The WHENNODATA keyword defines the behavior when there is no data to display in this sub panel. There are a number of options as follows:
- Collapse. Only the sub panel header, collapse/expand twisty, and the minimize and close buttons are displayed. This is the default.
- Minimize. The sub panel is minimized down to the task bar
- End. If no data is retrieved on the initial query or entry to the workspace, the sub panel is “deleted” from the workspace. This option is useful for queries that will either return data or will not, but that condition will not change if the workspace data is refreshed by pressing ENTER.
- Shrink. The number of rows in the sub panel is dynamically decreased to zero when there is no data.
- Hide. Use instead of End if you want the sub panel to reappear when data is available again.
The QUERY statement defines a standard ITM SQL Query that will be sent to the ITM framework via a Data Retrieval Agent (DRA).
The DISPLAYCOLS statement names the attributes that are to be displayed on the sub panel. The attributes are displayed in the order specified. Any attribute name you specify here must also be specified in the QUERY statement, however you do not have to display every attribute that the query retrieves.
You might retrieve certain attributes in the query in order to set variables from their values for later use as you navigate forward from this workspace. ORIGINNODE (the managed system name) is a typical example.
By default, each attribute is displayed using the same attribute caption and formatting information as used by ITM but you can override this on an attribute-by-attribute basis.
This statement defines the attribute names from the query whose data that should be used to create variables of the same name as the attribute when the row of data is selected as you navigate forward.
Any attribute name you specify here must also be specified in the QUERY statement.
The SORTCOLS statement specifies the attributes that should be indexed so that the rows of data in a TYPE=SUMMARY sub panel can be sorted by the user.
Since there is an overhead associated with building these indexes, especially for large row sets, it is recommended that you keep the number of sortable attributes to the minimum required to enable the user to perform the task at hand.
Any attribute name you specify here must also be specified in the QUERY statement.
The ZOOMSCOLS statement specifies the attributes that the user can ‘zoom’ on by placing the cursor on the attribute name for a detail sub panel, or the data for a summary sub panel, and the target workspace.
Any attribute name you specify here must also be specified in the QUERY statement and must also be specified in the DISPLAYCOLS statement.
The ACTION statement only applies to summary sub panels. Each instance of an ACTION statement defines the selection character that must be entered to invoke the associated action, the text to be displayed when the user inputs a / in the selection field to display the available options, the target workspace member name when this option is selected and for one entry, the DEFAULT option to indicate that this is the default option to be taken if the user just places the cursor in the input field and presses enter without entering a selection character.
A typical definition might look like this:
ACTION=RTYPE(S,”CICS Bottleneck Detail”,KCPBOTD,DEFAULT)
ACTION=RTYPE(T,”CICS Tasks Waiting for Resource”,KCPBOTT)
The RTYPE value (in this example) is the name of the attribute that the input field is to be displayed next to. Currently this is not used. There is always only one selection field and it is to the left of the first attribute that is displayed for each row.
Basic Workspace Customization
There are a few simple things that you can do to customize workspaces and sub panels.
Rearrange Displayed Attributes
For summary panels, you may prefer to see different attributes on the left of the tabular display so that that they are more rapidly visible without having to scroll the sub panel to the right to see them.
In the DISPLAYCOLS entry, each attribute should be followed by a comma and the entire string enclosed in quotes. For example:
Change or Add Captions
You can override the default caption extracted from the ITM Attribute Group definition by changing an existing caption override or adding a CAPTION entry after the attribute name. For example:
SOS(CAPTION=”Short On Storage”)’
Split a Sub Panel into multiple Sub Panels
For summary sub panels, which display the data as a scrollable table, if the number of attributes specified in the DISPLAYCOLS entry is larger than the screen width can display then the user will need to scroll left and right to see them all.
If you prefer you could split the displayed data into two sub panels so that you can see data that is currently off screen to the right, on a second sub panel below the first.
The process is fairly straightforward.
- Within the workspace, make a copy of the sub panel you want to split so that the new copy follows the existing one.
- Change the QUERY statement so that it reads as follows:
This will avoid the same query from being issued twice. Instead this sub panel will reuse the result set from the previous sub panel.
- Edit the DISPLAYCOLS statement in each sub panel so that it displays the required attributes.
Convert a Detail Sub Panel to a Summary Sub Panel
A detail sub panel can occupy multiple lines on the screen. You might prefer to display the data as a summary style sub panel and have the user scroll left and right to see the additional data.
This is a simple as changing the sub TYPE=DETAIL entry in the sub panel header so that it reads TYPE=SUMMARY.
You may also need to delete or comment out any LINES entry in the sub panel header.
So for example, this:
Zoom style navigation will still work as it did before. You may also be able to add action style navigation to the same workspaces as the zoom navigation by adding appropriate ACTION statements to the sub panel entry.
For Example, if the ZOOMCOLS entry for the sub panel is:
Then you ‘may’ be able to add the following to the sub panel so that you can navigate using action characters or the action menu:
ACTION=’CICSNAME(S,”CICS Regions Overview”,KCPRGNO,DEFAULT)
ACTION=’CICSNAME(T,”CICS Task Summary”,KCPTASS)
When the ZOOMCOLS definition for a column takes the user to a silent workspace, particularly one that runs a REXX exec then you may find it does not work as expected. However for basic navigation to another workspace this conversion ‘should’ work fine.
Convert a Summary sub Panel to a Detail Sub Panel
You can only convert a summary sub panel to a detail sub panel if the query associated with it only ever returns a single row of data. If the query returns multiple rows, only the FIRST row of data that is returned will be displayed.
The process is pretty much the reverse of the above.
- Change TYPE=SUMMARY to TYPE=DETAIL
- Add a COLUMNS=n entry to the header if you want the display to be more than a single column.
- Add a ZOOMCOLS entry and specify the attribute name that you want to zoom on and the target workspace member name.
- Delete or comment out any ACTION statements.