This technote contains information about known defects, limitations, and workarounds for the IBM Tivoli OMEGAMON XE for Mainframe Networks V5.1.1 product.
Resolving the problem
This technote contains information about known defects,
limitations, and workarounds for the IBM(R) Tivoli(R)
OMEGAMON(R) XE for Mainframe Networks V5.1.1 and earlier
1. Version 5.1.1 runs with IBM Tivoli Monitoring v6.2.3 Fix Pack
1. However, a best practice is to run v6.2.3 Fix Pack 3 or later.
If you are already running v6.3.0 of IBM Tivoli Monitoring
components, then v6.3.0 Fix Pack 1 is the best practice
2. OMEGAMON XE for Mainframe Networks Version 5.1.1 is equivalent
to Version 5.1.0 with APARs OA42339 and OA42422 applied. You can
upgrade from OMEGAMON XE for Mainframe Networks V5.1.0 by
installing the PTFs and fix pack that are associated with APARs
OA42339 and OA42422, or you can upgrade from V4.1.0 or later by
ordering and installing OMEGAMON XE for Mainframe Networks
V5.1.1 PID: 5698-T03.
If you have enabled the self-describing agent feature, and you
do not use the Tivoli Enterprise Portal desktop client, you do
not need to install the distributed fix pack that goes with the
APARs. Refer to the Version 5.1.1 Program Directory for
prerequisites and installation instructions.
3. Since Version 5.1.1 was delivered via fixpack and PTFs on
version 5.1.0, an existing customer reaches the functionality
of version 5.1.1 by applying the maintenance and running the
appropriate configuration steps. Versions 5.1.1 and 5.1.0
share the same FMID so when using JOBGEN, "V510" will continue
to display on the install list. This is not an error.
4. Users experience problems when the Tivoli OMEGAMON Manager
address space is running in a different CSI or RTE.
These SQL errors in the RKLVLOG indicate query failures:
SQL1_CreateRequest with return code of '202'
Which indicates a TEMS Catalog error (RC=202 is named
Problems occur if you have a Tivoli OMEGAMON Manager (TOM)
address space running in a SMP/E CSI or Run Time Environment
(RTE) other than the one where the OMEGAMON XE for Mainframe
Networks V511 agent is installed.
When the TOM address space executes in a different CSI or even a
different RTE than where the OMEGAMON for Mainframe Networks agent
is running, make sure the TOM has access to the latest product
provided queries. A SQL failure, such as SQL1_CreateRequest with
return code of '202' can occur if the TOM is not aware of new
The KN3DOC file from the latest V5.1.1 deliverable must be
available to all TOM address spaces capable of discovering
V5.1.1 agents. To address this problem, make this file available
by copying the KN3DOC file to the hlq.RKANDATV concatenation for
the TOM started task.
5. If you intend to enable the self-describing features and a
z/OS hub monitoring server, configure a high availability hub.
For more information, see IBM Tivoli Monitoring: Configuring
the Tivoli Enterprise Monitoring Server on z/OS.
Ensure that you have installed IBM Tivoli Monitoring V6.2.3
Fix Pack 1 or later before you install or upgrade to OMEGAMON
XE for Mainframe Networks v5.1.1.
The OMEGAMON XE for Mainframe Networks agent is installed with
self-describing support enabled. Once self-description is
enabled at the hub Tivoli Enterprise Monitoring Server that the
agent is reporting to, the application support file updates are
automatically synchronized, and, if relevant, the updates are
deployed to the Tivoli Enterprise Monitoring Server and the
connected Tivoli Enterprise Portal Server.
The following OMEGAMON XE for Mainframe Networks agent
TMS:Engine parameter values are needed in order to support
These parameters are generated in the KN3SYSIN member of the
If the hub monitoring server and the remote monitoring server
reside on z/OS, they must also be modified to use LIMIT(24,X).
Follow the process outlined in the Configuring the Tivoli
Enterprise Monitoring Server on z/OS book and ensure that the
Maximum storage request size (Extended) value is set to greater
than or equal to 24.
To make these changes permanent, make them using PARMGEN or
the Configuration Tool. See the IBM Tivoli OMEGAMON XE for
Mainframe Networks: Planning and Configuration Guide for more
information. This is not an issue if you install into a new
environment; it is only an issue when you upgrade.
This update is included in PTF UA69076. See the
“Self-describing agent function fails after application of
APARs OA42339 and OA42422” troubleshooting item for
configuration after installing this PTF.
6. When installing the OMEGAMON for Mainframe Networks v5.1.1
application support files from 5.1.0-TIV-KN3- FP0001 using the
installation wizard on Windows 2012, the install might appear
The problem might be that the installation wizard is waiting for
you to press Enter in a command window opened by the installer.
The window where this action should be taken may be minimized.
To continue with installation, locate the command window that
is generated by the installer, open it, and press Enter. If
the command window is minimized, use the icon for it in the
Windows desktop taskbar to maximize it.
7. In Version 6.3, IBM Tivoli Monitoring has implemented more
granular controls on the self-describing agent (SDA) feature.
If you enable the self-defining agent feature (SDA) on a hub
monitoring server running on a distributed platform (Enabled
by setting variable KMS_SDA=Y and starting the hub monitoring
server), then the following information is relevant. On z/OS
the default behavior for the hub monitoring server is that it
continues to function in ITM 623 mode when it is initially
enabled for SDA.
In Version 6.3 of IBM Tivoli Monitoring, the tacmd
listsdastatus command can be used to report SDA status for
the hub and remote monitoring servers. The default SDA
behavior is for the IBM Tivoli Monitoring v6.3.0 hub
monitoring server to block SDA installation unless a product
is explicitly configured for SDA or SDA behavior is set to work
as it did in IBM Tivoli Monitoring v6.2.3.
To address this issue, do the following:
a. Use the following command to determine SDA configuration.
If no configuration records exist, this means that all SDA
seeding is blocked.
b. Do one of the following:
Enable SDA installation of OMEGAMON XE for Mainframe Networks
V5.1.1 by issuing the following command, for example:
tacmd addsdainstalloptions -t N3 -v 05100400
Issue the following command to revert to 6.2.3 behavior where
all products are allowed to install:
tacmd editsdainstalloptions -t default -i on
If you see Message KRAA0003 returned, this indicates that
the product or version is blocked from SDA installation.
8. Before you upgrade to IBM Tivoli Monitoring v6.2.3 Fix
Pack 1 or later and OMEGAMON XE for Mainframe Networks v5.1.1,
run the following tacmd against the hub monitoring server
before starting the upgrade to ensure that the product-provided
situations added by the upgrade were distributed to their
respective managed systems groups during the upgrade.
tacmd editSdaOptions -o INSTALL_SEED=ALL UPGRADE_SEED=ALL -t N3
9. As result of changes made in z/OS V2R1, you must define
z/OS v2.1 does not allow default OMVS segments. RACF support to
automatically generate unique UIDs and GIDs on demand for users
and groups that do not have OMVS segments defined is the
recommended alternative. Support for automatic unique UID and
GID generation has been available since z/OS V1R11.
Before you install z/OS V2R1, perform these security server
actions. You can perform these actions on systems with your level
of z/OS. You do not need the z/OS V2R1 level of code to make
these changes, and the changes do not require the z/OS V2R1 level
of code to run once they are made.
10. Ensure that you have installed PTF UA70618.
11. If you plan to use autonomous agent support, apply PTF
UA68938 to your IBM Tivoli Monitoring installation.
12. If you have created custom situations and are upgrading
from OMEGAMON XE for Mainframe Networks v4.1.0, the situation
event indicators might not be displayed in the Tivoli
Enterprise Portal navigation tree when the condition defined in
the situation becomes true. This problem occurs only when you
upgrade using the self-describing agent feature.
Do the following to address this problem:
a. Restart the Tivoli Enterprise Portal Server to re-associate
situations with their assigned Tivoli Enterprise Portal
navigation tree items.
b. Edit the custom situation in the situation editor, select
the Distribution tab, and verify that the situation is
distributed to the expected managed systems, or managed
systems group (*OMEGAMONXE_MAINFRAME_NTWRK_TCP,
If situation distribution is configured as expected, then
proceed to the next step to verify that the custom situation
is associated with the Tivoli Enterprise Portal Navigator.
c. Right-click on the Tivoli Enterprise Portal Navigator item
and select Situations from the pull-down menu. This brings
up the Situation Editor, filtered for situations associated
with the Tivoli Enterprise Portal Navigator. If you do not
see the custom situation in the list of situations for the
Tivoli Enterpirse Portal Navigator item, do the following:
1) Click the "Set Situation filter criteria" icon at the
top left of the Situation Editor.
2)Select the "Eligible for Association" checkbox and click OK.
3) Find the custom situation in the list and select it. Then
right-click on it to display the pulldown menu.
4) Click the "Associate" item from that menu
5) Click OK to exit the situation editor.
d. If the preceding steps do not resolve the problem, create
new situations to replace the migrated custom situations that
are not displayed in the Tivoli Enterprise Portal navigation
tree after the Tivoli Enterprise Portal Server is restarted.
13. You might see an active TN3270 server session in both the
Tivoli Enterprise Portal and enhanced 3270 user interface
(enhanced 3270UI) workspaces when the TN3270 connection is not
actually in a session with a SNA application. This problem
occurs when a TN3270 user attempts to log on to an unavailable
SNA application and the TN3270 connection is in a MONITORGROUP.
When you specify a valid SNA application, the record correctly
displays as in session. When you close the TN3270 connection,
the record is no longer displayed after the next collection.
14.The following Take Action commands are enabled in the "UDP
Local Ports 12000-120004" view of the "EE Connection Summary"
Ping IP Address
Tracerte IP Address
NSLookup IP Address
For the Ping, Tracerte and NSLookup commands, the destination
IP address is not pre-filled in the first input field of the
command dialog. You may enter the destination IP address
manually. The remote IP address of the EE connection is shown
in the "EE Connection Summary for EEPUNAME" view.
15. The Enterprise workspaces in the enhanced 3270UI support
filtering by using wildcards (*) in the TCP STC Name and SMF
ID fields in the upper right corner of the workspace. When you
specify a TCP STC Name or SMF ID as a wildcard followed by a
character, you might see records from more systems than you
expect because the query is treated as if an implicit wildcard
was found at the end of the value. For instance, specifying
“*3” as an SMF ID would return rows for SMF ID 0238 as well as
for SMF ID 4083.
16. When you upgrade to OMEGAMON XE for Mainframe Networks
v5.1.1, you might find the following message in the RKLVLOG:
KN3I008E CALL TO ADDDATA FUNCTION FAILED, RETURN CODE=retcode,
An error has occurred when the monitoring agent tried to return
data for the table specified by the table variable and failed.
The most common cause of this error is a query that returns a
large number of rows of data, causing an out-of-memory condition.
This problem also occurs when you upgrade from an environment
unless you specifically update the LIMIT and MINIMUM values to
the new defaults or higher.
IBM Tivoli Management Services: Engine (TMS:Engine) is a common
component for both the Tivoli Enterprise Monitoring Server and
for OMEGAMON XE for Mainframe Networks Monitoring. It has startup
parameters that are defined with appropriate defaults for many
customer environments, and these parameters are defined in the
data set pointed to by the RKLVIN DD statement in the started
Options are to either modify the query so that it returns fewer
rows of data or increase the LIMIT and MINIMUM values in
17. If you are using the enhanced 3270UI, you might find the
following technotes useful:
- Technote “Troubleshooting no data conditions on the OMEGAMON
Enhanced 3270 User Interface” at
- Technote “Configuring OMEGAMON Enhanced 3270 User interface
18. If you have a Tivoli Enterprise Portal browser active during
self-describing agent upgrade processing, you may see a dialog
box that warns you about application support mismatch between
Tivoli Enterprise Portal and Tivoli Enterprise Portal Server
for the OMEGAMON monitoring agents you have installed. You
might also see the message “Warning: Field PKGVERSION is not
defined for application with id.”
If you see this message, you can ignore it. There will be no
problem with your application support. After you see this message,
recycle Tivoli Enterprise Portal to pick up the latest support
installed by SDA.
19. A technote is being prepared to document IBM Tivoli
Monitoring support of Windows 2012.
20. Specifying a start or end time between 12:00 PM and
12:59 PM on Tivoli Common Reporting reports is wrongly
interpreted as 12:00-12:59 AM. This problem results in
retrieving 12 hours of data that were not expected. To avoid
the issue, specify a time before 12:00 PM or after 12:59 PM
21. UNIX installation error messages can be ignored.
You might see the following warning message when you are
installing this monitoring agent on a UNIX system:
KCIIN2463W Warning: This installation media does not contain
any components which can be run on the current system platform
architecture. To install components which can run on this
system, please locate the installation media containing files
similar to *li62*.jar. If you are installing application support,
continue with the installation to see a list of support files.
If you see this message, no action is required. Press Enter
22. When selecting the cross-product link from the OMEGAMON XE
for Mainframe Networks Applications or TCP Listeners workspaces
to the IBM Tivoli OMEGAMON XE for CICS(R) on z/OS TCP/IP
Statistics workspace, you can receive this error message:
KFWITM081E: The link target can not be found, the link
definition might be incorrect or the target is unavailable.
Check first to ensure that the CICS monitoring agent is running.
If the CICS agent is running, the problem might be that the System
ID attribute in the OMEGAMON XE for Mainframe Networks table
(which is the source of the link) does not match the System ID
portion of any of the known CICS Managed System names. This
situation exists because the System ID portion of the CICS Managed
System name is padded to the right with the underscore (_) character
if the System ID for the system is fewer than four (4) characters
To avoid this problem you can do one of the following:
Ensure that your system names are all at least four (4) characters
Change the definition of the cross-product link to pad the System
ID attribute value with the underscore character (_) such that it
matches one of the known CICS Managed System names.
To implement this workaround, follow these steps:
Note: At any time during the procedure that follows, clicking the
Cancel button cancels your updates. Nothing is saved until your
press the Finish button.
a. Right-click on the Link icon for one of the rows in the summary
table, and select the Link Wizard.
b. In the Workspace Link Wizard, click the radio button by “Modify
an existing Link” and click the Next button.
c. In the resulting Workspace Link Wizard - Link to Modify window,
select the “CICS TCP/IP Statistics” link and click the Next button.
d. In the resulting Workspace Link Wizard – Link Name window, click
the Next button.
e. In the resulting Workspace Link Wizard – Target Filters window,
select the Managed System name line and click the “Modify Expression”
f. In the resulting Expression Editor - Managed System name window,
replace the expression with the following expression and click the
(LEN($kfw.TableRow:ATTRIBUTE.KN3TAP.SYSID$) GE 4) ?
($kfw.TableRow:ATTRIBUTE.KN3TAP.SYSID$ + "."
+ $kfw.TableRow:ATTRIBUTE.KN3TAP.APPLNAME$) :
($kfw.TableRow:ATTRIBUTE.KN3TAP.SYSID$ + STR("____", 1,
(4- LEN($kfw.TableRow:ATTRIBUTE.KN3TAP.SYSID$))) + "."
This action causes the Expression Editor to verify that the updated
expression matches a known CICS Managed System name.
g. Once the updated expression evaluates correctly, click the OK
button on the Expression Editor window to temporarily save the
h. In the resulting Workspace Link Wizard - Target Filters window,
click the Next button.
i. In the resulting Workspace Link Wizard - Parameters window,
click the Next button.
j. In the resulting Workspace Link Wizard - Summary window, click
the Finish button to save the change to the link definition.
For more information about the Link Wizard and the expression
editor, click the Help button from Tivoli Enterprise Portal, or
see the IBM Tivoli Monitoring User's Guide.
23. Flyover help in the situation editor shows the wrong
information when you hover over a situation group
1. The Feedback link in the lower left corner of help below the
rule does not work.
2. Some flyovers might be truncated in Chinese locales.
3. Tivoli Common Reporting reports in the Adobe(R) Postscript(R)
format are displayed incorrectly on Windows systems in Japanese
and Chinese locales.
In a Japanese environment, if the Tivoli Common Reporting server
is installed on a Windows system and the browser language is
either Japanese or Chinese, the Adobe Postscript report format are
4. Tivoli Common Reporting reports that are formatted in Postscript
(.ps) and Microsoft(R) Excel (.xls) are displayed incorrectly in a
Mozilla Firefox browser.
If your browser is Mozilla Firefox with the language set to other
than English, Tivoli Common Reporting reports cannot be generated
in the postscript (.ps) or Excel (.xls) formats. This is because
localized report names exceed 60 bytes.
To avoid this name-length problem, use the Tivoli Common Reporting
Properties dialog box to shorten the report name to be fewer than
5. The server locale must be the same as the browser locale.
Reports are not displayed if the language on the Tivoli Common
Reporting server is different from the language of the browser
where the reports are displayed.
6. Tivoli Common Reporting report selection dialogs fail for
some reports on Korean Windows systems when using a Mozilla
Firefox browser configured with any of the Korean language
choices. Report selection works correctly in Korean for the
Internet Explorer browser. If you change the Mozilla Firefox
browser language option to English, all reports can be launched
This information was developed for products and services
offered in the U.S.A. IBM may not offer the products,
services, or features discussed in this document in
other countries. Consult your local IBM representative
for information on the products and services currently
available in your area. Any reference to an IBM product,
program, or service is not intended to state or imply
that only that IBM product, program, or service may be
used. Any functionally equivalent product, program, or
service that does not infringe any IBM intellectual
property right may be used instead. However, it is the
user’s responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications
covering subject matter described in this document. The
furnishing of this document does not give you any
license to these patents. You can send license
inquiries, in writing, to:
IBM Director of Licensing
North Castle Drive
Armonk, NY 10504-1785 U.S.A.
For license inquiries regarding double-byte (DBCS)
information, contact the IBM Intellectual Property
Department in your country or send inquiries, in
Intellectual Property Licensing
Legal and Intellectual Property Law
IBM Japan, Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan
The following paragraph does not apply to the United
Kingdom or any other country where such provisions are
inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES
THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND,
EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Some states do not allow disclaimer of express or
implied warranties in certain transactions; therefore,
this statement might not apply to you.
This information could include technical inaccuracies or
typographical errors. Changes are periodically made to
the information herein; these changes is incorporated in
new editions of the publication. IBM can make
improvements and/or changes in the products and/or the
programs described in this publication at any time
Any references in this information to non-IBM Web sites
are provided for convenience only and do not in any
manner serve as an endorsement of those Web sites. The
materials at those Web sites are not part of the
materials for this IBM product and use of those Web
sites is at your own risk.
IBM can use or distribute any of the information you
supply in any way it believes appropriate without
incurring any obligation to you.
Licensees of this program who wish to have information
about it for the purpose of enabling: (i) the exchange
of information between independently created programs
and other programs (including this one) and (ii) the
mutual use of the information which has been exchanged,
11400 Burnet Road
Austin, TX 78758 U.S.A.
Such information may be available, subject to
appropriate terms and conditions, including in some
cases payment of a fee.
The licensed program described in this document and all
licensed material available for it are provided by IBM
under terms of the IBM Customer Agreement, IBM
International Program License Agreement or any
equivalent agreement between us.
Any performance data contained herein was determined in
a controlled environment. Therefore, the results
obtained in other operating environments may vary
significantly. Some measurements may have been made on
development-level systems and there is no guarantee that
these measurements will be the same on generally
available systems. Furthermore, some measurement may
have been estimated through extrapolation. Actual
results may vary. Users of this document should verify
the applicable data for their specific environment.
Information concerning non-IBM products was obtained
from the suppliers of those products, their published
announcements or other publicly available sources. IBM
has not tested those products and cannot confirm the
accuracy of performance, compatibility or any other
claims related to non-IBM products. Questions on the
capabilities of non-IBM products should be addressed to
the suppliers of those products.
IBM, the IBM logo, and ibm.com are trademarks or
registered trademarks of International Business Machines
Corp., registered in many jurisdictions worldwide. Other
product and service names might be trademarks of IBM or
other companies. A current list of IBM trademarks is
available on the Web at “Copyright and trademark
Adobe, Acrobat, PostScript and all Adobe-based
trademarks are either registered trademarks or
trademarks of Adobe Systems Incorporated in the United
States, other countries, or both.
Linux is a trademark of Linus Torvalds in the United
States, other countries, or both.
Microsoft, Windows, and the Windows logo are trademarks
of Microsoft Corporation in the United States, other
countries, or both.
UNIX is a registered trademark of The Open Group in the
United States and other countries.
Other company, product, and service names may be
trademarks or service marks of others.