Archive

Archive for the ‘IBM Tivoli Monitoring’ Category

Update to the Enhanced 3270 User Interface Security Requirements

December 17, 2013 Leave a comment

In this post I mentioned that the recent OB700 IF1 update had added additional security checking for KOBASE and 04SRV resources and that without suitable RACF (or other security product) profiles to give the user read access to these  resources, users would not be able to log on to the Enhanced 3270 UI.

PTF UA71750 is now available and removes the security checking on these resources. As a result, these additional security profiles are no longer required.

 

New to PARMGEN…?

December 3, 2013 Leave a comment

If you need to know more about the PARMGEN configuration tool for the ITM z/OS environment, here are a couple of videos about it.

 

What is PARMGEN

Convert an ICAT RTE to PRMGEN and Upgrade the Products

Maintaining the OMEGAMON XE for CICS on z/OS Globals with PARMGEN

September 10, 2013 Leave a comment

Global settings selection

May aspects of the operation of OMEGAMON XE for CICS on z/OS data collection and operation are controlled by global settings. These settings are held in a PDS member of the library allocated to the RKC2GLBL DD in the ‘classic’ collector address space (also known as the OCCI). Typically the hlq.RKANPARU library is allocated to the RKC2GLBL DD

Global members have member names of the form KC2GLBxx where xx is a two character suffix. The global member to be used by the OCCI when monitoring a given CICS region is selected by including a KOCGLBxx dummy DD in the CICS startup JCL, where the xx in the DD name matches the suffix of a global member in the library allocated to the RK2GLBL DD in the OCCI address space.

If you do not add a KOCGLBxx DD to the CICS region, then xx defaults to ’00’ (zero zero).  If the selected global member is not found by the OCCI address space then it uses a default set of values.

PARMGEN support for the CICS globals

Currently PARMGEN support for the CICS globals is limited to copying global members from a source PDS into the run time environment’s hlq.RKANPARU library.

The source PDS to be used is specified by the KC2_CLASSIC_KC2GLB_SRCLIB parameter in the rte member name in the PARMGEN WCONFIG library and defaults to the ICAT INSTDATA dataset.

If you are not converting from an ICAT install for the RTE you can point this parameter at any library you chose and place your completed global members in there. During the deployment phase of the RTE, the deployment jobs will copy the global members from this library to the run time’s hlq.RKANPARU library.

If you are NOT using the default global member for a CICS region you will still need to manually add a KOCGLBxx dummy DD card to the CICS startup JCL in order to select the corresponding global member.

PARMGEN and System Libraries…

August 12, 2013 Leave a comment

The deployment phase (step 11 on the menu) of creating and loading an RTE with PARMGEN copies all the run time data to the run time libraries.  Some of these members need to go into system libraries such as SYS1.PROCLIB and SYS1.VTAMLST or your user versions of same.

Rather than overwrite my current live run time procedures and VTAMLST members I configure PARMGEN to write them to  ‘staging’ libraries. From there I can double check them against the current live members before committing them.

To configure PARMGEN to write to your own system data sets, edit the $GBL$USR member in WCONFIG by selecting option 8 on the main menu and then option 2 and change the highlighted lines shown in this screen shot:

$GLB$USR

You have to manually create these data sets yourself but that is easy enough using ISPF option 3,2.

After the initial deployment, most of the time you will only need to copy run time JCL from the proclib and possibly vtam list members from the vtamlst staging libraries to your actual live system data sets.

Reserving TCP/IP Ports on z/OS for use by ITM

February 12, 2013 Leave a comment

If you are using the TCP/IP protocol (defined in ITM as IP.PIPE, IP6.PIPE or IP6.SPIPE) as a transport protocol between your ITM components on z/OS then you may need to consider configuring TCP/IP to reserve specific ports for use by the ITM components in order to prevent other non ITM address spaces from acquiring them.

ITM TCP/IP port allocation algorithm

ITM and ITM agents use the following rules to allocate TCP/IP ports

  • The Hub or Remote TEMS always uses the well known port, typically 1918.
  • The agents then attempt to acquire ports in sequence using the algorithm well known port + (n*4096) until they either obtain a port or they run out of ports to try. The actual starting port and number of attempts can be controlled by the SKIP and COUNT parameters as described later.

For example, if the well known port assigned to the hub or remote TEMS is 1918, the first agent to start will attempt to obtain port 1918+(1*4096) or 6014. If that fails, it will attempt to obtain port 1918+(2*4096) or 10110 and so on.
The actual port assigned to any given agent for any given execution will vary based on the startup order of the agents and various other timing related factors but will always follow the above pattern.
Thus you can predict the port numbers that will be required by the ITM infrastructure on a given LPAR.

Using 1918 as a starting point, the following port numbers are potential candidates for use by ITM:

1918 – Always assigned to the hub or remote TEMS
6014
10110
14206
18302
22398
26494
30590
34686
38782
42878
46974
51070
55166
59262
63358

Notice that this means you can have a maximum of one hub or remote TEMS and 15 agents on an LPAR.

What are the potential problems?

Unless you take specific action by configuring TCP/IP, there is nothing to prevent any other non ITM application on a z/OS LPAR from using any of these ports. Thus it is entirely possible that enough of these ports are in use by other applications that there are not enough for all the ITM agents, resulting in connectivity issues.
This type of problem can be difficult to diagnose since it may only occur randomly as it depends on the the unavailability of specific ports, and that will depend on which other application are running and the ports they have acquired.

What ports do I need to reserve?

If you are running for example, a remote TEMS and four agents on a z/OS LPAR then the environment will need as a minimum, the well known port plus four additional ports. The four additional ports do NOT have to be consecutive (using the list above). In the absence of the SKIP and COUNT parameters, each agent will try specific ports from the list (assuming 1918 as the base well known port) until it obtains a port. So you could quite validly reserve for example, ports 34686, 38782, 42878, 46974 for use by the four agent address spaces. In that case you might want to use the SKIP parameter to prevent agents from attempting to bind to the the first 7 ports in the list.

Remember, these examples are based on 1918 being the well known port. The actual values in use will change if you use a different port number for the well known port.

Reserving port in TCP/IP

The PROFILE DD of the TCP/IP started task JCL points to a dataset, or more typically a member of a dataset, that configures the TCP/IP environment. Within this configuration dataset or member you can use entries within the PORT statement to restrict specific ports to specific address spaces.

The port section might look like this:

PORT
7 TCP MISCSERV
7 UDP MISCSERV
9 TCP MISCSERV
9 UDP MISCSERV
19 TCP MISCSERV
19 UDP MISCSERV
20 TCP OMVS
etc…

Where the first value of each line is the port number, the second value is the protocol and the third value is the name of the address space that the port is limited to.

The critical port to reserve for ITM is the well known port which is typically 1918. So if your TEMS address space is named CANSDSST and the well known port is 1918 then you could add the following entry to the TCP/IP configuration deck PORTS section

1918 TCP CANSSDDT

This would prevent any other address space from obtaining port 1918.

Do I need to reserve ports for the agents?

The way that the allocation algorithm works allows you to have up to 15 agents running on an LPAR. If you only have a few agents on an LPAR then even if there are some ports from the potential list in use by non ITM applications, there are probably enough free ports from the list of potential ports to satisfy the needs of the agents.

However, if you have a lot of agents on an LPAR or if you want to guarantee that specific ports are available to the ITM agent address spaces then you may need to reserve specific ports to specific agents address spaces in order to ensure that they are available for the agent address spaces.

There are a couple of ways to do this:

  • Configure TCP/IP to allow any agent to connect to any of the potential ports
  • Configure each ITM agent to use a specific port and limit each port to a specific address space in the TCP/IP profile.

Configure TCP/IP to allow any agent to connect to any of the potential ports

The advantage of this method it that it only requires TCP/IP configuration and allows ITM to continue to dynamically assign ports to each agent based on availability and startup sequence. For example, if you had three agent started tasks CANSCICS, CANSMQ and CANSMFN, you would need to configure TCPIP to reserve all the potential ports for each address space as follows:

PORT
:
6014 TCP CANSCICS
6014 TCP CANSMQ
6014 TCP CANSMFN
10110 TCP CANSCICS
10110 TCP CANSMQ
10110 TCP CANSMFN
14206 TCP CANSCICS
14206 TCP CANSMQ
14206 TCP CANSMFN
etc all the way up to port 63358

Obviously as you add more agent address spaces you have to add more entries for each port.

Configure each ITM agent to use a specific port and limit each port to a specific address space in the TCP/IP profile.

This method uses a combination of ITM and TCP/IP configuration options to achieve the desired result. The advantage of this method is that the port assigned to each agent address space is predictable.

First, lets configure TCP/IP to reserve a single specific port for each agent address space:

PORT
:
6014 TCP CANSCICS
10110 TCP CANSMQ
14206 TCP CANSMFN
:

Now you need to configure each agent to only use a specific port. To do this you need to edit the KDE_TRANSPORT IP.PIPE (and/or IP6.PIPE or IP6.SPIPE if in use) entry of each agent’s KppENV member in RKANPARU as follows:

For the CICS agent address space CANSCICS:

KDE_TRANSPORT=IP.PIPE PORT:1918 USE:Y COUNT:1

For the MQ agent address space CANSMQ:

KDE_TRANSPORT=IP.PIPE PORT:1918 USE:Y COUNT:1 SKIP:1

For the MFN gent address space CANSMFN:

KDE_TRANSPORT=IP.PIPE PORT:1918 USE:Y COUNT:1 SKIP:2

The COUNT:1 parameter tells the agent address space to only try 1 port number from the potential list or ports.
The SKIP parameter tells the agent address space to skip that number of ports in the available list before trying to bind to the port. It is not required for the CICS agent (in this example) because the CICS agent address space will bind to the first port in the list.
Remember, these examples are based on the well know port number being 1918.

High Availability Hubs

A high availability hub is a hub TEMS address space that uses a DVIPA IP address to enable it to run on any candidate LPAR (one with the DVIPA address configured) within the sysplex. The location of the IP address moves with the hub address space so that as it moves from LPAR to LPAR, the agents and remote TEMS can connect to it, no matter where it is.

A hub TEMS uses the same well known port number as the rest of the ITM infrastructure (remote TEMS), however because a high availability hub connects to a different IP address (the DVIPA address) from that defined for the host LPAR, the high availability hub can execute on the same LPAR as a remote TEMS, even though both are using the same well known port.

However, if you have reserved the well known port on each LPAR for a remote TEMS address space, you must also reserve the same address for the high availability hub address space name.

So, in the PORT section of the TCPIP profile dataset or member you might have the following entry to reserve the well known port 1918 for the remote TEMS:

1918 TCP CANSSDDT

To this you would need to add (assuming the high availability hub address space name is CANSHAHB):

1918 TCP CANSHAHB

Both address spaces can bind to the same port because the high availability hub is using the DVIPA IP address.

Useful Commands

Refreshing the TCPIP configuration

After making changes to the TCPIP profile dataset or member you can use the OBEYFILE command to cause the TCPIP address space on an LPAR to reload its configuration file.

E.G.

V TCPIP,TCPIP,OBEYFILE,DSN=TCPIP.PROFILES(SYSA)

Listing reserved ports

You can list the currently configured TCP/IP reserved ports using the TSO NETSTART PORTLIST command.

E.G.

In TSO, issue the command:

NETSTAT PORTLIST [REP DSN dsn]

The REP DSN dsn option causes the command to write the output the to the dataset specified by the dsn operand.

Remember. Just because a port or address space name is defined in the TCPIP profile dataset or member does not mean it is actually defined to TCP/IP. You must restart TCPIP or issue the OBEYFILE command to refresh the TCPIP configuration.

Diagnosing Port Permissions Problems

In the agent or RTEMS RKLVLOG output you may see this sort of message:

(0017-D69321E3:kdebbbi.c,128,”KDEB_BaseBind”) Status 1DE00000=KDE1_STC_CANTBIND=2: EACCES
(0018-D69321E3:kdebbbi.c,132,”KDEB_BaseBind”) <0x29615378,0x10> bind: ASD 289FD7A0, status 1DE00000, errno 2
+0018 00000000 00022774 092A2E16 00000000 00000000 …………….

  • KDE1_STC_CANTBIND indicates a bind failure.
  • EACCES indicates the bind failed because of a permissions issue. The address space is not authorized to bind to the port.
  • The port number (in hex) is the lower four digits of the word indicated in the message above. In this case 2774 (hex) is port 10100 decimal.

Use the NETSTAT PORTLIST command to determine if the address space is authorized to access the port, for example:

NETSTAT PORTLIST (PORT 10100

The (PORT portnumber operand limits the output to just the requested port.

A note about EACCES issues.

My research indicates that an EACCES return code is returned when the application first attempts to use a port, NOT when it is allocated. What this means for ITM is that the port allocation algorithm may select a free port that is actually restricted by TCP/IP. However ITM will not find out about this until it tries to bind to the port.  At that point the port allocation process is complete so you end up with an assigned port that you cannot use.

In this instance I believe the only solution is to use the COUNT and SKIP parameters to force agents to only use ports in specific ranges and to avoid any reserved port ranges. You don’t have to assign a specific port to each agent, you can still let them pick from a range based on first available but if you have for example, a range of reserved ports in the middle of the normally free range of ports, you may need to configure some agents to only use ports below that reserved range and others to use the ports above the range.

The actual configuration you need to use to make the agents avoid the reserved range or ranges will depend on the number of agents you are running on the system and where in the list of normally free ports, the reserved range or ranges are.

 

 

Categories: IBM Tivoli Monitoring, ITM

Customizing the IBM Tivoli Monitoring Enhanced 3270 User Interface – Part 2

November 26, 2012 10 comments

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:

<WORKSPACE>
HEADER=’CICS Region Overview’
NAV1TEXT=’CICSplex’
NAV2TEXT=’Region’
SET ZOMEGLOCK1=NO
SET ZOMEGLOCK2=NO

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.

Sub Panels

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:


A SUMMARY sub panel is typically used to display multiple rows of data returned by the query as a table:

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:

<SUBPANEL>

TYPE=DETAIL
HEADER=’&CICSNAME Overview’
LINES=5
COLUMNS=2

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.

LINES Statement

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!

COLUMNS Statement

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:

QUERYTYPE=ROUTER
QUERYMODE=LIVE
QUERYREGTYPE=DRA

These relate to the way the sub panel query is run. DO NOT MESS WITH THESE!

QUERYWHEN=RETURN

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.

WHENNODATA=COLLAPSE

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.

QUERY Statement

The QUERY statement defines a standard ITM SQL Query that will be sent to the ITM framework via a Data Retrieval Agent (DRA).

DISPLAYCOLS Statement

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.

KEYCOLS Statement

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.

SORTCOLS 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.

ZOOMCOLS 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.

ACTION 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:

DISPLAYCOLS=’SYSTEMID,
CICSNAME,
WSERVCLAS,
WPERFINDX(CAPTION=”Region’s_Worst_Perf._Index”),
CPUUTIL,
TODUPDT,
TRANRATE,
PCNTMXT,
ENQWAIT,
REMQUEUE,
SOS’

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:

DISPLAYCOLS=’SYSTEMID,
CICSNAME,
WSERVCLAS,
WPERFINDX(CAPTION=”Region’s_Worst_Perf._Index”),
CPUUTIL,
TODUPDT,
TRANRATE,
PCNTMXT,
ENQWAIT,
REMQUEUE,
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:

QUERY=REUSE

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:

<SUBPANEL>
TYPE=DETAIL
LINES=7

Becomes this:
<SUBPANEL>
TYPE=SUMMARY
/* LINES=7
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:

ZOOMCOLS=’CICSNAME(KCPRGNO),TASKS(KCPTASS)’

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.
Categories: IBM Tivoli Monitoring, ITM

Customizing the IBM Tivoli Monitoring Enhanced 3270 User Interface – Part1

October 10, 2012 Leave a comment

This article will describe how to customize the basic features of the IBM OMEGAMON XE Enhanced 3270 User Interface (E3270UI).

Logon Profiles

When a user logs on to the E3270UI, the datasets allocated the RKOBPROF DD in the Tivoli OMEGAMON Manager (TOM) JCL are for a profile member. The search order is as follows:

·    A member with the same name as the userid that is logging on.
·    A member named CUASITE.
·    A member named KOBCUA.

Typically, the datasets allocated to the RKOBPROF DD are hlq.UKOBDATF and either hlq.TKOBDATF or hlq.RKOBDATF. User modified and created members should be placed in the UKOBDATF dataset. You should not modify the TKOBDATF or RKOBDATF datasets since any changes made will be lost if you apply service to the product install or run time environment.

KOBCUA is the product provided default profile. You can either copy this from the TKOBDATF  or RKOBDATF dataset to the UKANDATF dataset and make any changes to it there, or use it as a model to create CUASITE and userid specific members within the UKOBDATF dataset.

Parts of the Logon Profile Member

The logon profile member is split into a number of sections as follows:

CUA

<CUA>
LOCALEID=ENUS

The LOCALEID entry controls a couple of things as follows:

·    It defines the suffix of the KOBxxxx locale member in the RKOBPROF concatenation. The default value selects the KOBENUS member.

·    The first three characters (ENU in the default case) specify the last three characters of the RKANWxxx DD card used to load workspaces from. The default setting causes workspaces to be loaded from the RKANWENU DD. This enables you to create language specific workspaces for specific users and have them loaded from a different workspace DD for those users whose logon profile directs them to that DD.

CUACOLOR

The CUACOLOR section defines the colors used for the various elements of E2370UI workspaces.

<CUACOLOR>
BOXLINES=WHITE
MAINHEADER=YELLOW
SUBHEADER=YELLOW
COLHEADER=TURQUOISE
TRAILER=YELLOW
ACTIONSELECT=WHITE
ACTIONBAR=BLUE
INPUT=GREEN
PANELID=BLUE
ZOOMSELECT=WHITE
COMMANDLINE=GREEN
KEYWORDS=BLUE
BODYTEXT=TURQUOISE
PFK=BLUE

The seven standard 3270 color names can be used:

WHITE, YELLOW, TURQUOISE, BLUE, GREEN, PINK, RED

CUASTATUS

The CUASTATUS section controls the colors used for the status lights triggered by thresholding.

<CUASTATUS>
OKGOOD=GREEN
WARNING=YELLOW
CRITICAL=RED
IDLE=BLUE
HIGHLIGHT=TURQUOISE
UNKNOWN=BLUE

SHOWOKGOOD=NO

RANGE1=GREEN
RANGE2=GREEN
RANGE3=GREEN
RANGE4=YELLOW
RANGE5=YELLOW
RANGE6=YELLOW
RANGE7=RED
RANGE8=RED
RANGE9=RED

CUAPFKS

The CUAPFKS section controls the assignment of commands to PF and PA keys.

<CUAPFKS>
PFK01=HELP
PFK02=
PFK03=END
PFK04=FILTER
PFK05=
PFK06=
PFK07=UP
PFK08=DOWN
PFK09=
PFK10=LEFT
PFK11=RIGHT
PFK12=CANCEL

CUANAV

The FIRSTWS option in the CUANAV section specifies the member name of the workspace that is displayed after the user initially logs on to the E3270UI.

<CUANAV>
FIRSTWS=KOBSTART

CUADATA

The CUADATA section specifies the name of the hub TEMS that queries are to be directed to. It can also specify the IP address and port number which may be required if there are multiple hubs in the environment with duplicate names.

<CUADATA>
HUBNAME=C5D1DE6H:CMS
/* HUBIPADDRESS=::ffff:HUBADDRESS
/* HUBPORTNUMBER=HUBPORTNUMBER

The TOM will select DRAs based on the hub name specified here since the DRA must be in an ITM environment that can communicate with the specified hub.

The KOBxxxx LOCALE member

The locale member suffix is specified by the LOCALEID keyword of the logon profile. The product provided default member is KOBENUS.

LOCALE

The LOCALE section defines locale specific settings such as the data format and currency symbols.

<LOCALE>
LOCALEDESC:’English_USA’
DATEFORMAT:MM/DD/YYYY
TIMEFORMAT:24
CURRENCY:$
THOUSANDPOS:,
SCALING:MICROSECOND
MICROSECOND:X’A0′

ACTIONBAR

ACTIONBAR sections within the locale member define the tool bar text and actions that appear at the top of the E3270UI workspace.

<ACTIONBAR>
DESC:’File’
MNEM:1
PDC:’Exit’
ACTION:=LOGOFF
PARM:’ ‘
PDC:SPACE

Categories: IBM Tivoli Monitoring, ITM

IBM Tivoli Monitoring Enhanced 3270 User Interface Overview

August 31, 2012 1 comment

This article will cover the basic features and architecture of the IBM Tivoli Monitoring (ITM) OMEGAMON XE Enhanced 3270 User Interface (E3270UI).

Introduction

The E3270UI provides the user with a 3270 based display of many of the data attributes available to TEP users via the IBM Tivoli Monitoring (ITM) Tivoli Enterprise Portal (TEP).

Currently the E3270UI supports IBM OMEGAMON XE on z/OS v510 and IBM OMEGAMON XE for CICS on z/OS v510 with more products becoming available in the future.

The following shows a typical /E3270UI screen on a 43×80 display:

Major Parts of the E3270UI Screen

Home and Command Line

You can enter product and workspace specific commands in these input fields.

Panel Name

This is the name of the panel member from the RKANWENU DD panel library in the E3270UI started task JCL. The two letters after the K indicate the product code that owns the workspace. In this case, CP indicates CICS.

Toolbar Menu

Dropdown tools. You can place your cursor on the toolbar entry name and press ENTER or type the underscored letter into the Home input field and press enter to show the dropdown.

Context & Auto Update

The auto update field shows if screen auto update is enabled or not. You can overtyped the ‘off’ value with a number of seconds from 5 to 999 to enable auto update of the screen, or type the word ‘off’ to disable it.

The title text and contents of the Context fields will change as you more around the product workspaces. In some cases you will be able to overtype these fields to switch context, for example to look at the same workspace for a different CICS region, instead of having to navigate back to the start.

Detail Subpanel

Detail sub panels show information for a single entity. The data may be displayed in one or more columns. The layout may change depending upon the 3270 screen size in use.

Displaying Truncated Data on a detail sub panel

If the data to be displayed is to large to fit in the available space on a detail sub panel, then the data is displayed and highlighted:

To see the complete data, place the cursor on the data to be displayed and press ENTER:

Press f3 to close the pop up.

Summary Subpanel

Summary sub panels typically show data from multiple rows of an ITM attribute group as a scrollable table.

There are a number of areas of interest in a summary sub panel.

Selection Input Field

On the left of each row is an input field. You can enter a / character here to see a list of the available options. You can enter options either from that list or, if you know the option letter, you can enter it directly against the required row in the summary sub panel.

Here I entered a / against one of the tasks in the ‘Highest CPU Tasks’ sub panel:

If you just place the cursor in the input field on a summary row and press enter, the default action is taken. This is normally whatever action is assigned to the ‘S’ option and is chosen to be the most logical place you are likely to want to go to from that sub panel.

Columns Indicator

The columns part of the sub panel title area (if shown) shows you how many columns of data there are in the sub panel in total and which columns are currently displayed. You can overtype the first column number to go to a specific column.

Note that in this example the first column number is 2. This is because the first column is fixed and does not scroll (in this example). The number of fixed columns may vary depending upon the workspace. The Fixed column separator indicates which columns (to the left of it) are fixed:

Scroll Buttons

The scroll buttons on a summary workspace indicate if there is more data to the left, right, above or below the data that is currently displayed by being shown as white.

You can use the standard function keys to scroll the sub panel:

F7 – Up

F8 – Down

F10 – Left

F11 – Right

Note that to scroll only that sub panel when the MORE indicator is showing you must place the cursor within the sub panel, otherwise the whole screen will scroll.

The rows part of the sub panel title area (if shown) shows you how many rows of data there are in the sub panel in total and which rows are currently displayed. You can overtype the first row number to go to a specific row within the output.

Sorting

If the column title is highlighted and contains the sort indicator to the left of it:

Then you can place the cursor on the column title and press ENTER to sort the displayed data. The sort indicator changes to indicate the current sort order of the displayed data:

Collapse Subpanel

The collapse sub penal twisty enable you to reduce the size of a sub panel on a workspace so that only the title bar is displayed. To collapse a sub panel, place the cursor on the twisty and press ENTER.

Before:

Collapsed:

Note that the twisty changes to indicate that you can expand the sub panel by placing the cursor on the twisty and pressing ENTER.

The number of rows contained by the sub panel is display in reverse text on the right of the title bar.

Minimize and Delete Subpanel

 Minimize

If you place your cursor on the minimize icon (the small white square with the underscore in it) and press ENTER, the sub panel will be minimized down to the ‘task bar’ at the bottom of the screen.

Sub panels below the minimized one move up onto the available screen space.

To restore the minimized sub panel to the workspace, place the cursor on the entry on the task bar and press ENTER

Delete

If you place your cursor on the delete icon (the small white square with the cross in it) and press ENTER, the sub panel will be removed from the workspace:

The difference between minimize and delete is that when you minimize a sub panel, if you press enter to refresh the workspace, the query associated with the sub panel is still executed.

When you delete a sub panel from the workspace, pressing enter no longer runs the query associated with it.

To restore a deleted sub panel to the screen, you must navigate back to the previous workspace by pressing F3 and then navigate forward again to this workspace.

MORE Indicator

The MORE indicator in the bottom right corner of the screen shows if there are additional sub panels to display on the workspace that are not currently displayed on the physical screen.

The arrow indicates the direction of the additional sub panels. You can use the vertical scroll keys (F7 and F8) to scroll the workspace.

Note that the cursor must NOT be within a sub panel in order to scroll the entire workspace. If the cursor is within a sub panel, scrolling only applies to that sub panel.

Navigation

 Navigating around the E3270UI is designed to by quick and simple with the default options taking you to the most sensible places.

 Navigating from summary panels

 Navigating from a summary sub panel row is as simple as placing the cursor in the input field next to the desired row of data and pressing ENTER which will cause the E3270UI to take the default navigation action.

 If you don’t know what actions are available for the data in a summary row, you can enter a / character next to the row and pres ENTER to display a popup menu of available options. The default option, that is the one taken when you just put the cursor in the input field and press enter, is indicated by the S option.

 

Zooming

 Zooming is a navigation feature whereby you place the cursor on a data field’s caption or value and press enter which then takes you to another workspace. The target workspace may be fixed or it may be determined dynamically, based on the data in the field that you are zooming on.

Normal
0

Zooming from Detail sub panels

In the following sub panel, the Transaction ID field is highlighted indicating that it is zoomable.

Normal
0

By placing the cursor on the caption and pressing enter the user will be taken to another workspace. In this particular instance the user will be taken to the “Transaction Details” workspace for the transaction id displayed in the sub panel (OMEG in this case).

Zooming from Summary sub panels

In the following summary sub panel, the CICS Transaction ID field is highlighted indicating that it is zoomable.

 

By placing the cursor on the highlighted data in the required data row and pressing enter the user will be taken to another workspace. In this particular instance the user will be taken to the “Transaction Details” workspace for the selected transaction id (OMEG in this case).

 Navigating Back

 As you navigate forward through workspaces as a result of selections and zooms, you create a hierarchy of workspaces. To traverse back up that chain of workspaces to previous ones, press F3.

Architecture

In this section I shall take a brief look at the E3270 architecture.

The E3270UI environment is built on top of the IBM Tivoli Monitoring (ITM) agent framework. What this means is that it collects its data from existing ITM agents using the ITM framework that is already in place. You do not have to use the Tivoli Enterprise Portal (TEP) in order to use the e3270UI.

The Tivoli OMEGAMON Manager Address Space

The E3270UI 3270 sessions are hosted by the Tivoli OMEGAMON Manager (TOM) address space. A single TOM address space can support multiple 3270 sessions. The TOM obtains data from ITM by sending the requests to Data Retrieval Agents (DRAs) that execute within IBM Tivoli Monitoring Server (TEMS) and agent address spaces within the sysplex.

The Data Retrieval Agents

There can be one or more DRAs executing on one or more LPARs within the sysplex. Each DRA registers itself with the z/OS Workload Manager (WLM) as a service. The TOM then queries WLM in order to locate all the DRAs that are available within the sysplex.

TOM location within the sysplex

As a result, a TOM can be anywhere within the sysplex, it does NOT have to be on the same LPAR as a DRA.

Performance and Security

You can run multiple TOM address spaces, spread across the sysplex for performance, fail over and security reasons, depending upon your requirements and installation. When multiple DRAs are available, the TOM will dynamically select different ones to service query requests in order to prevent any one DRA hosting TEMS or agent address space from becoming overloaded.

Typical setup

This diagram shows a possible implementation. In this example the TOM is running on one LPAR and communicating with two DRAs. One DRA is with an agent or TEMS address space on the same LPAR while the other DRA is within an agent or TEMS address space on another LPAR within the same sysplex.

Each DRA registers itself with the common WLM environment, from where the TOM can locate them.

Notice that the hub TEMS is not shown. The ITM hub can be on a z/OS LPAR, possibly on an other sysplex or even off platform such as on an AIX machine.

TOM Registry

 The TOM periodically queries WLM for the list of available DRAs and the ITM environment in order to discover the available ITM managed system components, lists and managed system names.

In order to display data for a managed system such as a z/OS LPAR known to the ITM environment via an IBM OMEGAMON XE on z/OS agent executing on that LPAR, the TOM must have discovered and registered the managed system (the LPAR) from ITM via its registry refresh process.

It is possible that a managed system can be known to the ITM environment and even be viewed on the TEP and yet not be visible to E3270UI users because the TOM has not run it’s refresh process since the managed system came online.

You can drive the TOM registry refresh process manually at any time via the tools menu on the Tool bar dropdown menu.

You can also initiate a registry refresh by issuing the REGREFRESH operator modify command to the TOM address space via an interface such as SDSF.

 E.G.

 F tomstc,REGREFRESH

 Where tomstc is the job, started task or modify name of the tom address space. However most users will not have the necessary authority to do so, at least in a production environment.

Query Flow

 When an E3270UI workspace issues a query, the TOM directs the query to one of the DRAs that it knows about that are running in an agent or TEMS address space that connects to the desired hub TEMS.

The DRA then sends the query to the hub TEMS which then distributes it to the managed system agent on the desired system.

The response from the agent is sent back the hub TEMS and from there to the DRA and then back to the TOM.

Remember that the DRA selected by the tom may not be on the same physical LPAR as the agent that the query is destined for. This architecture ensures that the query can reach the required agent, even if there is no direct connection between the system the DRA is executing on and the system that the agent is running on.

Categories: IBM Tivoli Monitoring, ITM

Incorrect Workspace names in the ITM TEP Navigator tree

August 22, 2012 1 comment

If you notice that some of the workspace names do not resolve correctly in the ITM Navigator tree when you use the Java WebStart based TEP client then the following may be useful in resolving the problem.

The issue is described here http://www-01.ibm.com/support/docview.wss?uid=swg21585367

But in summary the steps to address the problem are:

 

Reconfigure the TEPS as follows:

From the ‘Manage Tivoli Monitoring Services’ application on the desktop, Right click the ‘Tivoli Enterprise Portal Server’ and select ‘Reconfigure…’ You do not have to actually change anything, just go through the steps in sequence.

If that does not correct the problem then try clearing the Java cache as follows:

  1. Go to the directory where Java 1.5 is installed.
  2. Change directories to the \jre\bin directory.
  3. Double-click on javaws.exe.
  4. In the Java Application Cache Viewer window, click Edit -> Preferences.
  5. In the Java Control panel, under the Temporary Internet Files section, click on Delete Files, check all boxes if not already checked and click OK and then OK again.

 

Categories: IBM Tivoli Monitoring, ITM

Some useful (I hope) links for the Enhanced 3270 User Interface

August 21, 2012 Leave a comment

Technote – Configuring OMEGAMON Enhanced 3270 User interface security

Technote – Alleviating GIM PROCESSING FAILED error messages

Upgrade OMXEC5510, Subset HKOB700

developerworks – System z Management

SMC – Service Management Connect

Note. The new Enhanced 3270 User Interface (E3270UI) framework, I.E. The TOM and associated components, are delivered as part of the base product FMID HKOB700 while the components that provide the actual data screens and data are delivered under their own FMIDs.

Categories: IBM Tivoli Monitoring, ITM