IBM Tivoli Advanced Catalog Management for z/OS...
Transcript of IBM Tivoli Advanced Catalog Management for z/OS...
Tivoli® IBM Tivoli Advanced Catalog Management for z/OS
Monitoring Agent User’s Guide
Version 02.01.00
SC23-7974-00
���
Tivoli® IBM Tivoli Advanced Catalog Management for z/OS
Monitoring Agent User’s Guide
Version 02.01.00
SC23-7974-00
���
Note
Before using this information and the product it supports, read the information in Appendix D, “Notices,” on page 95.
This edition applies to version 02.01.00 of IBM Tivoli Advanced Catalog Management for z/OS (5698-A50) and to all
subsequent releases and modifications until otherwise indicated in new editions.
© Copyright International Business Machines Corporation 2007. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
About this guide . . . . . . . . . . . . . . . . . . . . . . . . ix
Intended audience for this guide . . . . . . . . . . . . . . . . . . . ix
What this guide contains . . . . . . . . . . . . . . . . . . . . . ix
Publications . . . . . . . . . . . . . . . . . . . . . . . . . . x
Prerequisite publications . . . . . . . . . . . . . . . . . . . . . x
Related publications . . . . . . . . . . . . . . . . . . . . . . x
Accessing terminology online . . . . . . . . . . . . . . . . . . . x
Accessing publications online . . . . . . . . . . . . . . . . . . . xi
Ordering publications . . . . . . . . . . . . . . . . . . . . . . xi
Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Tivoli technical training . . . . . . . . . . . . . . . . . . . . . . xii
Support information . . . . . . . . . . . . . . . . . . . . . . . xii
Conventions used in this guide . . . . . . . . . . . . . . . . . . . xii
Typeface conventions . . . . . . . . . . . . . . . . . . . . . xii
Operating system-dependent variables and paths . . . . . . . . . . . xiii
Chapter 1. Overview of the IBM Tivoli Advanced Catalog Management . . . 1
IBM Tivoli Monitoring overview . . . . . . . . . . . . . . . . . . . 1
Features of IBM Tivoli Advanced Catalog Management . . . . . . . . . . 1
IBM Tivoli Advanced Catalog Management functions . . . . . . . . . . . 1
Components of IBM Tivoli Advanced Catalog Management . . . . . . . . . 2
User interface options . . . . . . . . . . . . . . . . . . . . . . . 2
Chapter 2. Requirements for the monitoring agent . . . . . . . . . . . 3
Requirements for the monitoring agent . . . . . . . . . . . . . . . . 3
Chapter 3. How to use a monitoring agent . . . . . . . . . . . . . . 5
View real-time data that the agent collects . . . . . . . . . . . . . . . 5
Investigate an event . . . . . . . . . . . . . . . . . . . . . . . 6
Recover the operation of a resource . . . . . . . . . . . . . . . . . 6
Customize your monitoring environment . . . . . . . . . . . . . . . . 7
Monitor with custom situations that meet your requirements . . . . . . . . . 8
Collect and view historical data . . . . . . . . . . . . . . . . . . . 9
Chapter 4. Workspaces reference . . . . . . . . . . . . . . . . . 11
About workspaces . . . . . . . . . . . . . . . . . . . . . . . . 11
More information about workspaces . . . . . . . . . . . . . . . . . 11
Predefined workspaces . . . . . . . . . . . . . . . . . . . . . . 11
IBM Tivoli Advanced Catalog Management Navigator item . . . . . . . . . 12
Alias Space Navigator item . . . . . . . . . . . . . . . . . . . . 12
Cache Performance Navigator item . . . . . . . . . . . . . . . . . 12
Catalog Dataset Attributes Navigator item . . . . . . . . . . . . . . . 13
Catalog Summary Navigator item . . . . . . . . . . . . . . . . . . 13
Catalog Volume Summary Navigator item . . . . . . . . . . . . . . . 14
Last Catalog Backup Navigator item . . . . . . . . . . . . . . . . . 15
Chapter 5. Attributes reference . . . . . . . . . . . . . . . . . . 17
About attributes . . . . . . . . . . . . . . . . . . . . . . . . 17
More information about attributes . . . . . . . . . . . . . . . . . . 17
Attribute groups and attributes for IBM Tivoli Advanced Catalog Management 17
Alias Space attribute group . . . . . . . . . . . . . . . . . . . . 18
© Copyright IBM Corp. 2007 iii
Cache Performance attribute group . . . . . . . . . . . . . . . . . 19
Catalog Dataset Attributes attribute group . . . . . . . . . . . . . . . 21
Catalog Summary attribute group . . . . . . . . . . . . . . . . . . 24
Catalog Volume Summary attribute group . . . . . . . . . . . . . . . 26
Last Catalog Backup attribute group . . . . . . . . . . . . . . . . . 27
Performance Object Status attribute group . . . . . . . . . . . . . . . 28
Disk capacity planning for historical data . . . . . . . . . . . . . . . 31
Chapter 6. Situations reference . . . . . . . . . . . . . . . . . . 33
About situations . . . . . . . . . . . . . . . . . . . . . . . . 33
More information about situations . . . . . . . . . . . . . . . . . . 33
Predefined situations . . . . . . . . . . . . . . . . . . . . . . . 34
IBM Tivoli Advanced Catalog Management Navigator item . . . . . . . . . 35
Alias Space Navigator item . . . . . . . . . . . . . . . . . . . . 35
KRN_KRN_Alias_Remain_Critical situation . . . . . . . . . . . . . 35
Cache Performance Navigator item . . . . . . . . . . . . . . . . . 35
KRN_KRN_Cat_Hit_Pct_Warning situation . . . . . . . . . . . . . . 35
Catalog Dataset Attributes Navigator item . . . . . . . . . . . . . . . 36
KRN_KRN_Cat_4GB_Limit_Critical situation . . . . . . . . . . . . . 36
KRN_KRN_Cat_Extents_Critical situation . . . . . . . . . . . . . . 36
Catalog Summary Navigator item . . . . . . . . . . . . . . . . . . 37
Catalog Volume Summary Navigator item . . . . . . . . . . . . . . . 37
KRN_KRN_Vol_Pct_Full_Critical situation . . . . . . . . . . . . . . 37
KRN_KRN_Vol_Frag_Idx_Critical situation . . . . . . . . . . . . . . 37
Last Catalog Backup Navigator item . . . . . . . . . . . . . . . . . 38
KRN_KRN_Cat_Backup_Critical situation . . . . . . . . . . . . . . 38
KRN_KRN_Cat_Backup_Warning situation . . . . . . . . . . . . . 38
Chapter 7. Take Action commands reference . . . . . . . . . . . . . 41
About Take Action commands . . . . . . . . . . . . . . . . . . . 41
More information about Take Action commands . . . . . . . . . . . . . 41
Predefined Take Action commands . . . . . . . . . . . . . . . . . 41
SampleAction action . . . . . . . . . . . . . . . . . . . . . . . 42
Chapter 8. Policies reference . . . . . . . . . . . . . . . . . . . 43
About policies . . . . . . . . . . . . . . . . . . . . . . . . . 43
More information about policies . . . . . . . . . . . . . . . . . . . 43
Predefined policies . . . . . . . . . . . . . . . . . . . . . . . 43
Appendix A. IBM Tivoli Enterprise Console event mapping . . . . . . . 45
Appendix B. Problem determination . . . . . . . . . . . . . . . . 49
Gathering product information for IBM Software Support . . . . . . . . . . 49
Built-in problem determination features . . . . . . . . . . . . . . . . 50
Determining whether the problem is caused by the monitoring agent . . . . . 50
Reproducible problems reported as Tivoli Enterprise Portal client problems 50
Irreproducible problems reported as Tivoli Enterprise Portal client problems 53
Problems reported as Tivoli Enterprise Portal Server problems . . . . . . 54
Problems affecting the monitoring agent . . . . . . . . . . . . . . 54
Debugging the persistent data store, Tivoli Data Warehouse, and warehouse
proxy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Setting up a trace on a z/OS system . . . . . . . . . . . . . . . . . 55
Setting up communications tracing . . . . . . . . . . . . . . . . . 56
Setting up RAS1 tracing . . . . . . . . . . . . . . . . . . . . 56
Capturing z/OS logs to send to IBM Software Support . . . . . . . . . 62
Understanding and using the trace logs . . . . . . . . . . . . . . . 66
iv IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Using the Log and Trace Analyzer tool . . . . . . . . . . . . . . . . 67
Problems and workarounds . . . . . . . . . . . . . . . . . . . . 67
Installation and configuration problem determination . . . . . . . . . . 67
Workspace problem determination . . . . . . . . . . . . . . . . . 70
Situation problem determination . . . . . . . . . . . . . . . . . . 71
Support information . . . . . . . . . . . . . . . . . . . . . . . 74
Using IBM Support Assistant . . . . . . . . . . . . . . . . . . . 74
Obtaining fixes . . . . . . . . . . . . . . . . . . . . . . . . 75
Receiving weekly support updates . . . . . . . . . . . . . . . . . 75
Contacting IBM Software Support . . . . . . . . . . . . . . . . . 76
Informational, warning, and error messages . . . . . . . . . . . . . . 78
Message format . . . . . . . . . . . . . . . . . . . . . . . 78
IBM Tivoli Advanced Catalog Management messages . . . . . . . . . 79
Appendix C. Accessibility . . . . . . . . . . . . . . . . . . . . 93
Navigating the interface using the keyboard . . . . . . . . . . . . . . 93
Magnifying what is displayed on the screen . . . . . . . . . . . . . . 93
Appendix D. Notices . . . . . . . . . . . . . . . . . . . . . . 95
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Contents v
vi IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Tables
1. View real-time data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2. Investigating an event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
3. Recover the operation of a resource . . . . . . . . . . . . . . . . . . . . . . . . 7
4. Customizing your monitoring environment . . . . . . . . . . . . . . . . . . . . . . 7
5. Monitor with custom situations . . . . . . . . . . . . . . . . . . . . . . . . . . 9
6. Collect and view historical data . . . . . . . . . . . . . . . . . . . . . . . . . 10
7. Capacity planning for historical data logged by component Advanced Catalog Management 31
8. Log locations for Tivoli Enterprise Portal desktop client . . . . . . . . . . . . . . . . . 51
9. Log locations for Tivoli Enterprise Portal Server . . . . . . . . . . . . . . . . . . . 52
10. Log locations for Tivoli Enterprise Monitoring Server on distributed systems . . . . . . . . . 53
11. Locations of log and trace information for z/OS components . . . . . . . . . . . . . . . 54
© Copyright IBM Corp. 2007 vii
viii IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
About this guide
IBM Tivoli Advanced Catalog Management Monitoring Agent User’s Guide provides
information about using IBM Tivoli Advanced Catalog Management for z/OS.
Use the information in this guide along with IBM Tivoli Monitoring User’s Guide to
monitor IBM Tivoli Advanced Catalog Management.
Intended audience for this guide
This guide is for system administrators who install and use the IBM Tivoli Advanced
Catalog Management to monitor and manage IBM Tivoli Advanced Catalog
Management resources.
Readers should be familiar with the following topics:
v Tivoli Enterprise™ Portal interface
v IBM® Tivoli® Monitoring application software
v IBM Tivoli Enterprise Console® (optional)
v IBM Tivoli Advanced Catalog Management environments
What this guide contains
This guide contains the following chapters:
v Chapter 1, “Overview of the IBM Tivoli Advanced Catalog Management,” on page
1
Provides an introduction to the IBM Tivoli Advanced Catalog Management.
v Chapter 2, “Requirements for the monitoring agent,” on page 3
Provides information about the requirements for the IBM Tivoli Advanced Catalog
Management.
v Chapter 3, “How to use a monitoring agent,” on page 5
Provides a list of tasks to achieve when using a monitoring agent, a list of
procedures for performing each task, and references for where to find information
about the procedures. After completing installation and configuration and
becoming familiar with the information in Chapter 1 of this guide, use this chapter
to see how you can use a monitoring agent.
v Chapter 4, “Workspaces reference,” on page 11
Provides an overview of workspaces, references to additional information about
workspaces, and descriptions of predefined workspaces in this monitoring agent.
v Chapter 5, “Attributes reference,” on page 17
Provides an overview of attributes, references to additional information about
attributes, descriptions of the attribute groups and attributes in this monitoring
agent, and disk space requirements for historical data.
v Chapter 6, “Situations reference,” on page 33
Provides an overview of situations, references to additional information about
situations, and descriptions of the predefined situations in this monitoring agent.
v Chapter 7, “Take Action commands reference,” on page 41
Provides detailed information about the Take Action commands, references to
additional information about Take Action commands, and descriptions of the Take
Action commands provided in this monitoring agent.
v Chapter 8, “Policies reference,” on page 43
© Copyright IBM Corp. 2007 ix
Provides an overview of policies, references for detailed information about
policies, and descriptions of the predefined policies included in this monitoring
agent.
v Appendix A, “IBM Tivoli Enterprise Console event mapping,” on page 45
Provides an overview of the IBM Tivoli Enterprise Console event mapping
information for this monitoring agent.
v Appendix B, “Problem determination,” on page 49
Provides information about troubleshooting the various components of the IBM
Tivoli Advanced Catalog Management, information about log files, and
information about your options for obtaining software support.
v Appendix C, “Accessibility,” on page 93
Provides information about the accessibility features in the IBM Tivoli Advanced
Catalog Management.
v Appendix D, “Notices,” on page 95
Provides IBM and Tivoli notices and trademark information as it applies to the
IBM Tivoli Advanced Catalog Management.
Publications
This section lists publications relevant to the use of the IBM Tivoli Advanced
Catalog Management. It also describes how to access Tivoli publications online and
how to order Tivoli publications.
Prerequisite publications
To use the information in this guide effectively, you must have some knowledge of
IBM Tivoli Monitoring products, which you can obtain from the following books:
v IBM Tivoli Monitoring Administrator’s Guide
v IBM Tivoli Monitoring Installation and Setup Guide
v IBM Tivoli Monitoring Problem Determination Guide
v IBM Tivoli Monitoring User’s Guide
v IBM Tivoli Monitoring Readme First
Related publications
The following documents also provide useful information:
v IBM Tivoli Advanced Catalog Management Monitoring Agent Planning and
Configuration Guide
v IBM Tivoli Advanced Catalog Management User's Guide
v IBM Tivoli Enterprise Console Adapters Guide
v IBM Tivoli Enterprise Console Event Integration Facility User’s Guide
v IBM Tivoli Enterprise Console Reference Manual
v IBM Tivoli Enterprise Console Rule Developer’s Guide
Accessing terminology online
The Tivoli Software Glossary includes definitions for many of the technical terms
related to Tivoli software. The Tivoli Software Glossary is available at the following
Tivoli software library Web site:
http://publib.boulder.ibm.com/tividd/glossary/tivoliglossarymst.htm
x IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
The IBM Terminology Web site consolidates the terminology from IBM product
libraries in one convenient location. You can access the Terminology Web site at the
following Web address:
http://www.ibm.com/ibm/terminology
Accessing publications online
The documentation CD contains the publications that are in the product library. The
format of the publications is PDF, HTML, or both. Refer to the readme file on the
CD for instructions on how to access the documentation.
IBM posts publications for this and all other Tivoli products, as they become
available and whenever they are updated, to the Tivoli software information center
Web site. Access the Tivoli software information center by first going to the Tivoli
software library at the following Web address:
http://publib.boulder.ibm.com/tividd/td/link/tdprodlist.html
In the Tivoli Information Center window, click Tivoli product manuals. Click the
letter that matches the first letter of your product name to access your product
library. For example, click M to access the IBM Tivoli Monitoring library.
Note: If you print PDF documents on other than letter-sized paper, set the option in
the File → Print window that allows Adobe Reader to print letter-sized pages
on your local paper.
Ordering publications
You can order many Tivoli publications online at http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi
You can also order by telephone by calling one of these numbers:
v In the United States: 800-879-2755
v In Canada: 800-426-4968
In other countries, contact your software account representative to order Tivoli
publications. To locate the telephone number of your local representative, perform
the following steps:
1. Go to http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi.
2. Select your country from the list and click Go.
3. Click About this site in the main panel to see an information page that includes
the telephone number of your local representative.
Accessibility
Accessibility features help users with a physical disability, such as restricted mobility
or limited vision, to use software products successfully. With this product, you can
use assistive technologies to hear and navigate the interface. You can also use the
keyboard instead of the mouse to operate most features of the graphical user
interface.
For additional information, see Appendix C, “Accessibility,” on page 93.
About this guide xi
Tivoli technical training
For Tivoli technical training information, refer to the following IBM Tivoli Education
Web site:
http://www.ibm.com/software/tivoli/education/
Support information
“Support information” on page 74 describes the following options for obtaining
support for IBM products:
v “Using IBM Support Assistant” on page 74
v “Obtaining fixes” on page 75
v “Receiving weekly support updates” on page 75
v “Contacting IBM Software Support” on page 76
Conventions used in this guide
This guide uses several conventions for special terms and actions, and operating
system-dependent commands and paths.
Typeface conventions
This guide uses the following typeface conventions:
Bold
v Lowercase commands and mixed case commands that are otherwise
difficult to distinguish from surrounding text
v Interface controls (check boxes, push buttons, radio buttons, spin
buttons, fields, folders, icons, list boxes, items inside list boxes,
multicolumn lists, containers, menu choices, menu names, tabs, property
sheets), labels (such as Tip:, and Operating system considerations:)
v Keywords and parameters in text
Italic
v Citations (examples: titles of books, diskettes, and CDs
v Words defined in text (example: a nonswitched line is called a
point-to-point line)
v Emphasis of words and letters (words as words example: "Use the word
that to introduce a restrictive clause."; letters as letters example: "The
LUN address must start with the letter L.")
v New terms in text (except in a definition list): a view is a frame in a
workspace that contains data.
v Variables and values you must provide: ... where myname represents....
Monospace
v Examples and code examples
v File names, programming keywords, and other elements that are difficult
to distinguish from surrounding text
v Message text and prompts addressed to the user
v Text that the user must type
v Values for arguments or command options
xii IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Operating system-dependent variables and paths
The direction of the slash for directory paths might vary in this documentation. No
matter which type of slash you see in the documentation, use the following
guidelines for a slash:
v If using UNIX®, use a forward slash (/).
v If using Windows®, use a backslash (\).
The names of environment variables are not always the same in Windows and
UNIX. For example, %TEMP% in Windows is equivalent to $TEMP in UNIX.
For environment variables, use the following guidelines:
v If using UNIX, use $variable.
v If using Windows, use %variable%.
Note: If you are using the bash shell on a Windows system, you can use the UNIX
conventions.
About this guide xiii
xiv IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Chapter 1. Overview of the IBM Tivoli Advanced Catalog
Management
The IBM Tivoli Advanced Catalog Management provides you with the capability to
monitor IBM Tivoli Advanced Catalog Management, and to perform basic actions
with IBM Tivoli Advanced Catalog Management. This chapter provides a description
of the features, components, and interface options for the IBM Tivoli Advanced
Catalog Management.
IBM Tivoli Monitoring overview
IBM Tivoli Monitoring is the base software for the IBM Tivoli Advanced Catalog
Management. IBM Tivoli Monitoring provides a way to monitor the availability and
performance of all the systems in your enterprise from one or several designated
workstations. It also provides useful historical data that you can use to track trends
and to troubleshoot system problems.
You can use IBM Tivoli Monitoring to do the following:
v Monitor for alerts on the systems that you are managing by using predefined
situations or custom situations.
v Establish your own performance thresholds.
v Trace the causes leading to an alert.
v Gather comprehensive data about system conditions.
v Use policies to perform actions, schedule work, and automate manual tasks.
The Tivoli Enterprise Portal is the interface for IBM Tivoli Monitoring products. By
providing a consolidated view of your environment, the Tivoli Enterprise Portal
permits you to monitor and resolve performance issues throughout the enterprise.
See the IBM Tivoli Monitoring publications listed in “Prerequisite publications” on
page x for complete information about IBM Tivoli Monitoring and the Tivoli
Enterprise Portal.
Features of IBM Tivoli Advanced Catalog Management
The IBM Tivoli Advanced Catalog Management software can identify, notify you of,
and correct common problems with the application that it monitors. The software
includes the following features:
v Monitoring
v Data gathering
v Event management
v Operations management
IBM Tivoli Advanced Catalog Management functions
IBM Tivoli Advanced Catalog Management provides the following functions:
Catalog Monitoring
Provides monitoring of the ICF catalog environment. The information
provided includes aliases associated with each catalog, catalog allocation
attributes, catalog status, and the return codes for all functions from the last
catalog backup executed.
© Copyright IBM Corp. 2007 1
Components of IBM Tivoli Advanced Catalog Management
After you install and set up the IBM Tivoli Advanced Catalog Management, you
have an environment that contains the client, server, and monitoring agent
implementation for IBM Tivoli Monitoring that contains the following components:
v Tivoli Enterprise Portal client with a Java™-based user interface for viewing and
monitoring your enterprise.
v Tivoli Enterprise Portal Server that is placed between the client and the Tivoli
Enterprise Monitoring Server and enables retrieval, manipulation, and analysis of
data from the monitoring agents. The Tivoli Enterprise Portal Server is the central
repository for all user data.
v Tivoli Enterprise Monitoring Server acts as a collection and control point for alerts
received from the monitoring agents, and collects their performance and
availability data. The Tivoli Enterprise Monitoring Server is also a repository for
historical data.
v Monitoring agent, IBM Tivoli Advanced Catalog Management, installed on the
systems or subsystems that you want to monitor. This monitoring agent collects
and distributes data to a Tivoli Enterprise Portal Server.
IBM Tivoli Enterprise Console is an optional component, which acts as a central
collection point for events from a variety of sources, including those from other
Tivoli software applications, Tivoli partner applications, custom applications, network
management platforms, and relational database systems. You can view these
events through the Tivoli Enterprise Portal (using the event viewer), and you can
forward events from IBM Tivoli Monitoring situations to the IBM Tivoli Enterprise
Console component.
User interface options
Installation of the base software and other integrated applications provides the
following interfaces that you can use to work with your resources and data:
Tivoli Enterprise Portal browser client interface
The browser interface is automatically installed with Tivoli Enterprise Portal.
To start Tivoli Enterprise Portal in your Internet browser, enter the URL for a
specific Tivoli Enterprise Portal browser client installed on your Web server.
Tivoli Enterprise Portal desktop client interface
The desktop interface is a Java-based graphical user interface (GUI) on a
Windows or Linux® workstation.
IBM Tivoli Enterprise Console
Event management application
Manage Tivoli Enterprise Monitoring Services window
The window for the Manage Tivoli Enterprise Monitoring Services utility is
used for configuring the agent and starting Tivoli services not already
designated to start automatically.
2 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Chapter 2. Requirements for the monitoring agent
This chapter contains information about the requirements for the IBM Tivoli
Advanced Catalog Management.
To install and configure the IBM Tivoli Advanced Catalog Management, use the
procedures in the IBM Tivoli Monitoring Installation and Setup Guide and the IBM
Tivoli Advanced Catalog Management Monitoring Agent Planning and Configuration
Guide.
Requirements for the monitoring agent
In addition to the requirements described in the IBM Tivoli Monitoring Installation
and Setup Guide, the IBM Tivoli Advanced Catalog Management has the following
requirements:
v The monitoring agent runs on these operating systems:
– Windows 2003 Server EE (32 bit) with Service Pack 1
v This agent monitors the following versions:
– IBM Tivoli Advanced Catalog Management 2.1
v A single computer that hosts the hub monitoring server, portal server, and a
monitoring agent requires approximately 300 MB of space. A monitored computer
that hosts only the monitoring agent requires approximately 30 MB of space,
including the specific enablement code for the monitoring agent. More space is
required for each additional monitoring agent that you deploy on the monitored
computer.
After you install the IBM Tivoli Monitoring Version 6.1 and the Tivoli Enterprise
Portal, you install the following software that is required for IBM Tivoli Advanced
Catalog Management to operate:
v IBM Tivoli Monitoring 6.1 Fix Pack 5 and Interim Fix 2
v IBM Tivoli Advanced Catalog Management
v IBM Tivoli Advanced Catalog Management Support for Tivoli Enterprise
Monitoring Server
v IBM Tivoli Advanced Catalog Management Support for Tivoli Enterprise Portal
Server
v IBM Tivoli Advanced Catalog Management Support for Tivoli Enterprise Portal
To use the search function for this agent's online help, ensure that you have
selected the IBM Eclipse help server check box when installing the Tivoli Enterprise
Portal Server. The 'Searching Agent Help' topic in this agent's online help contains a
link to the Eclipse help, where the search function is enabled. From the Table of
Contents in the left-hand pane of the help, select the 'Searching Agent Help' topic to
find the link to the Eclipse help in the right-hand pane.
© Copyright IBM Corp. 2007 3
4 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Chapter 3. How to use a monitoring agent
After you have installed and configured a Tivoli Enterprise Monitoring Agent and the
agent is running, you can begin using this agent to monitor your resources. The
following sources of information are relevant to installation and configuration:
v IBM Tivoli Monitoring Installation and Setup Guide
v Chapter 2, “Requirements for the monitoring agent” in the user’s guide for the
agent that you are installing and configuring
This chapter provides information about how to use a monitoring agent to perform
the following tasks:
v “View real-time data that the agent collects”
v “Investigate an event” on page 6
v “Recover the operation of a resource” on page 6
v “Customize your monitoring environment” on page 7
v “Monitor with custom situations that meet your requirements” on page 8
v “Collect and view historical data” on page 9
For each of these tasks, there is a list of procedures that you perform to complete
the task. For the tasks, there is a cross-reference to where you can find information
about performing that procedure. Information about the procedures is located in
subsequent chapters of this user’s guide and in the following publications:
v IBM Tivoli Monitoring User’s Guide
v IBM Tivoli Monitoring Administrator’s Guide
View real-time data that the agent collects
After you install, configure, and start the Tivoli Enterprise Monitoring Agent, the
agent begins monitoring.
Table 1 contains a list of the procedures for viewing the real-time data that the
monitoring agent collects through the predefined situations. The table also contains
a cross-reference to where you can find information about each procedure.
Table 1. View real-time data
Procedure Where to find information
View the hierarchy of your monitored
resources from a system point of view
(Navigator view organized by operating
system type, monitoring agents, and
workspaces).
IBM Tivoli Monitoring User’s Guide:
″Navigating through workspaces″ (in
″Monitoring: real-time and event-based″
chapter)
View the indicators of real or potential
problems with the monitored resources
(Navigator view).
View changes in the status of the resources
that are being monitored (Enterprise
Message Log view).
IBM Tivoli Monitoring User’s Guide: ″Using
workspaces″ (in ″Monitoring: real-time and
event-based″ chapter)
Chapter 4, “Workspaces reference,” on page
11 in this guide
© Copyright IBM Corp. 2007 5
Table 1. View real-time data (continued)
Procedure Where to find information
View the number of times an event has been
opened for a situation during the past 24
hours (Open Situations Account view).
IBM Tivoli Monitoring User’s Guide: ″Using
workspaces″ (in ″Monitoring: real-time and
event-based″ chapter)
Chapter 4, “Workspaces reference,” on page
11 in this guide
Chapter 6, “Situations reference,” on page 33
in this guide
Manipulate the views in a workspace. IBM Tivoli Monitoring User’s Guide: ″Using
views″ (in ″Monitoring: real-time and
event-based″ chapter)
Investigate an event
When the conditions of a situation have been met, an event indicator is displayed in
the Navigator. When an event occurs, you want to obtain information about that
event so you can correct the conditions and keep your enterprise running smoothly.
Table 2 contains a list of the procedures for investigating an event and a
cross-reference to where you can find information about each procedure.
Table 2. Investigating an event
Procedure Where to find information
Determine which situation raised the event
and identify the attributes that have values
that are contributing to the alert.
IBM Tivoli Monitoring User’s Guide:
″Opening the situation event workspace″ (in
″Monitoring: real-time and event-based″
chapter, ″Responding to alerts″ section)
Chapter 4, “Workspaces reference,” on page
11 in this guide
Review available advice.
Notify other users that you have taken
ownership of the problem related to an event
and are working on it.
IBM Tivoli Monitoring User’s Guide:
″Acknowledging a situation event″ (in
″Monitoring: real-time and event-based″
chapter, ″Responding to alerts″ section)
Remove the event from the Navigator. IBM Tivoli Monitoring User’s Guide: ″Closing
the situation event workspace″ (in
″Monitoring: real-time and event-based″
chapter, ″Responding to alerts″ section)
Recover the operation of a resource
When you find out that a resource is not operating as desired, you can control it
manually or automatically using Take Action commands.
Table 3 on page 7 contains a list of the procedures for recovering the operation of a
resource and a cross-reference to where you can find information about each
procedure.
6 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Table 3. Recover the operation of a resource
Procedure Where to find information
Take an action on a resource manually. IBM Tivoli Monitoring User’s Guide:
v ″Other views″ (in ″Custom workspaces″
chapter, ″Workspace views″ section)
v ″Take action: Reflex automation″ (in
Situations for event-based monitoring″
chapter, ″Event-based monitoring
overview″ section)
v "Take action" (in "Designing customized
responses" chapter)
Chapter 7, “Take Action commands
reference,” on page 41 in this guide
Take an action on a system condition
automatically by setting up a situation to run
a Take Action command.
IBM Tivoli Monitoring User’s Guide:
″Situations for event-based monitoring″
chapter
v ″Customize a situation″
v ″Create a situation″
v ″Specify an action to take″
v ″Distribute the situation″
Chapter 7, “Take Action commands
reference,” on page 41 in this guide
Take multiple actions on system conditions
automatically using a policy.
IBM Tivoli Monitoring User’s Guide: ″Policies
for automation″ chapter
v ″Creating a policy″
v ″Maintaining policies″
v ″Workflows window″
Chapter 8, “Policies reference,” on page 43
in this guide
Take actions across systems, agents, or
computers using a policy.
Customize your monitoring environment
You can change how your monitoring environment looks by creating new
workspaces with one or more views in it.
Table 4 contains a list of the procedures for customizing your monitoring
environment and a cross-reference to where you can find information about each
procedure.
Table 4. Customizing your monitoring environment
Procedure Where to find information
Display data in tables or charts (views) in the
Tivoli Enterprise Portal.
IBM Tivoli Monitoring User’s Guide:
v ″Custom workspaces″
v ″Table and chart views″
Display an overview of changes in the status
of situations for your monitored resources
(Message Log View).
IBM Tivoli Monitoring User’s Guide:
″Message log view″ (in ″Situation event
views: message log, situation event console
and graphic″ chapter)
Chapter 3. How to use a monitoring agent 7
Table 4. Customizing your monitoring environment (continued)
Procedure Where to find information
Specify which attributes to retrieve for a table
or chart so you can retrieve only the data
you want by creating custom queries.
IBM Tivoli Monitoring User’s Guide:
″Creating custom queries″ (in ″Table and
chart views″ chapter)
Chapter 5, “Attributes reference,” on page 17
in this guide
Build links from one workspace to another. IBM Tivoli Monitoring User’s Guide:
v ″Link from a workspace″ (in ″Custom
workspaces″ chapter)
v ″Link from a table or chart″ (in ″Table and
chart views″ chapter)
Identify which predefined situations started
running automatically when you started the
Tivoli Enterprise Monitoring Server.
IBM Tivoli Monitoring User’s Guide: ″What
the enterprise workspace shows″ (in
″Monitoring: real-time and event-based″
chapter, ″Using workspaces″ section)
Chapter 6, “Situations reference,” on page 33
in this guide
Determine whether to run situations as
defined, modify the values in situations, or
create new situations to detect possible
problems.
Chapter 6, “Situations reference,” on page 33
in this guide
Monitor with custom situations that meet your requirements
When your environment requires situations with values that are different from those
in the existing situations, or when you need to monitor conditions not defined by the
existing situations, you can create custom situations to detect problems with
resources in two ways:
v Create an entirely new situation
v Create a situation by copying and editing a predefined situation
You can specify the following information for a situation:
v Name
v Attribute group and attributes
v Qualification to evaluate multiple rows when a situation has a multiple-row
attribute group (display item)
v Formula
v Take Action commands
v Run at startup
v Sampling interval
v Persistence
v Manual or automatic start
v Severity
v Clearing conditions
v Expert Advice
v When a true situation closes
v Available Managed Systems
8 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Table 5 contains a list of the procedures for monitoring your resources with custom
situations that meet your requirements and a cross-reference to where you can find
information about each procedure.
Table 5. Monitor with custom situations
Procedure Where to find information
Create an entirely new situation. IBM Tivoli Monitoring User’s Guide:
″Creating a new situation″ (in ″Situations for
event-based monitoring″ chapter, ″Creating a
situation″ section)
Chapter 5, “Attributes reference,” on page 17
in this guide
Create a situation by copying and editing a
predefined situation.
IBM Tivoli Monitoring User’s Guide:
″Customize a situation″ (in ″Situations for
event-based monitoring″ chapter)
Chapter 6, “Situations reference,” on page 33
in this guide
Chapter 5, “Attributes reference,” on page 17
in this guide
Run a situation on a managed system. IBM Tivoli Monitoring User’s Guide:
″Situations for event-based monitoring″
chapter
v ″Associating situations with navigator
items″
v ″Distribute the situation″ (in ″Customizing
a situation″ section)
v ″Starting, stopping or deleting a situation″
Collect and view historical data
When you collect historical data, you specify the following configuration
requirements:
v Attribute groups for which to collect data
v Collection interval
v Summarization and pruning of attribute groups
v Roll-off interval to a data warehouse, if any
v Where to store the collected data (at the agent or the Tivoli Enterprise
Management Server)
Table 6 on page 10 contains a list of the procedures for collecting and viewing
historical data and a cross-reference to where you can find information about each
procedure.
Chapter 3. How to use a monitoring agent 9
Table 6. Collect and view historical data
Procedure Where to find information
Configure and start collecting short-term data
(24 hours).
IBM Tivoli Monitoring User’s Guide:
″Historical reporting″ (in ″Table and chart
views″ chapter)
IBM Tivoli Monitoring Administrator’s Guide
“Disk capacity planning for historical data” on
page 31 in this guide
Configure and start collecting longer-term
data (more than 24 hours).
View historical data in the Tivoli Enterprise
Portal.
Create reports from historical data using
third-party reporting tools.
Filter out unwanted data to see specific
areas of interest.
10 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Chapter 4. Workspaces reference
This chapter contains an overview of workspaces, references for detailed
information about workspaces, and descriptions of the predefined workspaces
included in this monitoring agent.
About workspaces
A workspace is the working area of the Tivoli Enterprise Portal application window.
At the left of the workspace is a Navigator that you use to select the workspace you
want to see.
As you select items in the Navigator, the workspace presents views pertinent to
your selection. Each workspace has at least one view. Every workspace has a set
of properties associated with it.
This monitoring agent provides predefined workspaces. You cannot modify or delete
the predefined workspaces, but you can create new workspaces by editing them
and saving the changes with a different name.
More information about workspaces
For more information about creating, customizing, and working with workspaces,
see IBM Tivoli Monitoring User’s Guide.
For a list of the predefined workspaces for this monitoring agent and a description
of each workspace, refer to the Predefined workspaces section in this chapter and
the information in that section for each individual workspace.
Some attribute groups for this agent might not be represented in the predefined
workspaces or views for this agent. For a full list of the attribute groups, see the
Attributes reference section.
Predefined workspaces
IBM Tivoli Advanced Catalog Management provides the following predefined
workspaces, which are organized by Navigator item:
v IBM Tivoli Advanced Catalog Management Navigator item
– IBM Tivoli Advanced Catalog Management workspace
v Alias Space Navigator item
– Alias Space workspace
– Alias Space Trend workspace
v Cache Performance Navigator item
– Cache Performance workspace
– Catalog Details workspace
v Catalog Dataset Attributes Navigator item
– Catalog Dataset Attributes workspace
– Catalog Details workspace
v Catalog Summary Navigator item
– Catalog Summary workspace
– Catalog Details workspace
© Copyright IBM Corp. 2007 11
v Catalog Volume Summary Navigator item
– Catalog Volume Summary workspace
– Catalog Volume Details workspace
v Last Catalog Backup Navigator item
– Last Catalog Backup workspace
The remaining sections of this chapter contain descriptions of each of these
predefined workspaces. The workspaces are organized by the Navigator item to
which the workspaces are relevant.
IBM Tivoli Advanced Catalog Management Navigator item
IBM Tivoli Advanced Catalog Management workspace
Workspace description
This workspace contains the following view:
View name
View description.
Alias Space Navigator item
Alias Space workspace
The Alias Space workspace displays the number of aliases associated with
each user catalog and approximately how many more can be defined for
each catalog listed.
This workspace contains the following views:
Space for < 50 New Aliases
View description.
Report
View description.
Alias Space Trend workspace
The Alias Space Trend workspace displays alias details about the selected
catalog.
This workspace contains the following views:
Remaining Aliases
The remaining aliases for the selected catalog.
Total Alias Length
The total alias length for the selected catalog.
Cache Performance Navigator item
Cache Performance workspace
The Cache Performance workspace displays caching information for each
catalog from the catalog address space.
This workspace contains the following views:
Catalog Cache Hit% < 50
Description.
Report
Description.
12 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Catalog Details workspace
The Catalog Details workspace displays details about the selected catalog.
This workspace contains the following views:
Extents
The number of extents for the selected catalog.
Free Space
The amount of free space available for the selected catalog.
Hit % The percentage of hits against the selected catalog.
Remaining Aliases
The remaining aliases for the selected catalog.
Catalog Dataset Details
The data set details for the selected catalog.
Catalog Volume Details
The catalog volume details for the selected catalog.
Catalog Dataset Attributes Navigator item
Catalog Dataset Attributes workspace
The Catalog Dataset Attributes workspace displays information on catalog
allocation attributes and their status.
This workspace contains the following views:
10 Largest Catalogs with %4GB Limit >=1
Description.
Report
Data set statistics for each catalog.
Catalog Details workspace
The Catalog Details workspace displays details about the selected catalog.
This workspace contains the following views:
Extents
The number of extents for the selected catalog.
Free Space
The amount of free space available for the selected catalog.
Hit % The percentage of hits against the selected catalog.
Remaining Aliases
The remaining aliases for the selected catalog.
Catalog Dataset Details
The data set details for the selected catalog.
Catalog Volume Details
The catalog volume details for the selected catalog.
Catalog Summary Navigator item
Catalog Summary workspace
The Catalog Summary workspace displays a high-level overview of all the
catalogs and their status.
This workspace contains the following views:
Chapter 4. Workspaces reference 13
Report
Statistics for the catalog.
Most Extents
Catalogs with the most extents.
Fewest Remaining Aliases
Catalogs with the fewest remaining aliases.
Catalog Details workspace
The Catalog Details workspace displays details about the selected catalog.
This workspace contains the following views:
Extents
The number of extents for the selected catalog.
Free Space
The amount of free space available for the selected catalog.
Hit % The percentage of hits against the selected catalog.
Remaining Aliases
The remaining aliases for the selected catalog.
Catalog Dataset Details
The data set details for the selected catalog.
Catalog Volume Details
The catalog volume details for the selected catalog.
Catalog Volume Summary Navigator item
Catalog Volume Summary workspace
The Catalog Volume Summary workspace displays space information for
volumes on which catalogs are allocated.
This workspace contains the following views:
Report
View description.
Catalog Volumes > 90% Full
View description.
Catalog Volumes Frag. > 300
View description.
Catalog Volume Details workspace
The Catalog Volume Details workspace displays additional catalog volume
details about the selected catalog.
This workspace contains the following views:
Catalog Volume Attributes
The attributes for the volume on which the selected catalog was
allocated.
Dataset Attribues
The attributes for the data set on which the seelected catalog was
allocated.
Catalog Cache Peformance
The caching information for the selected catalog from the catalog
address space.
14 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Volume % Full
The percentage of the volume used by the selected catalog.
Volume Fragmentation Index
The fragementation index of the volume used for the selected
catalog.
Last Catalog Backup Navigator item
Last Catalog Backup workspace
The Last Catalog Backup workspace displays return codes for all functions
of the last catalog backup executed.
This workspace contains the following views:
Backups with Non-Zero Return Codes
Statistics for catalogs with a non-zero return code.
Report
Dignose, Backup, Examine, and Verify statistics.
Chapter 4. Workspaces reference 15
16 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Chapter 5. Attributes reference
This chapter contains an overview of attributes, references for detailed information
about attributes, and descriptions of the attributes for each attribute group included
in this monitoring agent.
About attributes
Attributes are the application properties being measured and reported by IBM Tivoli
Advanced Catalog Management.
Attributes are organized into groups according to their purpose. The attributes in a
group can be used in the following two ways:
v Chart or table views
Attributes are displayed in chart and table views. The chart and table views use
queries to specify which attribute values to request from a monitoring agent. You
use the Query editor to create a new query, modify an existing query, or apply
filters and set styles to define the content and appearance of a view based on an
existing query.
v Situations
You use attributes to create situations that monitor the state of your operating
system, database, or application. A situation describes a condition you want to
test. When you start a situation, the Tivoli Enterprise Portal compares the values
you have assigned to the situation attributes with the values collected by IBM
Tivoli Advanced Catalog Management and registers an event if the condition is
met. You are alerted to events by indicator icons that are displayed in the
Navigator.
More information about attributes
For more information about using attributes and attribute groups, see IBM Tivoli
Monitoring User’s Guide.
For a list of the attributes groups, a list of the attributes in each attribute group, and
descriptions of the attributes for this monitoring agent, refer to the Attribute groups
and attributes section in this chapter.
Attribute groups and attributes for IBM Tivoli Advanced Catalog
Management
This monitoring agent contains the following attribute groups:
v Alias Space
v Cache Performance
v Catalog Dataset Attributes
v Catalog Summary
v Catalog Volume Summary
v Last Catalog Backup
v Performance Object Status
© Copyright IBM Corp. 2007 17
The remaining sections of this chapter contain descriptions of these attribute
groups, which are listed alphabetically. The following information is provided for
each attribute group:
Attributes
List of attributes that belong to the attribute group
Historical group
Whether the attribute group is a historical type that you can roll off to a data
warehouse
Attribute descriptions
Description and type for each attribute in the attribute group
Alias Space attribute group
This attribute group provides catalog alias space statistics. If the warehouse default
setting is enabled, data for this attribute group is stored in Tivoli Data Warehouse.
Historical group
This attribute group is part of the default historical group.
Attribute descriptions
The following list contains information about each attribute in the Alias Space
attribute group:
Node attribute - This attribute is a key attribute.
Description
The managed system name of the agent.
Type String
Timestamp attribute
Description
The local time at the agent when the data was collected.
Type String
BCSNAME attribute - This attribute is a key attribute.
Description
The catalog name.
Type String
VOLSER attribute
Description
The volume serial name of the DASD where the catalog resides.
Type String
ALIASCOUNT attribute
Description
The number of aliases.
Type Integer (Counter)
ALIASAVLEN attribute
18 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Description
The average alias name length.
Type Integer (Counter)
ALIASROOM attribute
Description
The approximate number of remaining aliases.
Type Integer (Counter)
ALIASTLEN attribute
Description
The total length consumed by aliases, including per-record
overhead.
Type Integer (Counter)
Cache Performance attribute group
This attribute group provides catalog cache performance statistics. If the warehouse
default setting is enabled, data for this attribute group is stored in Tivoli Data
Warehouse.
Historical group
This attribute group is part of the default historical group.
Attribute descriptions
The following list contains information about each attribute in the Cache
Performance attribute group:
Node attribute - This attribute is a key attribute.
Description
The managed system name of the agent.
Type String
Timestamp attribute
Description
The local time at the agent when the data was collected.
Type String
BCSNAME attribute - This attribute is a key attribute.
Description
The name of the catalog.
Type String
VOLSER attribute - This attribute is a key attribute.
Description
Volume Serial
Type String
CCHRECORDS attribute
Description
Number of catalog cache records
Chapter 5. Attributes reference 19
Type Integer (Counter)
CCHSEARCH attribute
Description
Number of catalog cache searches
Type Integer (Counter)
CCHFOUND attribute
Description
Number of catalog cache hits
Type Integer (Counter)
CCHDELETE attribute
Description
Number of catalog cache deletes
Type Integer (Counter)
CCHUPDATE attribute
Description
Number of catalog cache updates
Type Integer (Counter)
CCHPURGE attribute
Description
Number of catalog cache purges
Type Integer (Counter)
CCHPCTHIT attribute
Description
Catalog cache hit percentage
Type Integer (Gauge)
CATTYPE attribute
Description
Catalog type
Type Integer with enumerated values. The strings are displayed in the
Tivoli Enterprise Portal. The warehouse and queries return the
values shown in parentheses. The following values are defined:
v n/a (0)
v Master (1)
v User (2)
v Volcat (3)
Any other values will display the actual value returned by the agent
in the Tivoli Enterprise Portal.
CACHETYPE attribute
Description
Type of cache
Type Integer with enumerated values. The strings are displayed in the
20 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Tivoli Enterprise Portal. The warehouse and queries return the
values shown in parentheses. The following values are defined:
v n/a (0)
v ISC (1)
v CDSC (2)
v CLOSED (3)
Any other values will display the actual value returned by the agent
in the Tivoli Enterprise Portal.
Catalog Dataset Attributes attribute group
This attribute group provides catalog data set attributes. If the warehouse default
setting is enabled, data for this attribute group is stored in Tivoli Data Warehouse.
Historical group
This attribute group is part of the default historical group.
Attribute descriptions
The following list contains information about each attribute in the Catalog Dataset
Attributes attribute group:
Node attribute - This attribute is a key attribute.
Description
The managed system name of the agent.
Type String
Timestamp attribute
Description
The local time at the agent when the data was collected.
Type String
BCSNAME attribute - This attribute is a key attribute.
Description
The catalog name.
Type String
VOLSER attribute
Description
The volume serial number of the DASD where the catalog resides.
Type String
EXTENTS attribute
Description
The number of DASD extents used by the catalog.
Type Integer (Counter)
XHURBA attribute
Description
The High-Used RBA of the catalog’s data component.
Type Integer (Counter)
Chapter 5. Attributes reference 21
XHARBA attribute
Description
The High-Allocated RBA of the catalog’s data component.
Type Integer (Counter)
CICA attribute
Description
The number of control intervals in the control area for the catalog’s
data component.
Type Integer (Counter)
CISIZE attribute
Description
The control interval size, in bytes, used by the catalog’s data
component.
Type Integer (Counter)
PCTUSEDCA attribute
Description
The percentage of the HARBA for the catalog’s data component.
Type Integer (Gauge)
NUMUSEDCA attribute
Description
The number of control areas within the HURBA for the catalog’s
data component.
Type Integer (Counter)
ALLOCCAS attribute
Description
The allocation status to CAS.
Type Integer with enumerated values. The strings are displayed in the
Tivoli Enterprise Portal. The warehouse and queries return the
values shown in parentheses. The following values are defined:
v n/a (0)
v No (1)
v Yes (2)
Any other values will display the actual value returned by the agent
in the Tivoli Enterprise Portal.
SMS attribute
Description
The SMS-managed status.
Type Integer with enumerated values. The strings are displayed in the
Tivoli Enterprise Portal. The warehouse and queries return the
values shown in parentheses. The following values are defined:
v n/a (0)
v No (1)
v Yes (2)
22 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Any other values will display the actual value returned by the agent
in the Tivoli Enterprise Portal.
CACHETYPE attribute
Description
The type of cache.
Type Integer with enumerated values. The strings are displayed in the
Tivoli Enterprise Portal. The warehouse and queries return the
values shown in parentheses. The following values are defined:
v n/a (0)
v ISC (1)
v CDSC (2)
v CLOSED (3)
Any other values will display the actual value returned by the agent
in the Tivoli Enterprise Portal.
CATSHARED attribute
Description
The shared catalog status.
Type Integer with enumerated values. The strings are displayed in the
Tivoli Enterprise Portal. The warehouse and queries return the
values shown in parentheses. The following values are defined:
v n/a (0)
v No (1)
v Yes (2)
Any other values will display the actual value returned by the agent
in the Tivoli Enterprise Portal.
ECS attribute
Description
The Extended Catalog Sharing status.
Type Integer with enumerated values. The strings are displayed in the
Tivoli Enterprise Portal. The warehouse and queries return the
values shown in parentheses. The following values are defined:
v n/a (0)
v No (1)
v Yes (2)
Any other values will display the actual value returned by the agent
in the Tivoli Enterprise Portal.
CATLOCKED attribute
Description
The catalog locked status.
Type Integer with enumerated values. The strings are displayed in the
Tivoli Enterprise Portal. The warehouse and queries return the
values shown in parentheses. The following values are defined:
v n/a (0)
v No (1)
v Yes (2)
Chapter 5. Attributes reference 23
Any other values will display the actual value returned by the agent
in the Tivoli Enterprise Portal.
ALLOCTYPE attribute
Description
The unit type used to allocate DASD space for the catalog’s data
component.
Type Integer with enumerated values. The strings are displayed in the
Tivoli Enterprise Portal. The warehouse and queries return the
values shown in parentheses. The following values are defined:
v n/a (0)
v TRKS (1)
v CYLS (2)
Any other values will display the actual value returned by the agent
in the Tivoli Enterprise Portal.
PRIALLOC attribute
Description
The primary space allocation of DASD space for the catalog’s data
component.
Type Integer (Counter)
SECALLOC attribute
Description
The secondary space allocation of DASD space for the catalog’s
data component.n
Type Integer (Counter)
PCT4GBLIM attribute
Description
The HURBA expressed as a percentage of 4 gigabytes.
Type Integer (Gauge)
Catalog Summary attribute group
This attribute group provides summary statisitics of the catalog environment. If the
warehouse default setting is enabled, data for this attribute group is stored in Tivoli
Data Warehouse.
Historical group
This attribute group is part of the default historical group.
Attribute descriptions
The following list contains information about each attribute in the Catalog Summary
attribute group:
Node attribute - This attribute is a key attribute.
Description
The managed system name of the agent.
Type String
24 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Timestamp attribute
Description
The local time at the agent when the data was collected.
Type String
BCSNAME attribute - This attribute is a key attribute.
Description
The catalog name.
Type String
VOLSER attribute
Description
The volume serial number of the DASD where the catalog resides.
Type String
EXTENTS attribute
Description
The number of DASD extents used by the catalog.
Type Integer (Counter)
ALIASROOM attribute
Description
The approximate number of remaining aliases.
Type Integer (Counter)
STRINGS attribute
Description
The number of strings currently assigned to the catalog.
Type Integer (Counter)
CATTYPE attribute
Description
Catalog type.
Type Integer with enumerated values. The strings are displayed in the
Tivoli Enterprise Portal. The warehouse and queries return the
values shown in parentheses. The following values are defined:
v n/a (0)
v Master (1)
v User (2)
v Volcat (3)
Any other values will display the actual value returned by the agent
in the Tivoli Enterprise Portal.
LBKPSTMPL attribute
Description
Last backup timestamp, given in the local time of the target system.
Type Timestamp
LBKPRC attribute
Chapter 5. Attributes reference 25
Description
Backup return code
Type Integer (Counter)
Catalog Volume Summary attribute group
This attribute group provides catalog volume summary statistics. If the warehouse
default setting is enabled, data for this attribute group is stored in Tivoli Data
Warehouse.
Historical group
This attribute group is part of the default historical group.
Attribute descriptions
The following list contains information about each attribute in the Catalog Volume
Summary attribute group:
Node attribute - This attribute is a key attribute.
Description
The managed system name of the agent.
Type String
Timestamp attribute
Description
The local time at the agent when the data was collected.
Type String
VOLSER attribute - This attribute is a key attribute.
Description
The volume serial number of the DASD where the catalog resides.
Type String
FREESPC attribute
Description
The amount of free space.
Type Integer (Counter)
ALLOCSPC attribute
Description
The amount of allocated space.
Type Integer (Counter)
DEVCAP attribute
Description
The total capacity of the device.
Type Integer (Counter)
HIFREEEXT attribute
Description
The size of largest free extent.
26 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Type Integer (Counter)
FRAGIDX attribute
Description
The device fragmentation index.
Type Integer (Counter)
PCTFULL attribute
Description
The percent full.
Type Integer (Gauge)
Last Catalog Backup attribute group
This attribute group provides a summary of the last catalog backups. If the
warehouse default setting is enabled, data for this attribute group is stored in Tivoli
Data Warehouse.
Historical group
This attribute group is part of the default historical group.
Attribute descriptions
The following list contains information about each attribute in the Last Catalog
Backup attribute group:
Node attribute - This attribute is a key attribute.
Description
The managed system name of the agent.
Type String
Timestamp attribute
Description
The local time at the agent when the data was collected.
Type String
BCSNAME attribute - This attribute is a key attribute.
Description
The catalog name.
Type String
LBKPNAME attribute
Description
Backup file name for last backup.
Type String
LBKPVOLSER attribute
Description
Backup volser for last backup.
Type String
LSTRTSTMPL attribute
Chapter 5. Attributes reference 27
Description
Last backup start date, given in local time of target system.
Type Timestamp
LENDSTMPL attribute
Description
Last backup end date, given in local time of target system.
Type Timestamp
LSTRTSTMPU attribute
Description
Last backup start date, given in UTC time.
Type Timestamp
LENDSTMPU attribute
Description
Last backup end date, given in UTC time.
Type Timestamp
LBKPRC attribute
Description
Backup return code for the last backup.
Type Integer (Counter)
LDIAGRC attribute
Description
Diagnose return code from last backup
Type Integer (Counter)
LEXAMRC attribute
Description
Examine return code from last backup
Type Integer (Counter)
LVFYRC attribute
Description
Verify return code from last backup
Type Integer (Counter)
Performance Object Status attribute group
This table reflects the status of other attribute groups so you can see the status of
all of the performance objects that make up this application all at once. Each of
these other performance attribute groups is represented by a row in this table (or
other type of view). The status for an attribute group reflects the result of the last
attempt to collect data for that attribute group, which allows you to see whether the
agent is performing correctly. Unlike other attribute groups, the Performance Object
Status attribute group does not reflect the state of the monitored application. This
attribute group is most often used to determine why data is not available for one of
the performance attribute groups. If the warehouse default setting is enabled, data
for this attribute group is stored in Tivoli Data Warehouse.
28 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Historical group
This attribute group is part of the default historical group.
Attribute descriptions
The following list contains information about each attribute in the Performance
Object Status attribute group:
Node attribute - This attribute is a key attribute.
Description
The managed system name of the agent.
Type String
Timestamp attribute
Description
The local time at the agent when the data was collected.
Type String
Query Name attribute - This attribute is a key attribute.
Description
The name of the attribute group.
Type String
Object Name attribute
Description
The name of the performance object.
Type String
Object Type attribute
Description
The type of the performance object.
Type Integer with enumerated values. The strings are displayed in the
Tivoli Enterprise Portal. The warehouse and queries return the
values shown in parentheses. The following values are defined:
v WMI (0)
v PERFMON (1)
v WMI_ASSOCIATION_GROUP (2)
v JMX (3)
v SNMP (4)
v SHELL_COMMAND (5)
v JOINED_GROUPS (6)
v CIMOM (7)
v CUSTOM (8)
v ROLLUP_DATA (9)
v WMI_REMOTE_DATA (10)
v LOG_FILE (11)
Any other values will display the actual value returned by the agent
in the Tivoli Enterprise Portal.
Object Status attribute
Chapter 5. Attributes reference 29
Description
The status of the performance object.
Type Integer with enumerated values. The strings are displayed in the
Tivoli Enterprise Portal. The warehouse and queries return the
values shown in parentheses. The following values are defined:
v ACTIVE (0)
v INACTIVE (1)
Any other values will display the actual value returned by the agent
in the Tivoli Enterprise Portal.
Error Code attribute
Description
The error code associated with the query
Type Integer with enumerated values. The strings are displayed in the
Tivoli Enterprise Portal. The warehouse and queries return the
values shown in parentheses. The following values are defined:
v NO_ERROR (0)
v GENERAL_ERROR (1)
v OBJECT_NOT_FOUND (2)
v COUNTER_NOT_FOUND (3)
v NAMESPACE_ERROR (4)
v OBJECT_CURRENTLY_UNAVAILABLE (5)
v COM_LIBRARY_INIT_FAILURE (6)
v SECURITY_INIT_FAILURE (7)
v PROXY_SECURITY_FAILURE (9)
v NO_INSTANCES_RETURNED (10)
v ASSOCIATOR_QUERY_FAILED (11)
v REFERENCE_QUERY_FAILED (12)
v NO_RESPONSE_RECEIVED (13)
v CANNOT_FIND_JOINED_QUERY (14)
v CANNOT_FIND_JOIN_ATTRIBUTE_IN_QUERY_1_RESULTS
(15)
v CANNOT_FIND_JOIN_ATTRIBUTE_IN_QUERY_2_RESULTS
(16)
v QUERY_1_NOT_A_SINGLETON (17)
v QUERY_2_NOT_A_SINGLETON (18)
v NO_INSTANCES_RETURNED_IN_QUERY_1 (19)
v NO_INSTANCES_RETURNED_IN_QUERY_2 (20)
v CANNOT_FIND_ROLLUP_QUERY (21)
v CANNOT_FIND_ROLLUP_ATTRIBUTE (22)
v FILE_OFFLINE (23)
v NO_HOSTNAME (24)
v MISSING_LIBRARY (25)
v ATTRIBUTE_COUNT_MISMATCH (26)
v ATTRIBUTE_NAME_MISMATCH (27)
v COMMON_DATA_PROVIDER_NOT_STARTED (28)
v CALLBACK_REGISTRATION_ERROR (29)
30 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
v MDL_LOAD_ERROR (30)
v AUTHENTICATION_FAILED (31)
Any other values will display the actual value returned by the agent
in the Tivoli Enterprise Portal.
Disk capacity planning for historical data
Disk capacity planning for a monitoring agent is a prediction of the amount of disk
space to be consumed for each attribute group whose historical data is being
collected. Required disk storage is an important factor to consider when you are
defining data collection rules and your strategy for historical data collection.
The table in this chapter provides the following information required to calculate disk
space for this agent:
v Table is the table name as it is displayed in the warehouse database, if the
attribute group is configured to be written to the warehouse.
v Attribute group is the name of the attribute group as it is displayed in the
warehouse configuration panel.
v Bytes per instance (agent) is an estimate of the record length for each row or
instance written to the agent disk for historical data collection. This estimate can
be used for agent disk space planning purposes.
v Database bytes per instance (warehouse) is an estimate of the record length for
detailed records written to the warehouse database, if the attribute group is
configured to be written to the warehouse. Detailed records are those that have
been uploaded from the agent for long-term historical data collection. This
estimate can be used for warehouse disk space planning purposes.
v Aggregate bytes per instance (warehouse) is an estimate of the record length for
aggregate records written to the warehouse database, if the attribute group is
configured to be written to the warehouse. Aggregate records are created by the
Summarization agent for attribute groups that have been configured for
summarization. This estimate can be used for warehouse disk space planning
purposes.
In addition to the information in the tables, you must know the number of instances
of data that you plan to collect. An attribute group can have single or multiple
instances of data depending on the application environment that is being monitored.
For example, if your attribute group is monitoring each processor in your computer
and you have a dual processor computer, the number of instances is 2.
The following table contains capacity planning information for the data logged by
IBM Tivoli Advanced Catalog Management.
Table 7. Capacity planning for historical data logged by component Advanced Catalog Management
Table Attribute group
Bytes per
instance
(agent)
Database
bytes per
instance
(warehouse)
Aggregate
bytes per
instance
(warehouse)
KRNALSPC KRN_ALIAS_SPACE 142 144 241
KRNCCHPRF KRN_CACHE_PERFORMANCE 162 169 335
KRNCATDSA KRN_CATALOG_DATASET_ATTRIBUTES 194 209 444
KRNCATSUM KRN_CATALOG_SUMMARY 162 166 263
KRNCATVOL KRN_CATALOG_VOLUME_SUMMARY 106 109 260
Chapter 5. Attributes reference 31
Table 7. Capacity planning for historical data logged by component Advanced Catalog Management (continued)
Table Attribute group
Bytes per
instance
(agent)
Database
bytes per
instance
(warehouse)
Aggregate
bytes per
instance
(warehouse)
KRNLBKP KRN_LAST_CATALOG_BACKUP 250 257 354
KRNPOBJST KRN_PERFORMANCE_OBJECT_STATUS 288 289 326
For more information about historical data collection, see the IBM Tivoli Monitoring
Administrator’s Guide.
32 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Chapter 6. Situations reference
This chapter contains an overview of situations, references for detailed information
about situations, and descriptions of the predefined situations included in this
monitoring agent.
About situations
A situation is a logical expression involving one or more system conditions.
Situations are used to monitor the condition of systems in your network. You can
manage situations from Tivoli Enterprise Portal by using the Situation editor.
The monitoring agents that you use to monitor your system environment are
delivered with a set of predefined situations that you can use as-is or you can
create new situations to meet your requirements. Predefined situations contain
attributes that check for system conditions common to many enterprises.
Using predefined situations can improve the speed with which you can begin using
the IBM Tivoli Advanced Catalog Management. You can examine and, if necessary,
change the conditions or values being monitored by a predefined situation to those
best suited to your enterprise.
You can display predefined situations and create your own situations using the
Situation editor. The left frame of the Situation editor initially lists the situations
associated with the Navigator item that you selected. When you click a situation
name or create a new situation, the right frame opens with the following tabs:
Formula
Formula describing condition being tested
Distribution
List of managed systems (operating systems, subsystems, or applications)
to which the situation can be distributed. All of the IBM Tivoli Advanced
Catalog Management managed systems are assigned by default.
Expert advice
Comments and instructions to be read in the event workspace
Action
Command to be sent to the system
Util Options to close the event after a period of time, or when another situation
becomes true
More information about situations
IBM Tivoli Monitoring User’s Guide contains more information about predefined and
custom situations and how to use them to respond to alerts.
For a list of the predefined situations for this monitoring agent and a description of
each situation, refer to the Predefined situations section in this chapter and the
information in that section for each individual situation.
© Copyright IBM Corp. 2007 33
Predefined situations
This monitoring agent contains the following predefined situations, which are
organized by Navigator item:
v IBM Tivoli Advanced Catalog Management
– Not applicable
v Alias Space
– KRN_KRN_Alias_Remain_Critical
v Cache Performance
– KRN_KRN_Cat_Hit_Pct_Warning
v Catalog Dataset Attributes
– KRN_KRN_Cat_4GB_Limit_Critical
– KRN_KRN_Cat_Extents_Critical
v Catalog Summary
– Not applicable
v Catalog Volume Summary
– KRN_KRN_Vol_Pct_Full_Critical
– KRN_KRN_Vol_Frag_Idx_Critical
v Last Catalog Backup
– KRN_KRN_Cat_Backup_Critical
– KRN_KRN_Cat_Backup_Warning
The remaining sections of this chapter contain descriptions of each of these
situations. The situations are organized by Navigator item. The following information
is provided about each situation:
Description
Information about the conditions that the situation tests
Formula
Syntax that contains one or more logical expressions describing the
conditions for the situation to monitor
Run at startup
Whether the situation is automatically distributed to instances of the agent
or is available for manual distribution.
Sampling interval
Number of seconds that elapses between one sample of data that the
monitoring agent collects for the server and the next sample
Situation persistence
Whether the conditions specified in the situation evaluate to ″true″ for the
defined number of occurrences in a row before the situation is raised. The
default of 1 means no persistence checking takes place.
Severity
Severity of the event: Warning, Informational, or Critical
Clearing conditions
Controls when a true situation closes: after a period of time, when another
situation is true, or whichever occurs first if both are selected.
34 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
IBM Tivoli Advanced Catalog Management Navigator item
There are no predefined situations for this Navigator item.
Alias Space Navigator item
KRN_KRN_Alias_Remain_Critical situation
Description
The catalog connector record is running out of space.
Formula
*IF *VALUE KRN_ALIAS_SPACE.ALIASROOM *LT 50
See “Attribute groups and attributes for IBM Tivoli Advanced Catalog Management”
on page 17 for descriptions of the attributes in this formula.
Distribution type
This situation is automatically distributed to instances of this agent.
Sampling interval
1 minute
Situation persistence
The number of times the conditions of the situation must occur for the situation to
be true is 1.
Severity
Critical
Clearing conditions
The situation clears when the condition becomes false.
Cache Performance Navigator item
KRN_KRN_Cat_Hit_Pct_Warning situation
Description
The Low Hit% threshold has been reached
Formula
*IF *VALUE KRN_CACHE_PERFORMANCE.CCHPCTHIT *LT 20 *AND *VALUE KRN_CA
CHE_PERFORMANCE.CATTYPE *NE Master
See “Attribute groups and attributes for IBM Tivoli Advanced Catalog Management”
on page 17 for descriptions of the attributes in this formula.
Distribution type
This situation is automatically distributed to instances of this agent.
Sampling interval
1 minute
Chapter 6. Situations reference 35
Situation persistence
The number of times the conditions of the situation must occur for the situation to
be true is 1.
Severity
Warning
Clearing conditions
The situation clears when the condition becomes false.
Catalog Dataset Attributes Navigator item
KRN_KRN_Cat_4GB_Limit_Critical situation
Description
The catalog size is close the 4 gigabyte limit
Formula
*IF *VALUE KRN_CATALOG_DATASET_ATTRIBUTES.PCT4GBLIM *GT 90
See “Attribute groups and attributes for IBM Tivoli Advanced Catalog Management”
on page 17 for descriptions of the attributes in this formula.
Distribution type
This situation is automatically distributed to instances of this agent.
Sampling interval
1 minute
Situation persistence
The number of times the conditions of the situation must occur for the situation to
be true is 1.
Severity
Critical
Clearing conditions
The situation clears when the condition becomes false.
KRN_KRN_Cat_Extents_Critical situation
Description
The catalog is close to running out of extents
Formula
*IF *VALUE KRN_CATALOG_DATASET_ATTRIBUTES.EXTENTS *GT 100
See “Attribute groups and attributes for IBM Tivoli Advanced Catalog Management”
on page 17 for descriptions of the attributes in this formula.
Distribution type
This situation is automatically distributed to instances of this agent.
Sampling interval
1 minute
36 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Situation persistence
The number of times the conditions of the situation must occur for the situation to
be true is 1.
Severity
Critical
Clearing conditions
The situation clears when the condition becomes false.
Catalog Summary Navigator item
There are no predefined situations for this Navigator item.
Catalog Volume Summary Navigator item
KRN_KRN_Vol_Pct_Full_Critical situation
Description
A volume containing a catalog is getting full.
Formula
*IF *VALUE KRN_CATALOG_VOLUME_SUMMARY.PCTFULL *GT 95
See “Attribute groups and attributes for IBM Tivoli Advanced Catalog Management”
on page 17 for descriptions of the attributes in this formula.
Distribution type
This situation is automatically distributed to instances of this agent.
Sampling interval
1 minute
Situation persistence
The number of times the conditions of the situation must occur for the situation to
be true is 1.
Severity
Critical
Clearing conditions
The situation clears when the condition becomes false.
KRN_KRN_Vol_Frag_Idx_Critical situation
Description
The volume fragmentation index exceeds the critical threshold
Formula
*IF *VALUE KRN_CATALOG_VOLUME_SUMMARY.FRAGIDX *GE 850
See “Attribute groups and attributes for IBM Tivoli Advanced Catalog Management”
on page 17 for descriptions of the attributes in this formula.
Chapter 6. Situations reference 37
Distribution type
This situation is automatically distributed to instances of this agent.
Sampling interval
1 minute
Situation persistence
The number of times the conditions of the situation must occur for the situation to
be true is 1.
Severity
Critical
Clearing conditions
The situation clears when the condition becomes false.
Last Catalog Backup Navigator item
KRN_KRN_Cat_Backup_Critical situation
Description
The last backup job for a catalog had a return code >= 8
Formula
*IF *VALUE KRN_LAST_CATALOG_BACKUP.LBKPRC *GE 8
See “Attribute groups and attributes for IBM Tivoli Advanced Catalog Management”
on page 17 for descriptions of the attributes in this formula.
Distribution type
This situation is automatically distributed to instances of this agent.
Sampling interval
1 minute
Situation persistence
The number of times the conditions of the situation must occur for the situation to
be true is 1.
Severity
Critical
Clearing conditions
The situation clears when the condition becomes false.
KRN_KRN_Cat_Backup_Warning situation
Description
The last backup job for a catalog had a non-zero return code < 8
Formula
*IF ( ( *VALUE KRN_LAST_CATALOG_BACKUP.LBKPRC *GT 0 ) *AND ( *VALUE
KRN_LAST_CATALOG_BACKUP.LBKPRC *LT 8 ) )
See “Attribute groups and attributes for IBM Tivoli Advanced Catalog Management”
on page 17 for descriptions of the attributes in this formula.
38 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Distribution type
This situation is automatically distributed to instances of this agent.
Sampling interval
1 minute
Situation persistence
The number of times the conditions of the situation must occur for the situation to
be true is 1.
Severity
Warning
Clearing conditions
The situation clears when the condition becomes false.
Chapter 6. Situations reference 39
40 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Chapter 7. Take Action commands reference
This chapter contains an overview of Take Action commands, references for
detailed information about Take Action commands, and descriptions of the Take
Action commands included in this monitoring agent, if any.
About Take Action commands
Take Action commands can be run from the portal client or included in a situation or
a policy.
When included in a situation, the command runs when the situation becomes true.
A Take Action command in a situation is also referred to as reflex automation. When
you enable a Take Action command in a situation, you automate a response to
system conditions. For example, you can use a Take Action command to send a
command to restart a process on the managed system or to send a text message
to a cell phone.
Advanced automation uses policies to perform actions, schedule work, and
automate manual tasks. A policy comprises a series of automated steps called
activities that are connected to create a workflow. After an activity is completed,
Tivoli Enterprise Portal receives return code feedback, and advanced automation
logic responds with subsequent activities prescribed by the feedback.
A basic Take Action command displays the return code of the operation in a
message box that is displayed after the action completes. After you close this
window, no further information is available for this action.
More information about Take Action commands
For more information about working with Take Action commands, see the IBM Tivoli
Monitoring User’s Guide.
For a list of the Take Action commands for this monitoring agent and a description
of each command, refer to the Predefined Take Action commands section in this
chapter and the information in that section for each individual command.
Predefined Take Action commands
This monitoring agent contains the following Take Action commands:
v SampleAction
The remaining sections of this chapter contain descriptions of these Take Action
commands, which are listed alphabetically. The following information is provided
about each Take Action command:
Description
Which actions the command performs on the system to which is it sent
Arguments
List of parameters, if any, for the Take Action command with a short
description and the default value (if any) for each one
Return codes
Information that the Take Action command returns
© Copyright IBM Corp. 2007 41
SampleAction action
Description
DataPower Configuration
Arguments
v Name: value1
Description: Parameter 1
Default:
v Name: value2
Description: Parameter 2
Default:
v Name: value3
Description: Parameter 3
Default:
Return codes
Return Code: 0
Return Code Type: OK
Platforms: com.ibm.tivoli.monitoring.AgentGenerator.AgentXML.Tasks.CommandSpecification@64d864d8
Message ID: KNW9200I
Message: This is a sample message 2.
Return Code: 2
Return Code Type: GENERAL_ERROR
Platforms: com.ibm.tivoli.monitoring.AgentGenerator.AgentXML.Tasks.CommandSpecification@64d864d8
Message ID: KBC9202E
Message: WARNING::NO MESSAGE FOUND FOR THIS RETURN CODE!!!!!
Return Code: 6
Return Code Type: ALREADY_RUNNING
Platforms: com.ibm.tivoli.monitoring.AgentGenerator.AgentXML.Tasks.CommandSpecification@64d864d8
Message ID: KBC9201E
Message: WARNING::NO MESSAGE FOUND FOR THIS RETURN CODE!!!!!
Return Code: 8
Return Code Type: DOESNT_EXIST
Platforms: com.ibm.tivoli.monitoring.AgentGenerator.AgentXML.Tasks.CommandSpecification@64d864d8
Message ID: KBC9203E
Message: WARNING::NO MESSAGE FOUND FOR THIS RETURN CODE!!!!!
42 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Chapter 8. Policies reference
This chapter contains an overview of policies, references for detailed information
about policies, and descriptions of the predefined policies included in this monitoring
agent, if any.
About policies
Policies are an advanced automation technique for implementing more complex
workflow strategies than you can create through simple automation.
A policy is a set of automated system processes that can perform actions, schedule
work for users, or automate manual tasks. You use the Workflow Editor to design
policies. You control the order in which the policy executes a series of automated
steps, which are also called activities. Policies are connected to create a workflow.
After an activity is completed, Tivoli Enterprise Portal receives return code feedback
and advanced automation logic responds with subsequent activities prescribed by
the feedback.
More information about policies
This agent does not provide predefined policies. For more information about
working with policies, see the IBM Tivoli Monitoring User’s Guide.
For information about using the Workflow Editor, see the IBM Tivoli Monitoring
Administrator’s Guide or the Tivoli Enterprise Portal online help.
Predefined policies
The IBM Tivoli Advanced Catalog Management does not provide predefined
policies.
© Copyright IBM Corp. 2007 43
44 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Appendix A. IBM Tivoli Enterprise Console event mapping
Each event class corresponds to an attribute group in the IBM Tivoli Enterprise
Console. For a description of the event slots for each event class, see the lists in
this appendix. For more information about mapping attribute groups to event
classes, see the IBM Tivoli Monitoring Administrator’s Guide.
Generic event mapping provides useful event class and attribute information for
situations that do not have specific event mapping defined. BAROC files are found
on the Tivoli Enterprise Monitoring Server in the installation directory in TECLIB
(that is, install_dir/cms/TECLIB for Windows systems and install_dir/tables/TEMS_hostname/TECLIB for UNIX systems). IBM Tivoli Enterprise Console event
synchronization provides a collection of ready-to-use rule sets that you can deploy
with minimal configuration. Be sure to install IBM Tivoli Enterprise Console event
synchronization to access the correct Sentry.baroc, which is automatically included
during base configuration of IBM Tivoli Enterprise Console rules if you indicate that
you want to use an existing rulebase. See the IBM Tivoli Monitoring Installation and
Setup Guide for details.
Each of the event classes is a child of KRN_Base and is defined in the krn.baroc
file. The KRN_Base event class can be used for generic rules processing for any
event from the IBM Tivoli Advanced Catalog Management.
For events generated by situations on the ALIAS_SPACE attribute group, Tivoli
Enterprise Console events are sent using the ITM_KRN_ALIAS_SPACE class. This
class contains the following slots:
v node: STRING
v timestamp: STRING
v bcsname: STRING
v volser: STRING
v aliascount: INTEGER
v aliasavlen: INTEGER
v aliasroom: INTEGER
v aliastlen: INTEGER
For events generated by situations on the CACHE_PERFORMANCE attribute
group, Tivoli Enterprise Console events are sent using the
ITM_KRN_CACHE_PERFORMANCE class. This class contains the following slots:
v node: STRING
v timestamp: STRING
v bcsname: STRING
v volser: STRING
v cchrecords: INTEGER
v cchsearch: INTEGER
v cchfound: INTEGER
v cchdelete: INTEGER
v cchupdate: INTEGER
v cchpurge: INTEGER
v cchpcthit: INTEGER
v cattype: INTEGER
© Copyright IBM Corp. 2007 45
v cattype_enum: STRING
v cachetype: INTEGER
v cachetype_enum: STRING
For events generated by situations on the CATALOG_DATASET_ATTRIBUTES
attribute group, Tivoli Enterprise Console events are sent using the
ITM_KRN_CATALOG_DATASET_ATTRIBUTES class. This class contains the
following slots:
v node: STRING
v timestamp: STRING
v bcsname: STRING
v volser: STRING
v extents: INTEGER
v xhurba: INTEGER
v xharba: INTEGER
v cica: INTEGER
v cisize: INTEGER
v pctusedca: INTEGER
v numusedca: INTEGER
v alloccas: INTEGER
v alloccas_enum: STRING
v sms: INTEGER
v sms_enum: STRING
v cachetype: INTEGER
v cachetype_enum: STRING
v catshared: INTEGER
v catshared_enum: STRING
v ecs: INTEGER
v ecs_enum: STRING
v catlocked: INTEGER
v catlocked_enum: STRING
v alloctype: INTEGER
v alloctype_enum: STRING
v prialloc: INTEGER
v secalloc: INTEGER
v pct4gblim: INTEGER
For events generated by situations on the CATALOG_SUMMARY attribute group,
Tivoli Enterprise Console events are sent using the
ITM_KRN_CATALOG_SUMMARY class. This class contains the following slots:
v node: STRING
v timestamp: STRING
v bcsname: STRING
v volser: STRING
v extents: INTEGER
v aliasroom: INTEGER
v strings: INTEGER
46 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
v cattype: INTEGER
v cattype_enum: STRING
v lbkpstmpl: STRING
v lbkprc: INTEGER
For events generated by situations on the CATALOG_VOLUME_SUMMARY
attribute group, Tivoli Enterprise Console events are sent using the
ITM_KRN_CATALOG_VOLUME_SUMMARY class. This class contains the following
slots:
v node: STRING
v timestamp: STRING
v volser: STRING
v freespc: INTEGER
v allocspc: INTEGER
v devcap: INTEGER
v hifreeext: INTEGER
v fragidx: INTEGER
v pctfull: INTEGER
For events generated by situations on the LAST_CATALOG_BACKUP attribute
group, Tivoli Enterprise Console events are sent using the
ITM_KRN_LAST_CATALOG_BACKUP class. This class contains the following slots:
v node: STRING
v timestamp: STRING
v bcsname: STRING
v lbkpname: STRING
v lbkpvolser: STRING
v lstrtstmpl: STRING
v lendstmpl: STRING
v lstrtstmpu: STRING
v lendstmpu: STRING
v lbkprc: INTEGER
v ldiagrc: INTEGER
v lexamrc: INTEGER
v lvfyrc: INTEGER
For events generated by situations on the PERFORMANCE_OBJECT_STATUS
attribute group, Tivoli Enterprise Console events are sent using the
ITM_KRN_PERFORMANCE_OBJECT_STATUS class. This class contains the
following slots:
v node: STRING
v timestamp: STRING
v query_name: STRING
v object_name: STRING
v object_type: INTEGER
v object_type_enum: STRING
v object_status: INTEGER
v object_status_enum: STRING
Appendix A. IBM Tivoli Enterprise Console event mapping 47
v error_code: INTEGER
v error_code_enum: STRING
48 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Appendix B. Problem determination
This appendix provides agent-specific problem determination information. See the
IBM Tivoli Monitoring Problem Determination Guide for general problem
determination information. Also see “Support information” on page 74 for other
problem-solving options.
Note: You can resolve some problems by ensuring that your system matches the
system requirements listed in Chapter 2, “Requirements for the monitoring
agent,” on page 3.
Gathering product information for IBM Software Support
If you have a problem that you are unable to solve by referring to this guide and to
IBM Tivoli Monitoring Problem Determination Guide, gather the following information
about the problem and contact IBM Software Support for further assistance. The
IBM Support Assistant can help you gather and submit the required information
about the problem. See “Support information” on page 74.
v Monitored application file.
v Appropriate RAS1 trace output.
v Description of the operation scenario that led to the problem.
v Incorrect output, such as Tivoli Enterprise Portal screen prints or a description of
what you observed, if applicable.
v Log files from failing systems. You can collect all logs or logs of a certain type,
such as RAS trace logs or message logs.
v Application information, such as version number and patch level.
v Operating system version number and patch level.
v Messages and other information displayed on the screen.
v Version number of the following components of the monitoring environment:
– Tivoli Enterprise Portal client. Select About Tivoli Enterprise Portal ... from
the Help menu.
– Tivoli Enterprise Portal Server and Tivoli Enterprise Monitoring Server on
distributed systems. Also provide the IBM Tivoli Monitoring patch level, if
available.
- On Windows systems, you can find the version number and patch level in
the Version column of Manage Tivoli Monitoring Services.
- On Linux and UNIX systems, you can find the version number and patch
level in the .ver file for individual product components in the
Install_dir/registry subdirectory.
– Tivoli Enterprise Monitoring Server on z/OS®. You can find the version number
and patch level in the KDSENV member of the RKANPARU data set.
– Monitoring agent. You can find the version number and patch level by using
SMP/E.
For more information about collecting problem information, see IBM Tivoli
Monitoring Problem Determination Guide for distributed components and “Setting up
a trace on a z/OS system” on page 55 for z/OS components.
© Copyright IBM Corp. 2007 49
Built-in problem determination features
When you encounter a problem with any component, the primary troubleshooting
feature is logging. Logging refers to the writing of text messages and trace data
generated by the software to an output destination, such as a console screen or a
file. A monitoring agent does not display most messages at the Tivoli Enterprise
Portal. Instead, the messages are sent to more typical z/OS output locations, such
as sysout data sets or spool files or, more rarely, to the z/OS system console.
Tracing creates a record of the processing of a computer program or transaction.
Trace logs capture information about the operating environment to help you
diagnose problems when components fail to operate as intended. The principal
trace log type is the reliability, availability, and serviceability (RAS1) trace log. You
can set up RAS tracing for the monitoring agents, Tivoli Enterprise Monitoring
Server, and Tivoli Enterprise Portal Server. The default level of tracing depends on
the component and operating system. For the monitoring agents on z/OS, the
default level is KBB_RAS1=ERROR, which means that only error messages are
captured. This is the setting for minimal tracing.
Tip
Two useful tools can help you collect, view, analyze, and correlate log and
trace information:
v IBM Support Assistant. See “Using IBM Support Assistant” on page 74.
v Log and Trace Analyzer tool. See “Using the Log and Trace Analyzer tool”
on page 67.
Determining whether the problem is caused by the monitoring agent
One of the most difficult troubleshooting issues in a client-server environment such
as Tivoli Monitoring Services is determining which component is the origin of the
problem. In most cases, the problem might seem to be a Tivoli Enterprise Portal
client problem because this is what you can see. But this can be misleading,
because the client can display data only if it receives data from the Tivoli Enterprise
Monitoring Server.
In any problem scenario, try to gather documentation at the time of the error. What
appears to be a client problem might well be a server problem, especially if data is
not showing up at the client.
As you collect logs, create an exact description of the problem. For reproducible
problems, document the exact navigation path that produced the error. Screen
prints might also help with problem determination. For locations of log files for all
the components of Tivoli Monitoring Services and for information about enabling
tracing for distributed components, refer to IBM Tivoli Monitoring Problem
Determination Guide.
The sections that follow discuss types of problems that you might see and methods
of capturing the information needed to diagnose those problems.
Reproducible problems reported as Tivoli Enterprise Portal client
problems
If the problem is reproducible and is reported as a Tivoli Enterprise Portal client
problem, you need the client log. The location of the log depends on the type of
50 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
client and the operating system the client is running on. You might be asked to set
a trace in the client and then collect the log.
Log files are created automatically when you start the Tivoli Enterprise Portal. You
can view the logs with any text editor. Logon prompts, progress messages, and
error messages are also displayed in the status bar of the Tivoli Enterprise Portal
logon window. You can change the level of tracing by either of two methods:
v In the Tivoli Enterprise Portal, select File > Trace Options.... See the Tivoli
Enterprise Portal online help for instructions.
v In Manage Tivoli Monitoring Services, right-click Tivoli Enterprise Portal and
select Advanced > Edit Trace Parms....
If the Tivoli Enterprise Portal desktop client is being used, collect the logs shown in
Table 8.
Table 8. Log locations for Tivoli Enterprise Portal desktop client
Component Windows system Linux system
Tivoli
Enterprise
Portal
desktop client
install_dir\CNP\logs
where install_dir is the directory where the
Tivoli Monitoring Services components are
installed (usually, C:\IBM\ITM).
You can find three types of log files in the portal
client log location:
v kcjerror.log contains environment variables
and command strings for starting the Tivoli
Enterprise Portal.
Tivoli Enterprise Portal keeps the last five
error logs (kcjerror_1.log, kcjerror_2.log, and
so on) in addition to the current one. Every
time the Tivoli Enterprise Portal starts, it
purges the oldest error log and renames the
rest.
v kcjras1.log contains the RAS1 tracing for the
portal client.
v KCJ.LOG contains any errors in the Java
libraries used by the portal client.
Every time the Tivoli Enterprise Portal starts, it
purges the kcjras1.log and KCJ.LOG files and
writes new ones. If you want to preserve
these log files, you must rename them or
copy them to another directory before
restarting the Tivoli Enterprise Portal.
install_dir/logs/hostname_cj_timestamp.log
where:
install_dir
Is the directory where the Tivoli Monitoring
Services components are installed.
hostname
Is the host name of the system.
cj Is the component code for the portal
client.
timestamp
Is a decimal representation of the time
when the process started.
If the Tivoli Enterprise Portal browser client is being used, collect the following trace
log:
C:\Documents and Settings\Administrator\Application Data\IBM\Java\Deployment\log\plugin1.4.2.trace
The plugin1.4.2.trace file contains the RAS1 tracing for the Tivoli Enterprise Portal
browser client and any Java exceptions. You might need to edit your Internet
Explorer browser options to enable tracing on your local system. When tracing is
enabled, you can change the level of tracing by selecting File > Trace Options... in
the Tivoli Enterprise Portal.
Appendix B. Problem determination 51
The Tivoli Enterprise Portal Server log is found in the locations shown in Table 9.
Table 9. Log locations for Tivoli Enterprise Portal Server
Component Windows system Linux or AIX® system
Tivoli
Enterprise
Portal Server
install_dir\logs\hostname_cq_hex_timestamp-nn.log
where:
install_dir
Is the directory where the Tivoli
Monitoring Services components are
installed.
hostname
Is the host name of the system.
cq Is the component code for the portal
server.
hex_timestamp
Is a hexadecimal representation of
the time when the process started.
nn Represents the circular sequence in
which logs are rotated. Ranges from
01 to 05, by default, though the first
is always retained, since it includes
configuration parameters.
install_dir/logs/hostname_cq_timestamp.log
where:
install_dir
Is the directory where the Tivoli Monitoring
Services components are installed.
hostname
Is the host name of the system.
cq Is the component code for the portal server.
timestamp
Is a decimal representation of the time when
the process started.
The log files are created automatically when you start the portal server. You can
view the logs with any text editor.
When you investigate portal server problems on Windows systems, use the
Windows Event Viewer to check that the portal server started correctly and to look
for errors. You can also use the service console, accessible from the portal server
with an Internet Explorer browser, to read logs and turn on traces for remote
product diagnostics and configuration information. See IBM Tivoli Monitoring
Problem Determination Guide for instructions on using the service console.
You can change trace settings in Manage Tivoli Monitoring Services. Right-click
Tivoli Enterprise Portal Server and select Advanced > Edit Trace Parms....
In addition, you can set the portal server to display messages in a command
prompt window on a Windows system.
1. Right-click Tivoli Enterprise Portal Server in the Manage Tivoli Monitoring
Services window.
2. Select Change startup.
3. Select Allow service to interact with desktop.
Collect the Tivoli Enterprise Monitoring Server logs, too. Even when a problem
appears to be a Tivoli Enterprise Portal problem, the real problem might be a
monitoring server failure.
v Table 11 on page 54 shows the location of logs for a Tivoli Enterprise Monitoring
Server on a z/OS system.
v Table 10 on page 53 shows the location of logs for a Tivoli Enterprise Monitoring
Server on distributed systems.
52 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Table 10. Log locations for Tivoli Enterprise Monitoring Server on distributed systems
Component Windows system Linux or UNIX system
Tivoli
Enterprise
Monitoring
Server
install_dir\logs\hostname_cms_hex_timestamp-nn.log
where:
install_dir
Is the directory where the Tivoli
Monitoring Services components are
installed.
hostname
Is the host name of the system.
cms Is the component code for the
monitoring server.
hex_timestamp
Is a hexadecimal representation of
the time when the process started.
nn Represents the circular sequence in
which logs are rotated. Ranges from
01 to 05, by default, though the first
is always retained, since it includes
configuration parameters.
install_dir/logs/hostname_ms_timestamp.log
where:
install_dir
Is the directory where the Tivoli Monitoring
Services components are installed.
hostname
Is the host name of the system.
ms Is the component code for the monitoring
server.
timestamp
Is a decimal representation of the time when
the process started.
The log files are created automatically when you start the monitoring server on a
Windows, Linux, or UNIX system. You can view the log files with any text editor.
When you investigate monitoring server problems on Windows systems, use the
Windows Event Viewer to check that the monitoring server started correctly and to
look for errors. You can also use the service console, accessible from the portal
server with an Internet Explorer browser, to read logs and turn on traces for remote
product diagnostics and configuration information. See IBM Tivoli Monitoring
Problem Determination Guide for instructions on using the service console.
You can change trace settings in Manage Tivoli Monitoring Services. Select Action
> Advanced > Edit Trace Parms....
In addition, you can set the monitoring server to display messages in a command
prompt window on a Windows system.
1. Right-click Tivoli Enterprise Monitoring Server in the Manage Tivoli
Monitoring Services window.
2. Select Change startup.
3. Select Allow service to interact with desktop.
Irreproducible problems reported as Tivoli Enterprise Portal client
problems
If a problem reported as a Tivoli Enterprise Portal client problem is not reproducible,
collect the portal client and portal server logs. The logs might be the only indication
of the real problem. Always try to get the logs at the time of the error.
Appendix B. Problem determination 53
Problems reported as Tivoli Enterprise Portal Server problems
If the problem is reported as a Tivoli Enterprise Portal Server problem, collect the
portal server logs. If the problem is reproducible, you might be asked to set unit
traces for the portal server and gather the logs. The location for the portal server
logs is found in Table 9 on page 52. Also collect the portal client log at the time of
the error, if it is available.
Problems affecting the monitoring agent
After you have ruled out problems with Tivoli Monitoring Services components, treat
the problem as a monitoring agent problem. A data collection problem with a
monitoring agent manifests itself as the display of no data or incorrect data in the
Tivoli Enterprise Portal.
Log files and trace information are provided in a common fashion across all
monitoring agents on z/OS and the z/OS components of the Tivoli Monitoring
Services. Two useful tools can help you collect, view, analyze, and correlate the log
and trace information:
v IBM Support Assistant. See “Support information” on page 74.
v Log and Trace Analyzer tool. See “Using the Log and Trace Analyzer tool” on
page 67.
Table 11 explains the location of log and trace files for the monitoring agent and the
Tivoli Monitoring Services z/OS components.
Table 11. Locations of log and trace information for z/OS components
Component Locations of log and trace information
Monitoring agent RKLVLOG for the monitoring agent started task is the single most helpful
piece of service information for a monitoring agent on z/OS. The RKLVLOG is
the sysout data set or spool file that contains log and trace messages.
Instructions on how to save the contents of this log to a dataset are provided
under “Capturing z/OS logs to send to IBM Software Support” on page 62.
These additional log files (if available) are also useful:
v The RKLVSNAP sysout data set or spool file contains formatted dump
output.
v The RKPDLOG sysout data set or spool file contains information and error
messages related to the handling of persistent data stores.
Refer to your started procedures for the locations of these serviceability log
files.
Tivoli Enterprise Monitoring Server
on z/OS
Because the Tivoli Enterprise Monitoring Server on z/OS runs under
ITMS:Engine just as a monitoring agent on z/OS does, all logging under
ITMS:Engine is handled the same way: log and trace data is written to
RKLVLOGs and RKPDLOGs.
54 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Table 11. Locations of log and trace information for z/OS components (continued)
Component Locations of log and trace information
ITMS:Engine
ITMS:Engine is a collection of basic operating system and communication
service routines built specifically for z/OS. All address spaces used by
monitoring agents load and use the services of ITMS:Engine.
The following message indicates successful initialization of ITMS:Engine:
KLVIN408 IBM OMEGAMON PLATFORM ENGINE VERSION 400 READY
For troubleshooting information about ITMS:Engine problems, refer to the
z/OS initialization section of IBM Tivoli Monitoring Problem Determination
Guide.
ITMS:Engine writes messages to the same RKLVLOG as the product it is
running. For the IBM Tivoli Advanced Catalog Management monitoring agent,
product-specific messages begin with the product code KRN. Messages for
the ITMS:Engine begin with the product code KLV. Tivoli Enterprise Monitoring
Server messages begin with the product code KDS.
Persistent data store The RKPDLOG sysout data set or spool file contains the information and error
messages related to the handling of persistent data stores. To dump this log,
follow the procedures described for RKLVLOG in the sections that follow.
See “Setting up a trace on a z/OS system” for detailed instructions on using traces
and logs to debug the monitoring agent and the monitoring server on z/OS systems.
Debugging the persistent data store, Tivoli Data Warehouse, and
warehouse proxy
To view the Application Event Log for Tivoli Data Warehouse and the warehouse
proxy on a Windows system, start the Event Viewer by selecting Start > Programs
> Administrative Tools> Event Viewer. Select Application from the Log
pull-down menu. Every successful export of historical data is logged in Tivoli Data
Warehouse in a table called WAREHOUSELOG.
In the warehouse proxy, you can turn on error tracing to capture additional error
messages that can be helpful in detecting problems. Refer to IBM Tivoli Monitoring
Problem Determination Guide for more information.
Information about maintaining the persistent datastore can be found in Configuring
IBM Tivoli Enterprise Monitoring Server on z/OS and IBM Tivoli Monitoring
Administrator’s Guide.
Setting up a trace on a z/OS system
Trace logs capture information about the operating environment to help you
diagnose problems when components fail to operate as intended. The principal log
type is the reliability, availability, and serviceability (RAS1) trace log. When the
monitoring agents and Tivoli Monitoring Services components are initialized, RAS1
is one of the first processes started. RAS logs are in the English language only. You
can set up RAS tracing for the monitoring agents, Tivoli Enterprise Monitoring
Server, and Tivoli Enterprise Portal Server.
The default level of tracing depends on the component and operating system. For
the monitoring agents on z/OS, the default level is KBB_RAS1=ERROR, which means
Appendix B. Problem determination 55
that only error messages are captured. This is the setting for minimal tracing. When
you report a problem, IBM Software Support might ask you to enable a more
in-depth and detailed form of tracing, such as one of those discussed under “Syntax
for RAS1 traces” on page 57.
IBM Software Support uses the information captured by trace logging to trace a
problem to its source or to determine why an error occurred. The default
configuration for trace logging, such as the level of trace logging, depends on the
source of the trace logging. Trace logging is always enabled.
Tip
Overhead (CPU and I/O) associated with detailed RAS1 tracing might degrade
performance of the monitoring agent. Restore RAS1 tracing for the monitoring
agent to the default level KBB_RAS1=ERROR after you complete problem
diagnosis.
You can also use communications traces during TCP/IP initialization to help
diagnose problems in connections between the monitoring agent and the monitoring
server. See “Setting up communications tracing.”
This section provides instructions for setting up traces on z/OS components for your
own use and to forward to IBM Software Support.
Setting up communications tracing
Communications tracing during TCP/IP initialization is controlled by the
KDC_DEBUG environment variable. To obtain the level of tracing required for the
TCP/IP initialization messages to be recorded in the RAS1 log, add the string
KDC_DEBUG=Y to member KRNENV of RKANPARU for the IBM Tivoli Advanced
Catalog Management monitoring agent or to member KDSENV of RKANPARU for
the Tivoli Enterprise Monitoring Server.
Possible values for KDC_DEBUG are:
Y The data flow between the monitoring agent and monitoring server during
TCP/IP initialization is recorded, including data packages sent and received.
When KDC_DEBUG=Y is active in the environment during initialization of
TCP/IP services for this address space, you can confirm successful
initialization of TCP/IP by looking for one of the following messages in
RKLVLOG:
"KDE1I_OpenTransportProvider") Transport opened: socket/ip.tcp
"KDE1I_OpenTransportProvider") Transport opened: socket/ip.pipe
"KDE1I_OpenTransportProvider") Transport opened: socket/ip.udp
N The data flow between the monitoring agent and monitoring server during
TCP/IP initialization is not recorded. This is the default and the
recommended setting for normal operation.
Refer to the environment variables appendix in IBM Tivoli Monitoring Problem
Determination Guide for a list of environment variables associated with other
components.
Setting up RAS1 tracing
RAS1 tracing is the primary diagnostic tool for product components. It is provided
by the KBB library service and is set either in the IBM Tivoli Monitoring Service
56 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Console interface or by a more direct method of modifying the KBB_RAS1
parameter. RAS1 messages are sent to STDOUT and redirected to the files shown
in Table 11 on page 54.
RAS1 trace log files can grow very large with the wrong amount of filtering. Be
careful with the levels of tracing that you specify.
Syntax for RAS1 traces
This syntax is used to specify a RAS1 trace in the KppENV file of RKANPARU
(where pp is the product code: RN for the IBM Tivoli Advanced Catalog
Management or DS for the Tivoli Enterprise Monitoring Server). After you add this
command to the KppENV file, you must stop and restart the address space for the
command to take effect. After that, it remains in effect for the life of the address
space. To end the trace, you must edit the KppENV file again to reset the trace
level, and stop and restart the address space.
An IBM Software Support representative can tell you the values to set for the RAS1
trace parameters.
The basic syntax of the RAS1 trace command is:
�� KBB_RAS1= global_class
(COMP:
component_type)
(ENTRY:
entry_point) �
� (UNIT:
unit_name, class) ��
where:
global_class
Indicates the level of tracing that you want. This is a global setting that
applies to all RAS1 filters in the process. If you set this global class by
itself, it is global in scope and the trace cannot filter on any of the other
keywords. Separate combined classes with a space. The following values
are possible. Valid abbreviations are in parentheses.
v ERROR (ER): returns severe error messages only (this is the default for
most applications).
v STATE (ST): records the condition or current setting of flags and
variables in the process. If state tracing is enabled, you can see the
current state of particular variables or flags as the process is running.
v FLOW (FL): causes a message to be generated at an entry or exit point
of a function.
v DETAIL (DE): produces a detailed level of tracing.
v INPUT (IN): records data created by a particular API, function, or
process.
v ALL: causes all available messages to be recorded. This setting
combines all the other forms of tracing.
COMP Indicates that the trace includes a component type. The COMP keyword is
used to trace groups of routines related by function (or component). Use
this keyword only at the explicit request of an IBM Software Support
representative.
component_type
Identifies a component type. An IBM Software Support representative can
tell you what value to specify.
Appendix B. Problem determination 57
ENTRY
Narrows a filtering routine to specify a specific ENTRY POINT. Since
multiple entry points for a single routine are rare, use this keyword only at
the explicit request of an IBM Software Support representative.
entry_point
Represents the name of the entry point. An IBM Software Support
representative can tell you what value to specify.
UNIT Indicates that the trace is to look for a match between the compilation unit
dispatched and the fully or partially qualified compilation unit specified on
the RAS1 statement. A match results in a trace entry.
unit_name
Represents the name of the compilation unit. In most instances, this name
defines the component that is being traced. The value is likely to be the
three-character product code for the monitoring agent (KRN for IBM Tivoli
Advanced Catalog Management).
class One of the same values specified for global_class but, because of its
position inside the parentheses, narrowed in scope to apply only to the
unit_name specified.
Note: The default setting for monitoring agents on z/OS is KBB_RAS1=ERROR,
meaning that only error tracing is enabled. You can specify any combination
of UNIT, COMP, and ENTRY keywords. No keyword is required. However,
the RAS1 value you set with the global class applies to all components.
Example: Tracing monitoring agent requests to and answers from the
monitoring server: To show monitoring agent requests to and answers from the
Tivoli Enterprise Monitoring Server, specify this trace:
KBB_RAS1=ERROR (UNIT:KRA ST ERR)
The unit values ST and ERR indicate collection of state and error information for a
monitoring agent infrastructure component (KRA).
Note: Use this type of trace only for debugging a specific problem, because the
settings greatly increase the number of messages generated by the
monitoring agent. With this type of trace, messages include a detailed dump
of all rows of data that pass filtering: attribute names and values, request
names, table names, and collection intervals. Be sure to disable this
resource-intensive form of tracing immediately after you complete the trace.
Setting RAS1 trace levels by editing RKANPARU
One of the simplest ways to set trace levels for a monitoring agent on z/OS is to
edit the RKANPARU (KppENV) member, where pp is the product code (RN for IBM
Tivoli Advanced Catalog Management). The text in bold shown in the following
screen capture is an example of what an IBM service representative might ask you
to add to this member.
58 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
EDIT RKANPARU(KRNENV)
Command ===>
****** ***************************** Top of Data ******************************
000001 KDE_TRANSPORT=\
000002 SNA.PIPE PORT:135 USE:N\
000003 IP6.PIPE PORT:1918 USE:N\
000004 IP6.UDP PORT:1918 USE:N\
000005 IP.SPIPE PORT:3660 USE:N\
000006 IP6.SPIPE PORT:3660 USE:N\
000007 IP.PIPE PORT:1918\
000008 IP.UDP PORT:1918
000009 KBB_RAS1=ERROR (UNIT:KQZ ALL)
000010 CT_CMSLIST=\
000011 IP.PIPE:n.nn.nnn.nn;\
000012 IP.UDP:n.nn.nnn.nn;
000013 CTIRA_STANDALONE=N
000014 KRN_CPS_PORT=2092
000015 KRN_CPS_PORT=2093
000016 KQZ_DP_CACHE_TTL=30
000017 KQZ_DP_ACTION_TIMEOUT=60
000018 KQZ_PURE_EVENT_CACHE_SIZE=1000
000019 KQZ_COLLECTION_TIMEOUT=60
000020 CTIRA_IP_PORT=0
000021 LANG=en_US.ibm-037
****** **************************** Bottom of Data ****************************
Setting RAS1 trace levels dynamically from the IBM Tivoli
Monitoring Service Console
You can also use the IBM Tivoli Monitoring Service Console to set trace levels for
monitoring agents on z/OS, as well as for a Tivoli Enterprise Monitoring Server on
z/OS or for distributed components. Using the service console, you can read logs
and turn on traces for remote product diagnostics and configuration.
The service console is uniquely identified by its service point name. All service
consoles for a host are linked and presented on the IBM Tivoli Monitoring Service
Index for that host. You can perform operations on a specific component process by
selecting the service console associated with the service point name of the
component.
Starting the service console: Use the following procedure to start the service
console.
1. Start Internet Explorer (version 5 or higher).
2. In the Address field, type the URL for the Tivoli Enterprise Portal browser client:
http://hostname:1920
where hostname specifies the system where the Tivoli Enterprise Portal Server
is installed. If the service console is not displayed, a system administrator might
have blocked access to it. Refer to the IBM Tivoli Monitoring Problem
Determination Guide for information about blocking access to the service
console.
3. On the IBM Tivoli Monitoring Service Console window, select the desired
component process (service point name).
4. Click OK.
In secure environments, you need a valid user ID and password to proceed.
You can issue service console commands in the command input area. For a list of
available commands, type a question mark (?) and click Submit.
Appendix B. Problem determination 59
Service console commands: The service console supports the following
commands, most of them useful for problem determination:
bss1 Manages BSS1 (Basic System Services). This command is paired with one
of the following sub-commands:
v listenv: Display the resident ITMS:Engine variables
v getenv: Display environment variables
v setenv: Assign an environment variable
v info: Display BSS1_Info() data
v config: Manage configuration variables
config Modifies the settings of the ITMS: Engine debug environment variables:
RES1_DEBUG, KDH_DEBUG, KDC_DEBUG, and KDE_DEBUG . For
example, the following config command alters the setting of KDC_DEBUG:
CONFIG KDC_DEBUG=Y
http Displays HTTP server management.
kdcstat
Displays the status of the KDC remote procedure call (RPC) service
component.
ras1 Manages RAS1 (Reliability, Availability, and Serviceability). This command is
paired with one of the following sub-commands:
v log: Display RAS1 log capture buffer
v list: List the RAS1 filters
v ctbld: Display the resident CTBLD data
v units: Display the registered compilation units
v set: Display the RAS1 filters
You can use the RAS1 command without operands to view the current
ITMS:Engine log capture buffer. When you supply operands with the RAS1
command, the operands are assumed to be keywords applicable to the
KBB_RAS1 environment variable.
The RAS1 command is especially useful for dynamically enabling and
disabling RAS1 traces. Often the documentation requests of IBM Software
Support conflict with your availability requirements. The RAS1 command
can be used to alter KBB_RAS1 tracing parameters dynamically without the
need to recycle the product. For example, to enable the standard IRA
traces, you can issue the following service console command:
RAS1 set error (unit:kpx all) (unit:kra all)
After you capture this trace, you can disable it with the following service
console command:
RAS1 set error (unit:kpx error) (unit:kra error)
This command restores the RAS1 logging level from ALL to ERROR for
units KPX and KRA.
res1 Displays the status of RES1 Logical Resource Manager
Using the Configuration Tool to set trace levels
When you use the Configuration Tool to configure a Tivoli Enterprise Monitoring
Server or a monitoring agent on z/OS, you can specify the level of trace information
collected. For the monitoring server, you specify trace levels on the Specify
Advanced Configuration Values panel. For the monitoring agent, you specify
trace levels on the Specify Advanced Agent Configuration Values panel. For
60 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
information about these panels, see the IBM Tivoli Advanced Catalog Management
Monitoring Agent Planning and Configuration Guide and the Configuring IBM Tivoli
Enterprise Monitoring Server on z/OS.
Setting trace levels for the monitoring server in the Configuration Tool: The
Specify Advanced Configuration Values panel for the monitoring server provides
several parameters for setting up logging and tracing.
Enable startup console messages
Set this parameter to Y if you want a SYSLOG message on the console to
indicate when the monitoring server finishes initializing. The default is Y.
Enable communications trace
Set this parameter to Y if you want KDC_DEBUG=Y as the override setting
in the KDSENV member of RKANPARU. Otherwise, the default setting of
KDC_DEBUG=N is used. This default parameter instructs the data
communications layer to report communications problems using a minimal,
summary format. This parameter is intended for stable applications in
production. Note that the default KDC_DEBUG=N generates standard
RAS1 trace data in the monitoring server RKLVLOG, in addition to the
summary information diagnosing possible timeout conditions
The following settings report on data communications problems:
v KDC_DEBUG=N: minimal tracing (default)
v KDC_DEBUG=Y: full-packet tracing
v KDC_DEBUG=D: KDC_DEBUG=Y plus STATE & FLOW tracing
v KDC_DEBUG=M: KDC_DEBUG=D plus INPUT & OUTPUT HELP tracing
v KDC_DEBUG=A: KDC_DEBUG=M plus all format tracing
Do not set KDC_DEBUG=A unless directed by an IBM Software Support
representative.
Enable storage detail logging
Set this parameter to Y to enable storage allocation detail logging. You can
use the storage detail command output to analyze storage use in the
monitoring server address space. Specifying Y generates the second
EVERY command in the KDSSTART member of RKANCMDU.
To disable storage detail logging, set this parameter to N, which generates
the second EVERY command as a comment. To control storage detail
logging further, you can also dynamically issue the following modify
command to the CANSDSST started task:
==> /F CANSDSST,STORAGE D
This modify command is useful if the monitoring server is already running
with storage detail logging disabled. Issuing the modify command activates
storage detail logging without recycling the monitoring server. The default is
Y.
If you set this parameter to Y, you must also define the times for storage
detail logging and flushing the VSAM buffers.
v For Storage detail logging, set the interval to monitor storage. The
interval values are written as part of the second EVERY command in the
KDSSTART member of RKANCMDU. The default is 0 hours (hh) and 60
minutes (mm).
Appendix B. Problem determination 61
v For Flush VSAM buffers, set the interval to force all deferred VSAM
writes to DASD. The interval values are written as part of the command
in the KDSSTART member of RKANCMDU. The default is 0 hours (hh)
and 30 minutes (mm).
Setting trace levels for a monitoring agent in the Configuration Tool: The
Specify Advanced Agent Configuration Values panel provides several
parameters for setting up logging and tracing.
Enable startup console messages
Set this parameter to Y if you want a SYSLOG message on the console to
indicate when the monitoring agent finishes initializing.
Enable WTO messages
Set this parameter to Y if you want write-to-operator (WTO) messages
logged.
Flush VSAM buffers interval
Set the interval (hh:mm) to force all deferred VSAM writes to DASD. The
interval values are written as part of the command the KRNAGST or
KDSSTART members of RKANCMDU. KRNAGST is used for monitoring
agents running in their own address space and KDSSTART is used when
the monitoring agent runs in a Tivoli Enterprise Monitoring Server address
space.
Capturing z/OS logs to send to IBM Software Support
You can view the RKLVLOG for a monitoring agent or monitoring server on z/OS
online, or you can save the log to a file. To save a log to a file rather than viewing
the log online, you need to know how to perform the following tasks:
v “Saving the contents of an RKLVLOG”
v “Ending one RKLVLOG and starting another” on page 63
v “Submitting problems” on page 77
Saving the contents of an RKLVLOG
To save the information in your z/OS logs (such as RKLVLOG), use the System
Display and Search Facility (SDSF). Follow these instructions to use SDSF to
capture (in this example) the RKLVLOG associated with any running task in your
monitoring agent.
1. From ISPF, select the SDSF option.
2. Enter the following on the command line:
st taskname
where taskname is the name of the procedure whose log you are trying to
display and capture. For example, entering st canshl on the command line
results in display of theIBM Tivoli Advanced Catalog Management monitoring
agent job.
3. From the SDSF screen, enter ? next to the name of the started task to display a
list of the output files. For example, the output files for the IBM Tivoli Advanced
Catalog Management monitoring agent task look like this:
JESMSGLG JES2
JESJCL JES2
JESYSMSG JES2
RKLVLOG ITMAGENT
RKLVSNAP ITMAGENT
RKPDLOG ITMAGENT
62 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
4. To print the RKLVLOG for this job to a data set, type s next to the RKLVLOG
output file. Then, on the command line of SDSF, type:
print d
Press Enter. The d means that you want the file printed to a data set.
The SDSF Print to Data Set panel is displayed.
5. On this panel, type the data set name and characteristics for the file you want to
print, and press Enter.
6. You are returned to the RKLVLOG output file. On the command line, specify the
number of lines you want to print by entering a range large enough to include
the entire file, such as:
print 1 99999999
Then press Enter. A message in the upper right corner of the panel tells you
how many lines are printed.
7. Type print close on the SDSF command line to close the file. The log is now
saved in the data set that was specified in Step 5.
For more information about SDSF commands, see z/OS SDSF Operation and
Customization (SA22-7670).
Ending one RKLVLOG and starting another
When you want to recreate a problem to send it to IBM Software Support, you can
use a z/OS MODIFY command to close the current RKLVLOG spool data set and
open a new one. This command is issued from a z/OS console or from the Tivoli
Enterprise Portal (by means of a Take Action command). The TLVLOG command
manages the recording of information to RKLVLOG. The syntax and usage of this
command are as follows:
�� MODIFY stcname , TLVLOG SWITCH
,
CLASS=
class
,
COPIES=
copies
,
DEST=
dest �
COMMAND INPUT ===>
Data set name ===> ’data_set_name’
Member to use ===>
Disposition ===> NEW (OLD, NEW, SHR, MOD)
If the data set is to be created, specify the following.
Volume serial will be used to locate existing data sets if specified.
Management class ===> (Blank for default management class)
Storage class ===> (Blank for default storage class)
Volume serial ===> (Blank for authorized default volume) *
Device type ===> (Generic unit or device address) *
Data class ===> (Blank for default data class)
Space units ===> TRKS (BLKS, TRKS, CYLS, BY, KB, or MB)
Primary quantity ===> 5 (In above units)
Secondary quantity ===> 5 (In above units)
Directory blocks ===> 0 (Zero for sequential data set)
Record format ===> VBA
Record length ===> 240
Block size ===> 3120
* Only one of these fields may be specified
Figure 1. SDSF Print to Data Set panel
Appendix B. Problem determination 63
� ,
FCB=
fcb
,
FORM=
form
NO
,
MAXLINES=
maxlines
HOLD=
YES
�
� ,
UCS=
ucs
,
USER=
user
,
WTRNAME=
wtrname ��
where:
SWITCH
Dynamically allocates a new RKLVLOG file using the current values, begins
recording on the new file, and closes the current RKLVLOG file, releasing it
for processing by JES.
class Is the one-character JES SYSOUT class. CLASS=A is the ITMS:Engine
startup value.
copies Is the copy count. The valid range is 1-254. COPIES=1 is the startup value.
dest Is the 1-8 character JES SYSOUT destination. DEST=() is the startup
value.
fcb Is the 1-4 character FCB name to be used. FCB=() is the startup value.
form Is the 1-4 character form name to be used. FORM=() is the startup value.
hold Determines whether the SYSOUT is to be placed in a JES operator hold
when spun off. Specify YES (operator hold is requested) or NO. HOLD=NO
is the startup value.
Note: If HOLD=YES is specified, you must issue the appropriate JES
release command for the SYSOUT dataset to be processed.
maxlines
Is the maximum number of lines to be written to RKLVLOG, in thousands
(for example, MAXLINES=2 means a maximum of 2000 lines). The valid
range is 0 through 16000 (16 million lines). When this number is reached,
an automatic TLVLOG SWITCH is performed, closing the current RKLVLOG
and allocating a new one If the specified value is 0, there is no maximum;
you must manually enter TLVLOG SWITCH to switch log files.
MAXLINES=0 is the startup value.
Note: Unlike the other values, MAXLINES takes effect immediately. If the
new MAXLINES value is less than the number of lines that have
already been written to the current RKLVLOG, a switch is performed
immediately.
ucs Specifies the 1-4 character UCS name to be used. UCS=() is the startup
value.
user Is the 1-8 character user ID to which the SYSOUT is to be spooled. Ignored
if DEST is blank. USER=() is the startup value.
wtrname
Is the 1-8 character external writer name to be used. WTRNAME=() is the
startup value.
Notes:
1. The TLVLOG command performs up to three functions, depending on the
keywords specified. Assuming that you select all three functions, they are
performed in the following order:
64 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
a. Updates the dynamic allocation values. With the exception of MAXLINES,
these values are used when the next dynamic allocation is performed.
Values are updated whenever they are coded on the command.
b. Lists the current dynamic allocation values. This is always done.
c. Switches RKLVLOGs. This is done only when SWITCH is specified on the
command.
You can update values and request a switch with the same command. The
values are updated first, and then the switch is performed.
2. RKLVLOGs can be closed automatically after a certain number of records have
been written to them. Refer to the MAXLINES keyword for more information.
3. To set up an automatic RKLVLOG switch whenever the ITMS:Engine address
space is started, add the following command to your RKANCMD startup CLIST:
TLVLOG MAXLINES=nnn
This command causes RKLVLOG to be closed and released to JES whenever
nnn thousands of lines have been written. If needed, you can add other values
(for example, CLASS) to this command.
4. Many diagnostic messages are recorded in RKLVLOG. If you set RKLVLOG to
spin off automatically, or if you explicitly switch RKLVLOG, you must ensure that
the SYSOUT files are kept at least for the life of the ITMS:Engine run, in case
they are required for problem solving.
5. You might want to issue a TLVLOG SWITCH command after a problem occurs. This
spins off the RKLVLOG data related to the problem into a separate spool data
set, which can be included in the problem documentation. Be sure to include all
previously spun-off RKLVLOG files .
6. Because RKLVLOG is managed with standard IBM data management routines,
records are buffered before being written. If you are viewing the currently active
RKLVLOG with a product such as SDSF, you do not see the latest messages.
Issue the command FLUSH TLVLOG to force the current data management buffer
to be written. Do not use the TLVLOG SWITCH to spin off the current RKLVLOG for
this purpose, as it fragments the messages recorded in RKLVLOG.
7. Unless you explicitly set a non-zero MAXLINES value, RKLVLOG never
switches automatically.
8. If an error occurs when writing to RKLVLOG, ITMS:Engine issues a message
and disables RKLVLOG recording. However, messages are still written to
VIEWLOG and to all active operator interfaces. Depending on the error, you
might be able to restart RKLVLOG by issuing a switch request.
Here are some example of ways to use this command:
v To list the current RKLVLOG destination and values:
tlvlog
v To establish class X and destination SYSPROG as default SYSOUT attributes,
and the maximum number of lines as 20,000:
tlvlog class=x dest=sysprog maxlines=20
v To switch to a new RKLVLOG:
tlvlog switch
Flushing the log buffers: After a TLVLOG is switched, issuing an echo command
can flush the log buffers and ensure that new messages are written to the new
RKLVLOG. The ECHO command echoes any text entered back to the screen. The
syntax of the ECHO command is shown below:
Appendix B. Problem determination 65
�� ECHO
string ��
where string is a character string to be echoed back to the operator screen where
the ECHO command was entered.
Notes:
1. Use ECHO to verify that the ITMS:Engine operator facility is functioning properly
and to force all buffered messages to the log.
2. Even after an ECHO, log output might not be visible in JES3 systems, because
of the way JES3 manages spool buffers.
3. Enclosing string in single quotes is necessary only if you want to preserve
leading blanks.
Understanding and using the trace logs
When you open a trace log, you find a mix of status lines and numbered product
messages. Most messages with IDs are documented in the problem determination
guides for each monitoring agent. You can also determine the meaning of a
message by entering the message number into an Internet search engine such as
Google. The information that follows helps you interpret the messages and status
lines in a z/OS log.
Format of messages in a RAS1 log
A RAS1 log for a monitoring agent on z/OS includes the following information:
v Environmental information
– Operating system and CPU data. This information is prefaced with the
following string:
pppxxmmm
where:
ppp Is the component prefix.
xx Is the component code.
mmm Is the module name.
– Initial command line settings
v Component summary:
– Name of the module
– Information about where the library was loaded from
– Date and time the module was compiled
– Version (if this detail was specified)
v Formatted output, including entry and exit points and text strings. Entry and exit
points show flow into and out of a given function. The exit shows the return code,
if applicable. The text depends on the kind of trace specified. Here is an
example:
(00D41 F9C-1{99%}:KppMAIN.CPP,953,"MainWnd::MainWnd") Entry
(00D41 FD3-1{99%}:KppMAIN.CPP,959,"MainWnd::MainWnd") Exit
Time,Thread,{%stack avail},pgm_name,Line#,function,text
As noted earlier, not all functions are RAS1-enabled, and trace level might
exclude some paths.
66 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Using the Log and Trace Analyzer tool
Tivoli Monitoring Services includes a Log and Trace Analyzer tool that helps you
view, analyze, and correlate log files. You can evaluate event and error logs with
time synchronization.
Launch the Log and Trace Analyzer tool from the Tivoli Enterprise Portal Event
Tools view. You can then use the tool to view logs from the Tivoli Enterprise Portal
Server or Tivoli Enterprise Monitoring Server on a distributed system, or the
RKLVLOG from a monitoring agent or monitoring server on z/OS.
You can find more information about the Log and Trace Analyzer at
http://www.ibm.com/developerworks/autonomic/probdet.html.
Problems and workarounds
The following sections provide symptoms and workarounds for problems that might
occur with the IBM Tivoli Advanced Catalog Management:
v “Installation and configuration problem determination” on page 67
v “Workspace problem determination” on page 70
v “Situation problem determination” on page 71
Note: You can resolve some problems by ensuring that your system matches the
system requirements listed in Chapter 2, “Requirements for the monitoring
agent,” on page 3.This appendix provides agent-specific problem determination information. See the
IBM Tivoli Monitoring Problem Determination Guide for general problem
determination information.
Installation and configuration problem determination
This section provides solutions for installation and configuration problems.
No IBM Tivoli Advanced Catalog Management predefined
situations are listed in the Situation Editor
If the list of predefined situations listed in the Situation Editor does not include any
IBM Tivoli Advanced Catalog Management situations, you might have forgotten to
add application support to the Tivoli Monitoring Services components. For
instructions, see IBM Tivoli Advanced Catalog Management Monitoring Agent
Planning and Configuration Guide and IBM Tivoli Monitoring Installation and Setup
Guide.
Data is missing from all workspaces for a specific agent type
If a monitoring agent is not installed in the same consolidated software inventory
(CSI) as a z/OS hub monitoring server, its catalog and attribute files must be
transferred to the RKANDATV data set of the hub monitoring server. Similarly, if you
are using a z/OS hub, and you want to aggregate and prune historical data for any
agent, you must transfer the catalog and attribute files for the Summarization and
Pruning agent to the hub.
If these files are not located on the hub, all the workspaces for that type of agent
contain no data. The workspaces show KFWITM217E Request error:
SQL1_CreateRequest failed, rc=209, and the RKLVLOG shows many errors
building situations.
Appendix B. Problem determination 67
The required catalog and attribute files are installed on the Tivoli Enterprise Portal
Server when you install application support for an agent. From there you can then
transfer them to the hub. There are a number of ways to transfer these files. If the
Tivoli Enterprise Portal Server is installed on a Windows system, you can use the
Manage Tivoli Monitoring Services utility as follows:
1. Launch Manage Tivoli Monitoring Services. For example, Start > All Programs
> IBM Tivoli Monitoring > Manage Tivoli Monitoring Services.
2. Right-click Tivoli Enterprise Portal Server and select Advanced > Utilities >
FTP Catalog and Attribute files.
3. On the Select attribute and catalog data for transfer window, select the files
you want to transfer, then click OK.
4. On the FTP TEMS data to z/OS window, provide the following information:
v The name or IP address of the hub Tivoli Enterprise Monitoring Server
v A valid FTP user ID and password
v The fully qualified name of the RKANDATV data set (DSN)
5. After you have completed these fields, click OK to transfer the files. Click OK
again to confirm.
Communication between the monitoring agent and remote
monitoring server fails in a multi-home environment
The monitoring agent and a remote monitoring server might fail to connect or
communicate with each other in configurations with multi-home IP host systems and
Virtual Internet Protocol Addressing (VIPA). When Tivoli Monitoring Services
components perform IP discovery, they sometimes identify internal-use-only IP host
interface addresses (that is, addresses usable only inside a system or sysplex). A
connection failure occurs when a component uses an internal IP interface address
in attempting to converse with another component on a different system or sysplex.
Apply the following configuration changes to the monitoring agent and remote
monitoring server (if any), to force the use of the correct IP interface address.
Because configuring or reconfiguring the IBM Tivoli Advanced Catalog Management
product overwrites your changes, you must perform these actions after initial
configuration of the product and after any reconfiguration of the product.
Tip
You do not need to change the configuration of the hub monitoring server or
the portal server.
Changing the monitoring agent configuration: Edit the KDE_TRANSPORT
statement of the &rhilev.&rte.RKANPARU(KRNENV) data set member in the
monitoring agent runtime environment, as follows:
1. Add the EPHEMERAL:Y keyword.
2. Specify USE:N for alternative (non-pipe) IP protocols.KDE_TRANSPORT=\
IP.PIPE PORT:nnnnn EPHEMERAL:Y \
IP.UDP USE:N
where nnnnn is the IP port number of the monitoring server with which the
monitoring agent communicates.
Changing the remote monitoring server configuration: Complete the following
steps to change the remote monitoring server configuration:
68 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
1. Edit the KDE_TRANSPORT statement of the &rhilev.&rte.RKANPARU(KDSENV) data set member in the remote monitoring server
runtime environment, as follows:
a. Add the EPHEMERAL:Y keyword.
b. Specify USE:N for alternative (non-pipe) IP protocols.KDE_TRANSPORT=\
IP.PIPE PORT:nnnnn EPHEMERAL:Y \
IP.UDP USE:N
where nnnnn is the IP port number of the monitoring server.
2. Add the KDEB_INTERFACELIST=ip_host_address statement to the remote
monitoring server RKANPARU(KDSENV) member:
KDEB_INTERFACELIST=ip_host_address
where ip_host_address is the dotted-decimal IP host address for the system
where the monitoring server is running.
Historical data collection configuration problems
The persistent data store must be configured on the z/OS system where the IBM
Tivoli Advanced Catalog Management 2.1 monitoring agent is installed. The
persistent data store retains data for 24 hours. To enable long-term historical data
collection, the Tivoli Data Warehouse and the warehouse proxy agent must be
installed and configured on a distributed system. For instructions on configuring the
persistent data store, see the following publications:
v IBM Tivoli Advanced Catalog Management Monitoring Agent Planning and
Configuration Guide
v Configuring IBM Tivoli Enterprise Monitoring Server on z/OS
v IBM Tivoli Monitoring Administrator’s Guide
For instructions on installing and configuring the Tivoli Data Warehouse and the
warehouse proxy agent, see IBM Tivoli Monitoring Installation and Setup Guide.
U200 Port in use message found in RKLVLOG, indicating an
incorrect default port
After you complete all installation and configuration tasks for the IBM Tivoli
Advanced Catalog Management monitoring agent and try to start the monitoring
agent, you might find the following abend message in RKLVLOG, indicating a
connection failure:
U200 Port in use
One possible cause of this problem is that the port defined for communication
among the Tivoli Monitoring Services components is already reserved for a different
application in the PORT statement of the TCP/IP profile. In that case, complete the
following steps to correct the problem:
1. Verify that the existing port reservation is no longer needed, or choose a
different port for communication among the Tivoli Monitoring Services
components.
2. Edit your TCP/IP profile to reserve the port for the Tivoli Enterprise Monitoring
Server started procedure, or change the configuration settings for the portal
server (on a Windows, Linux, or UNIX system) and monitoring agent (on a z/OS
system) to communicate with the Tivoli Enterprise Monitoring Server on a
different port.
3. Stop and restart the monitoring server, monitoring agent, and portal server.
Appendix B. Problem determination 69
Workspace problem determination
This section shows problems that might occur with workspaces. This appendix
provides agent-specific problem determination information. See the IBM Tivoli
Monitoring Problem Determination Guide for general problem determination
information.
Information in a workspace is inconsistent or a table in a
workspace has no rows
It is important to keep in mind that the workspaces displayed in the Tivoli Enterprise
Portal are static, while the z/OS data is dynamic. When you view a workspace, you
see data values from the most recent data collection. Data can change between the
time it is collected and the time it is displayed on the workstation, and you might
see inconsistencies caused by different times of data collection for different data
items in the workspace.
You see the following message: KFWIT083W Default link is
disabled for the selected object; please verify link and link
anchor definitions
You see this message because some links do not have default workspaces.
Right-click the link to access a list of workspaces to select.
Cross-product links to OMEGAMON XE for Storage workspaces
do not function
Cross-product links from IBM Tivoli Advanced Catalog Management workspaces to
OMEGAMON XE for Storage workspaces function only if an OMEGAMON XE for
Storage monitoring agent is installed and running on the same z/OS image as the
IBM Tivoli Advanced Catalog Management monitoring agent. Otherwise, message
KFWITM081E The link target cannot be found is displayed when you attempt to
link to an OMEGAMON XE for Storage workspace. If you see this message even
though an OMEGAMON XE for Storage monitoring agent is installed on the z/OS
system, check to make sure the agent is running.
If you installed application support for monitoring agents that you have not installed,
links to these agents' workspaces appear as valid destinations for dynamic
cross-product links. To prevent the inclusion of misleading links, install application
support only for the monitoring agents that you have installed.
Unless your environment is configured so that all monitoring agents are running on
all z/OS systems being monitored, the KFWITM081E message does not necessarily
indicate a problem.
Cross-product links are missing from the link list
Cross-product workspace links to OMEGAMON XE for Storage workspaces are
displayed in the link list if the OMEGAMON XE for Storage workspace you are
linking to has been installed and your Tivoli Enterprise Portal user ID is authorized
to access the OMEGAMON XE for Storage product.
If a cross-product link is missing from the link list, verify that your user ID is
authorized to access the OMEGAMON XE for Storage product and that you have
installed application support for both IBM Tivoli Advanced Catalog Management and
OMEGAMON XE for Storage.
70 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
The name of the attribute does not display in a bar chart or
graph view
When a chart or graph view that includes the attribute is scaled to a small size, a
blank space is displayed instead of a truncated name. To see the name of the
attribute, expand the view of the chart until there is sufficient space to display all
characters of the attribute’s name.
You start collection of historical data but the data cannot be
seen
Managing options for historical data collection:
v Basic historical data collection populates the Warehouse with raw data. This type
of data collection is turned off by default. See the IBM Tivoli Monitoring
Administrator’s Guide for information on managing this feature including how to
set the interval at which data is collected. By setting a more frequent interval for
data collection you reduce the load on the system incurred every time data is
uploaded.
v You use the Summarization and Pruning monitoring agent to collect specific
amounts and types of historical data. Be aware that historical data is not
displayed until the Summarization and Pruning monitoring agent begins collecting
the data. By default, this agent begins collection at 2 AM daily. At that point, data
is visible in the workspace view. See the IBM Tivoli Monitoring Administrator’s
Guide to learn how to modify the default collection settings.
Historical data collection is unavailable because of incorrect
queries in the Tivoli Enterprise Portal
The column, Sort By, Group By, and First/Last functions are not compatible with the
historical data collection feature. Use of these advanced functions makes a query
ineligible for historical data collection.
Even if data collection has been started, you cannot use the time span feature if the
query for the chart or table includes column functions or advanced query options
(Sort By, Group By, First / Last).
To ensure support of historical data collection, do not use the Sort By, Group By, or
First/Last functions in your queries.
See the IBM Tivoli Monitoring Administrator’s Guide the Tivoli Enterprise Portal
online help for information about the Historical Data Collection function.
The process name is truncated
When you use a long process name in the situation, the process name is truncated.
Truncation of process or service names for situations in the Availability table in the
portal display is the expected behavior. 100 bytes is the maximum name length
Regular (non-historical) monitoring data fails to be displayed.
Check the formation of the queries you use to gather capture data. For example,
look for invalid SQL statements.
Situation problem determination
This section provides information about both general situation problems and
problems with the configuration of situations. See the IBM Tivoli Monitoring Problem
Determination Guide for more information about problem determination for
situations.
Note: To get started with many of the solutions in this section, perform these steps:
Appendix B. Problem determination 71
1. Launch the Tivoli Enterprise Portal.
2. Click Edit > Situation Editor.
3. In the tree view, choose the agent whose situation you want to modify.
4. Choose the situation in the list. The Situation Editor view is displayed.
Monitoring activity requires too much disk space
Check the RAS trace logging settings that are described in “Setting up a trace on a
z/OS system” on page 55. For example, trace logs grow rapidly when you apply the
ALL logging option.
Monitoring activity requires too many system resources
“Disk capacity planning for historical data” on page 31 describes the performance
impact of specific attribute groups. If possible, decrease your use of the attribute
groups that require greater system resources.
A formula that uses mathematical operators appears to be
incorrect
For example, if you were monitoring Linux, a formula that calculates when Free
Memory falls under 10 percent of Total Memory does not work: LT
#’Linux_VM_Stats.Total_Memory’ / 10 . This formula is incorrect because situation
predicates support only logical operators. Your formulas cannot have mathematical
operators.
Note: The Situation Editor provides alternatives to math operators. Regarding the
example, you can select % Memory Free attribute and avoid the need for
math operators.
A predefined situation that has been edited or a user created
situation displays the severity UNKNOWN in IBM Tivoli
Enterprise Console
IBM Tivoli Monitoring is configured to provide data to the optional product IBM Tivoli
Enterprise Console. However, either a predefined situation that has been edited or
a user created situation displays the severity UNKNOWN in IBM Tivoli Enterprise
Console. For a situation to have the correct severity in IBM Tivoli Enterprise
Console for those situations that are not mapped, you need to ensure that an entry
exists in the tecserver.txt file for the situation and that SEVERITY is specified.
See the "Configuring Tivoli Enterprise Console Integration" chapter in the IBM Tivoli
Monitoring Administrator’s Guide for more information.
You want to change the appearance of situations when they are
displayed in the Navigation tree
Do the following:
1. Right-click an item in the Navigation tree.
2. Select Situations in the pop-up menu. The Situation Editor window is displayed.
3. Select the situation that you want to modify.
4. Use the Status pull-down menu in the lower right of the window to set the
status and appearance of the Situation when it triggers.
Note: This status setting is not related to severity settings in IBM Tivoli
Enterprise Console.
72 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
The situation for a specific agent is not visible in the Tivoli
Enterprise Portal
Open the Situation Editor. Access the All managed servers view. If the situation is
absent, confirm that the monitoring server has been seeded for the agent. If not,
seed the server, as described in the IBM Tivoli Monitoring Installation and Setup
Guide.
The monitoring interval is too long
Access the Situation Editor view for the situation that you want to modify. Check the
Sampling interval area in the Formula tab. Adjust the time interval as needed.
The situation did not activate at startup
Manually recycle the situation as follows:
1. Right-click the situation and choose Stop Situation.
2. Right-click the situation and choose Start Situation.
Note: You can permanently avoid this problem by placing a check mark in the Run
at Startup option of the Situation Editor view for a specific situation.
The situation is not displayed
Click the Action tab and check whether the situation has an automated corrective
action. This action can occur directly or through a policy. The situation might be
resolving so quickly that you do not see the event or the update in the graphical
user interface.
An Alert event has not occurred even though the predicate has
been properly specified
Check the logs, reports, and workspaces.
A situation fires on an unexpected managed object
Confirm that you have distributed and started the situation on the correct managed
system.
The product did not distribute the situation to a managed system
Click the Distribution tab and check the distribution settings for the situation.
The situation does not fire
Incorrect predicates are present in the formula that defines the situation. For
example, the managed object shows a state that normally triggers a monitoring
event, but the situation is not true because the wrong attribute is specified in the
formula.
In the Formula tab, analyze predicates as follows:
1. Click the fx icon in the upper-right corner of the Formula area. The Show
formula window is displayed.
a. Confirm the following details in the Formula area at the top of the window:
v The attributes that you intend to monitor are specified in the formula.
v The situations that you intend to monitor are specified in the formula.
v The logical operators in the formula match your monitoring goal.
v The numerical values in the formula match your monitoring goal.
b. (Optional) Click the Show detailed formula check box in the lower left of
the window to see the original names of attributes in the application or
operating system that you are monitoring.
c. Click OK to dismiss the Show formula window.
Appendix B. Problem determination 73
2. (Optional) In the Formula area of the Formula tab, temporarily assign numerical
values that immediately trigger a monitoring event. The triggering of the event
confirms that other predicates in the formula are valid.
Note: After you complete this test, you must restore the numerical values to
valid levels so that you do not generate excessive monitoring data based
on your temporary settings.
Situation events are not displayed in the Events Console view of
the workspace
Associate the situation with a workspace.
Note: The situation does not need to be displayed in the workspace. It is sufficient
that the situation be associated with any workspace.
You do not have access to a situation
Note: You must have administrator privileges to perform these steps.
Do the following:
1. Select Edit > Administer Users to access the Administer Users window.
2. In the Users area, select the user whose privileges you want to modify.
3. In the Permissions tab, Applications tab, and Navigator Views tab, select the
permissions or privileges that correspond to the user’s role.
4. Click OK.
A managed system seems to be offline
Do the following:
1. Select Physical View and highlight the Enterprise Level of the navigator tree.
2. Select View > Workspace > Managed System Status to see a list of managed
systems and their status.
3. If a system is offline, check network connectivity and status of the specific
system or application.
Support information
If you have a problem with your IBM software, you want to resolve it quickly. This
section describes the following options for obtaining support for IBM software
products:
v “Using IBM Support Assistant”
v “Obtaining fixes” on page 75
v “Receiving weekly support updates” on page 75
v “Contacting IBM Software Support” on page 76
Using IBM Support Assistant
The IBM Support Assistant is a free, stand-alone application that you can install on
any workstation. You can then enhance the application by installing product-specific
plug-in modules for the IBM products you use.
The IBM Support Assistant saves you time searching product, support, and
educational resources. The IBM Support Assistant helps you gather support
information when you need to open a problem management record (PMR), which
you can then use to track the problem.
74 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
The product-specific plug-in modules provide you with the following resources:
v Support links
v Education links
v Ability to submit problem management reports
If your product does not use IBM Support Assistant, use the links to support topics
in your information center. In the navigation frame, check the links for resources
listed in the ibm.com and related resources section where you can search the
following resources:
v Support and assistance (includes search capability of IBM Technotes and IBM
Downloads for interim fixes and workarounds)
v Training and certification
v IBM developerWorks
v IBM Redbooks
v General product information
If you cannot find the solution to your problem in the information center, search the
following Internet resources for the latest information that might help you resolve
your problem:
v Forums and newsgroups
v Google.com
Obtaining fixes
A product fix might be available to resolve your problem. To determine what fixes
are available for your IBM software product, follow these steps:
1. Go to the Software support Web site at http://www.ibm.com/software/support.
2. Click the Download tab.
3. Select the operating system in the Operating system menu.
4. Type search terms in the Enter search terms field.
5. As appropriate, use other search options to further define your search.
6. Click Search.
7. From the list of downloads returned by your search, click the name of a fix to
read the description of the fix and to optionally download the fix.
For more information about the types of fixes that are available, see the IBM
Software Support Handbook at http://techsupport.services.ibm.com/guides/handbook.html.
Receiving weekly support updates
To receive weekly e-mail notifications about fixes and other software support news,
follow these steps:
1. Go to the IBM Software Support Web site at http://www.ibm.com/software/support.
2. Click My account in the upper right corner of the page.
3. Click Subscribe to IBM e-news. (If you have already subscribed and want to
modify your subscription preferences, click Modify subscriptions and follow the
instructions on screen.)
4. Follow the instructions on screen to provide the following data:
v Your personal contact information.
Appendix B. Problem determination 75
v Your areas of interest.
v The types of subscriptions and regional versions that you want to receive.
5. Review the subscription confirmation to confirm your settings.
If you experience problems with the My support feature, you can obtain help in one
of the following ways:
Online
Send an e-mail message to [email protected], describing your problem.
By phone
Call 1-800-IBM-4You (1-800-426-4968).
Contacting IBM Software Support
IBM Software Support provides assistance with product defects.
Before contacting IBM Software Support, your company must have an active IBM
software maintenance contract, and you must be authorized to submit problems to
IBM. The type of software maintenance contract that you need depends on the type
of product you have:
v For IBM distributed software products (including, but not limited to, Tivoli, Lotus,
and Rational products, as well as DB2 and WebSphere products that run on
Windows, or UNIX operating systems), enroll in Passport Advantage in one of the
following ways:
Online
Go to the Passport Advantage Web site at http://www-306.ibm.com/software/howtobuy/passportadvantage/pao_customers.htm .
By phone
For the phone number to call in your country, go to the IBM Software
Support Web site at http://techsupport.services.ibm.com/guides/contacts.html and click the name of your geographic region.
v For customers with Subscription and Support (S & S) contracts, go to the
Software Service Request Web site at https://techsupport.services.ibm.com/ssr/login.
v For customers with IBMLink, CATIA, Linux, OS/390, iSeries, pSeries, zSeries,
and other support agreements, go to the IBM Support Line Web site at
http://www.ibm.com/services/us/index.wss/so/its/a1000030/dt006.
v For IBM eServer software products (including, but not limited to, DB2 and
WebSphere products that run in zSeries, pSeries, and iSeries environments), you
can purchase a software maintenance agreement by working directly with an IBM
sales representative or an IBM Business Partner. For more information about
support for eServer software products, go to the IBM Technical Support
Advantage Web site at http://www.ibm.com/servers/eserver/techsupport.html.
If you are not sure what type of software maintenance contract you need, call
1-800-IBMSERV (1-800-426-7378) in the United States. From other countries, go to
the contacts page of the IBM Software Support Handbook on the Web at
http://techsupport.services.ibm.com/guides/contacts.html and click the name of your
geographic region for phone numbers of people who provide support for your
location.
To contact IBM Software support, follow these steps:
1. “Determining the business impact” on page 77
76 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
2. “Describing problems and gathering information”
3. “Submitting problems”
Determining the business impact
When you report a problem to IBM, you are asked to supply a severity level.
Therefore, you need to understand and assess the business impact of the problem
that you are reporting. Use the following criteria:
Severity 1
The problem has a critical business impact. You are unable to use the
program, resulting in a critical impact on operations. This condition requires
an immediate solution.
Severity 2
The problem has a significant business impact. The program is usable, but
it is severely limited.
Severity 3
The problem has some business impact. The program is usable, but less
significant features (not critical to operations) are unavailable.
Severity 4
The problem has minimal business impact. The problem causes little impact
on operations, or a reasonable circumvention to the problem was
implemented.
Describing problems and gathering information
When describing a problem to IBM, be as specific as possible. Include all relevant
background information so that IBM Software Support specialists can help you
solve the problem efficiently. To save time, know the answers to these questions:
v What software versions were you running when the problem occurred?
v Do you have logs, traces, and messages that are related to the problem
symptoms? IBM Software Support is likely to ask for this information.
v Can you re-create the problem? If so, what steps were performed to re-create
the problem?
v Did you make any changes to the system? For example, did you make changes
to the hardware, operating system, networking software, and so on.
v Are you currently using a workaround for the problem? If so, be prepared to
explain the workaround when you report the problem.
See “Gathering product information for IBM Software Support” on page 49 for
further tips for gathering information for IBM Software Support.
Submitting problems
You can submit your problem to IBM Software Support in one of two ways:
Online
Click Submit and track problems on the IBM Software Support site
athttp://www.ibm.com/software/support/probsub.html. Type your information
into the appropriate problem submission form.
By phone
For the phone number to call in your country, go to the contacts page of the
IBM Software Support Handbook at http://techsupport.services.ibm.com/guides/contacts.html and click the name of your geographic region.
If the problem you submit is for a software defect or for missing or inaccurate
documentation, IBM Software Support creates an Authorized Program Analysis
Appendix B. Problem determination 77
Report (APAR). The APAR describes the problem in detail. Whenever possible, IBM
Software Support provides a workaround that you can implement until the APAR is
resolved and a fix is delivered. IBM publishes resolved APARs on the Software
Support Web site daily, so that other users who experience the same problem can
benefit from the same resolution.
Informational, warning, and error messages
This appendix introduces message logging and explains how to gather information
from those logs.
Message logging refers to the text and numeric messages created by the software.
These messages relay information about how the system or application is
performing and can alert you to exceptional conditions when they occur. Messages
are sent to an output destination, such as a file, database, or console screen.
If you receive a warning or error message, you can do one of the following:
v Follow the instructions listed in the Detail window of the message if this
information is included there.
v Consult the message details listed in this appendix to see what action you can
take to correct the problem.
v Consult the message log for message ID and text, time and date of the
message, as well as other data you can use to diagnose the problem.
Message format
IBM Tivoli Advanced Catalog Management messages have the following format:
Message ID and text
Explanation
Operator Response
The message ID has the following format:
CCC####severity
where:
CCC Prefix that indicates the component to which the message applies. The
component is one of the following:
KRN General IBM Tivoli Advanced Catalog Management messages
#### Number of the message
severity
Severity of the message. There are three levels of severity:
I Informational messages provide feedback about something that
happened in the product or system that might be important. These
messages can provide guidance when you are requesting a specific
action from the product.
W Warning messages call your attention to an exception condition.
The condition might not be an error but can cause problems if not
resolved.
E Error messages indicate that an action cannot be completed
because of a user or system error. These messages require user
response.
78 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
The Text of the message provides a general statement regarding the problem or
condition that occurred. The Explanation provides additional information about the
message and what might have caused the condition. The Operator Response
provides actions to take in response to the condition, particularly for error messages
(messages with the ″E″ suffix).
Note: Many message texts and explanations contain variables, such as the specific
name of a server or application. Those variables are represented in this
appendix as symbols, such as ″&1.″ Actual messages contain values for
these variables.
This appendix includes the messages for the following software:
v IBM Tivoli Advanced Catalog Management
IBM Tivoli Advanced Catalog Management messages
Notes:
1. In the following messages, id is replaced by the TEDA server ID. This ID
matches the TEDA(Kpp) parameter passed to the TEDA server started task
program.
2. When any of the IBM Tivoli Enterprise Portal agents (KRJ, KRG, or KRN) share
the same address space, the id and Kpp values will be those of the TEDA
server address space.
KRN0001E id Required LE module module not loaded
Explanation: The indicated load module module is required by the Language Environment interface cannot be found
or loaded.
Operator response: Validate that the indicated load module can be found in either the JOBLIB/STEPLIB data sets
or the z/OS system linklist. A server restart will be required to resolve the problem.
KRN0002E id LE Environment initialization failed RC=rc
Explanation: An attempt to initialize Language Environment for this task has failed with the indicated return code rc.
The return code is issued from the init_sub_dp function call to CEEPIPI.
Operator response: Please refer to the z/OS Language Environment Programming Guide for an explanation of the
return codes and possible corrective actions. A server restart will be required to resolve the problem.
KRN0003E id LE Environment termination failed RC=rc
Explanation: An attempt to initialize Language Environment for this task has failed with the indicated return code rc.
The return code is issued from the term function call to CEEPIPI.
Operator response: Please refer to the z/OS Language Environment Programming Guide for an explanation of the
return codes and possible corrective actions.
KRN0004E id CEEPIPI add of module failed RC=rc
Explanation: An attempt to add the indicated load module module to the Language Environment function table has
failed with the indicated return code rc. The return code is issued from the add_entry function call to CEEPIPI.
Operator response: Please refer to the z/OS Language Environment Programming Guide for an explanation of the
return codes and possible corrective actions. A server restart will be required to resolve the problem.
Appendix B. Problem determination 79
KRN0005E id CEEPIPI function module missing
Explanation: The required Language Environment function load module module could not be found.
Operator response: There should be an AGENT statement of type ″PIPI″ for the indicated load module module in
the KppSHRxx member that is being used by the TEDA server. A server restart will be required to resolve the problem.
KRN0006E id CEEPIPI call of module failed RC=rc
Explanation: An attempt to call the indicated load module module to the Language Environment function table has
failed with the indicated return code rc. The return code is issued from the call_sub function call to CEEPIPI.
Operator response: Please refer to the z/OS Language Environment Programming Guide for an explanation of the
return codes and possible corrective actions. A server restart will be required to resolve the problem.
KRN0007I id Agent agent using port portnum
Explanation: The indicated TEP agent agent is using the indicated port number portnum. The value of the port
number is taken from the KppPORT keyword on the GLOBAL statement in the KppPRDxx member.
Operator response: No action is required.
KRN0008I id Agent agent connected to TEMA
Explanation: The indicated TEP agent agent has successfully connected to the TEMA address space.
Operator response: No action is required.
KRN0009I id Agent agent disconnected from TEMA
Explanation: The indicated TEP agent agent has successfully disconnected from the TEMA address space.
Operator response: No action is required.
KRN0010E id Agent agent service function failed RC=rc
Explanation: The indicated agent agent encountered a non-zero return code rc when calling the indicated CPCI
function function.
Operator response: Refer to the following list of return codes
v CP_PORT_NOT_SET
v CP_SOCKET_OPEN_FAILED
v CP_STATE_ERROR
v CP_WRITE_ERROR
v CP_PARSING_ERROR
v CP_ATTRIBUTE_GROUP_NOT_REGISTERED
v CP_HANDLE_NOT_FOUND
v CP_ID_NOT_FOUND
v CP_MALLOC_FAILED
For CP_SOCKET_OPEN_FAILED, check that the TEMA address space is active and accepting connections from the
″Kpp″ product. When this condition is received, the TEDA address space retries every 30 seconds. For all other return
codes, please contact IBM Support.
KRN0011E id Attribute group register not found
Explanation: The internal attribute group register was not found. All attribute groups will not be registered with TEP.
Operator response: Ensure that the KppTEP00 agent statement is present in the KppSHRxx member. A server
restart will be required to resolve the problem.
80 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
KRN0012E id Attribute group register is full
Explanation: There is no more room in the internal attribute group register. All subsequent attribute groups will not
be registered with TEP.
Operator response: Contact IBM Support.
KRN0013E id Attribute group module module not found
Explanation: One or more attribute groups require the indicated load module module and it could not be found or
loaded.
Operator response: Verify that the indicated load module can be found in either the JOBLIB or STEPLIB data sets
or the z/OS system linklist. A server restart will be required to resolve the problem.
KRN0014I id Attribute group group assigned handle handle
Explanation: The indicated attribute group group has been assigned the indicated handle handle.
Note: This message is only shown for MsgLevel(1) and above.
Operator response: No action is required.
KRN0015I id Attribute group group inactivated
Explanation: The indicated attribute group group has been inactivated and no further requests will be handled. This
message is normally issued during server termination.
Operator response: No action is required.
KRN0016E id Attribute group group already registered
Explanation: An attempt to register the indicated attribute group group has been made when there is already one of
the same name registered. The register request will be refused.
Operator response: Contact IBM Support.
KRN0017I id Attribute group group registered with TEMA
Explanation: An attempt to register the indicated attribute group group has been made successfully. Data can now
flow between TEP and the TEDA server for this attribute group.
Operator response: No action is required.
KRN0018I id Attribute group registration complete for agent
Explanation: The indicated agent agent has completed its registration phase.
Operator response: No action is required.
KRN0019I id text
Explanation: This message is issued in response to a Take Action TEP request. The text of text varies depending on
the context of the action.
Operator response: It is intended that this message is processed by your automated operations software.
KRN0020W id Agent agent has no associated attribute groups
Explanation: The indicated agent agent has completed its registration phase and has not registered any attribute
groups. This happens when all of the attribute groups are asynchronous in nature (pure event table) but the KppSYNC
agent is defined so that it can respond to the TEP shutdown requests.
Operator response: No action is required.
Appendix B. Problem determination 81
KRN0021W id TaskRequest received but no handler defined for product
Explanation: A take action request from TEP has been received for this product but there are no take action
handlers defined for this product.
Operator response: Contact IBM Support.
KRN0030W TEDA Kpp not found - Retrying every 60 seconds
Explanation: The KppSIGNL utility program could not find the TEDA server specified on the runtime parameter. It will
retry in 60 seconds.
Operator response: Start the indicated TEDA server.
KRN0031E TEDA Kpp not found and maximum retry attempts exceeded
Explanation: The KppSIGNL utility program could not find the TEDA server specified on the runtime parameter and
the maximum number of retry attempts has been exceeded. The KppSIGNL program will terminate with a return code
of 8.
Operator response: Start the indicated TEDA server.
KRN0032W TEDA Kpp not found - Retry or Cancel (R/C)
Explanation: The KppSIGNL utility program could not find the TEDA server specified on the runtime parameter and
RETRY(WTOR) was either specified or defaulted to.
Operator response: Start the TEDA server indicated. Specify R to retry or C to cancel the wait for the TEDA server.
KRN0033W TEDA Kpp not found and retry cancelled by operator
Explanation: The KppSIGNL utility program could not find the TEDA server specified on the runtime parameter and
RETRY(WTOR) was either specified or defaulted to. The operator then replied C to Kpp0032W.
Operator response: No action is required.
KRN0034I Signal service failed RC=rc RSN=rsn
Explanation: The KppSIGNL utility program failed with the indicated return code rc and reason code rsn.
Operator response: Examine any previous messages issued by the KppSIGNL utility.
KRN0035W Signal signal not found for teda
Explanation: The KppSIGNL utility program could not find the indicated signal signal the TEDA teda.
Operator response: Check that the signal name is correct and has been defined as a resource for the TEDA server.
KRN0036I Signal signal updated for teda
Explanation: The KppSIGNL utility program found the indicated signal signal for the TEDA teda and its value has
been updated.
Operator response: No action is required.
KRN0053I id agent initializing
Explanation: The indicated agent agent is initializing.
Operator response: No action is required.
82 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
KRN0054I id agent initialization complete
Explanation: The indicated agent agent has completed its initialization phase.
Operator response: No action is required.
KRN0055W id agent invalid runtime keyword keyword ignored
Explanation: The indicated agent agent has encountered an invalid runtime keyword keyword. The keyword will be
ignored.
Operator response: Correct the specification of the runtime keyword or contact IBM Support. A server restart will be
required to resolve the problem.
KRN0056I id agent terminating
Explanation: The indicated agent agent is terminating.
Operator response: No action is required.
KRN0057I id agent termination complete
Explanation: The indicated agent agent has completed its termination phase.
Operator response: No action is required.
KRN0059I id Current user ASID id Jobname Jobname
Explanation: During shutdown, the TEDA server has detected that some address spaces that still have outstanding
active connections. Each address space is listed by the Kpp0059I message. The TEDA server will retry shutdown in
30 seconds.
Operator response: No action is required.
KRN0060I id There are no current users
Explanation: During shutdown, the TEDA server has detected that there are no current connections—termination
can now proceed.
Operator response: No action is required.
KRN0062E id Operating system level not supported
Explanation: The TEDA server has detected a level of z/OS that is not supported. The server will terminate.
Operator response: Check the installation instructions for the software prerequisites.
KRN0063E id Architecture level not supported
Explanation: The TEDA server has detected a level of hardware that is not supported. The server will terminate.
Operator response: Check the installation instructions for the hardware prerequisites.
KRN0064W id Shutdown prevented by active users : Retry/Ignore (R, I)
Explanation: The TEDA server shutdown is prevented because there are still active sessions with other address
spaces. The TEDA server will automatically retry every 30 seconds if the operator does not reply to this message.
Operator response: Reply R to retry or I to ignore. Replying I should be used with extreme caution and only in an
emergency situation or when the z/OS system is being shutdown in preparation for an IPL. If you specify I, the TEDA
server termination will remove critical resources from the system without attempting normal serialization and it will not
free the common storage control blocks — leaving approximately 240K of orphaned E-CSA. The TEDA server will also
not be able to restart until the address spaces that were in session have completely disconnected. Therefore, it is
strongly recommended that you reply R or wait for the TEDA server to retry every 30 seconds.
Appendix B. Problem determination 83
KRN0074I id TEDA initialization complete
Explanation: The TEDA server has successfully completed its initialization phase.
Operator response: No action is required.
KRN0075I id Waiting for active connections to terminate
Explanation: The TEDA server is terminating but cannot continue until all active connections are terminated. If active
connections are present, message KRN0064W will be issued.
Operator response: No action is required.
KRN0078I id TEDA shutdown proceeding
Explanation: The TEDA server is shutting down and is about to pass control to its termination routines.
Operator response: No action is required.
KRN0080I id TEDA removing services
Explanation: All active connections are terminated. The TEDA server is now removing internal services.
Operator response: No action is required.
KRN0082I id Dataspace dataspace created successfully
Explanation: The indicated dataspace dataspace has been successfully created.
Note: This message is only shown for MsgLevel(1) and above.
Operator response: No action is required.
KRN0083I id Dataspace dataspace removed
Explanation: The indicated dataspace dataspace has been successfully removed.
Note: This message is only shown for MsgLevel(1) and above.
Operator response: No action is required.
KRN0085E id Required keywords not specified
Explanation: Required keywords on the TEDA server modify command were not specified.
Operator response: Check the TEDA server modify command syntax and re-specify the required keywords.
KRN0086E id Unknown server server specified
Explanation: An agent specified a server server that is not valid.
Operator response: Correct the agent statement and restart the server.
KRN0088I id Command accepted
Explanation: The TEDA server operator command has been accepted.
Operator response: No action is required.
84 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
KRN0089E id Invalid command command
Explanation: The TEDA server operator command command is not valid.
Operator response: Check the TEDA server modify command syntax and re-issue the command.
KRN0090I id TEDA starting
Explanation: The TEDA server is starting.
Operator response: No action is required.
KRN0092I id Server server control task terminated
Explanation: The indicated server server control task has terminated.
Operator response: No action is required.
KRN0093E id Server server already stopped
Explanation: An attempt was made to stop a server that was already stopped. The request was ignored.
Operator response:
KRN0097I id Agent agent in server server quiesced
Explanation: The indicated agent named agent in server server is now quiesced. This message is issued for all
matching agents when the TEDA server quiesce command has been issued. If the agent code supports the quiesce
command, it will cease activity until its is resumed.
Operator response: No action is required.
KRN0098I id Agent agent in server server already quiesced - no action taken
Explanation: The indicated agent named agent in server server was already quiesced when a new attempt to
quiesce it was received. No action was taken.
Operator response: No action is required.
KRN0099I id No matches for Agent agent in server server
Explanation: There was no matches for the agent mask agent for the indicated server server.
Operator response: Re-specify the AGENT() keyword on the TEDA server operator modify command.
KRN0100I id No action taken for agent agent in server server
Explanation: There was no actions taken against any agent agent in the indicated server server. This is usually
caused by the agents already being in the desired state when the quiesce or resume commands were issued.
Operator response: Verify that the correct modify command was issued to the TEDA server.
KRN0102I id Agent task name agent heartbeat
Explanation: Trace message written by the indicated agent agent when the MsgLevel is greater than 0.
Operator response: No action is required.
KRN0103E id Common Dataspace dataspace ALESERV failed RC=rc
Explanation: During initialization the TEDA server could not perform the ALESERV ADD for the TEDA common
dataspace. All SMF record intercept functions will be disabled.
Operator response: Contact IBM Support.
Appendix B. Problem determination 85
KRN0104E id Required type name missing
Explanation: The required object of type type named name could not be found.
Operator response: Ensure that the associated statement is present in the KppSHRxx or KppPRDxx member. A
server restart will be required to resolve the problem.
KRN0105E id Required keyword type missing for command
Explanation: The required keyword of type type is missing for the operator modify command command.
Operator response: Verify the syntax of the modify command and re-issue the command.
KRN0107I id agent msgtext
Explanation: Trace message written by the indicated agent agent when the MsgLevel is greater than 0.
Operator response: No action is required.
KRN0109I id Agent task name agent terminated RC=rc
Explanation: The indicated agent agent has terminated with the specified return code rc.
Operator response: If the return code is non-zero and unexpected please contact IBM Support.
KRN0115I id Agent agent : Quiesced(Y/N) Address (address)
Explanation: Issued as the response from the D AGENT(mask) modify command, this message shows the quiesced
state and the address address in common storage of the agent block for the indicated agent agent.
Operator response: No action is required.
KRN0118I id Agent agent in server server resumed
Explanation: The indicated agent agent in server server has been resumed and will restart its work.
Operator response: No action is required.
KRN0119I id Agent agent in server server already active - no action taken
Explanation: The indicated agent agent in server server is already active and an attempt was made to resume it.
The request is ignored.
Operator response: Ensure that the R AGENT(mask) command was issued correctly.
KRN0126I id IBM Tivoli/product TEDA version
Explanation: The version version or the IBM Tivoli product product shown at TEDA server startup.
Operator response: No action is required.
KRN0127I id Agent task name agent initialization complete
Explanation: The indicated agent agent has completed its initialization phase.
Operator response: No action is required.
KRN0134E id Unknown keyword keyword
Explanation: An unknown keyword was discovered in the TEDA KppPRDxx or KppSHRxx member or as part of the
T AGENT(mask) operator command.
Operator response: Re-specify the keyword and restart the server or re-issue the operator command.
86 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
KRN0135E id Error in statement : statement
Explanation: During the process of reading the KppPRDxx and KppSHRxx members, the TEDA server encountered
one or more errors in the statement shown statement.
Operator response: Examine earlier messages that explain the errors discovered.
KRN0143E id One or more parameters missing from the type statement
Explanation: During the process of reading the KppPRDxx and KppSHRxx members, the TEDA server encountered
one or more missing parameters for the indicated statement type type.
Operator response: Correct the statement in error and restart the TEDA server.
KRN0144E id Dataspace dataspace DSPSERV failed RC=rc RSN=rsn
Explanation: During the creation of the indicated dataspace dataspace, the DSPSERV service failed with return
code rc and reason code rsn.
Operator response: Contact IBM Support.
KRN0145E id ALESERV failed RC=rc
Explanation: During an attempt to add a dataspace ALET to the access list, the ALESERV service failed with return
code rc.
Operator response: Contact IBM Support.
KRN0147I id Agent task name agent initializing
Explanation: The indicated agent agent is beginning its initialization phase.
Operator response: No action is required.
KRN0151E id Required keyword keyword missing from type for agent
Explanation: During the process of reading the KppPRDxx and KppSHRxx members, the required keyword keyword
was missing from the statement type type for the indicated agent agent.
Operator response: Correct the statement in error and restart the TEDA server.
KRN0152I id Module module loaded successfully at address address
Explanation: The indicated load module module has been loaded at address address.
Note: This message is only shown for MsgLevel(1) and above.
Operator response: No action is required.
KRN0153E id Agent task name agent storage obtain failed
Explanation: The indicated agent agent could not obtain the required storage to perform its actions. Processing is
suspended and retried during the next sampling interval.
Operator response: Increase the REGION size allocated to the TEDA server.
KRN0157W id Agent task name agent disabled - maximum restart count exceeded
Explanation: The indicated agent agent has terminated unexpectedly too many times and has exceeded its Restart()
value. The agent will not be restarted.
Operator response: Examine the cause of the unexpected termination and contact IBM Support.
Appendix B. Problem determination 87
KRN0161E id Fatal error error in module module
Explanation: There has been a non-recoverable error error in server module module. The TEDA server will
terminate.
Operator response: Contact IBM support.
KRN0162I id Agent agent in server TEDA updated with new value
Explanation: The indicated agent agent has been updated with a new value using the SET modify operator
command.
Operator response: No action is required.
KRN0164E id Agent task name agent data collection failed RC=rc RSN=rsn
Explanation: The indicated agent agent has encountered problems during its data collection processing, the return
code rc and reason code rsn is shown.
Operator response: Contact IBM Support.
KRN0166I id PC Routine routine installed for index index
Explanation: The indicated PC Routine routine has been installed and its index value index is shown.
Note: This message is only shown for MsgLevel(1) and above.
Operator response: No action is required.
KRN0167I id Invoking initialization routine routine
Explanation: The indicated initialization routine routine has been invoked.
Note: This message is only shown for MsgLevel(1) and above.
Operator response: No action is required.
KRN0168I id Invoking termination routine routine
Explanation: The indicated termination routine routine has been invoked.
Note: This message is only shown for MsgLevel(1) and above.
Operator response: No action is required.
KRN0176I id Dealt SMF record type number
Explanation: The SMF record number number has been intercepted by the TEDA server and successfully dealt to a
SMF record handler agent.
Note: This message is only shown for MsgLevel(1) and above.
Operator response: No action is required.
KRN0177W id Discarded SMF record type number
Explanation: The SMF record number number has been intercepted by the TEDA server but was not given to any
interested SMF record handler agent.
Note: This message is only shown for MsgLevel(1) and above.
Operator response: No action is required.
88 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
KRN0180E id No supplied parameters for statement
Explanation: During the process of reading the KppPRDxx and KppSHRxx members, the indicated statement
statement did not contain any valid parameters.
Operator response: Refer to the Monitoring Agent Planning and Configuration Guide for more information on the
keywords and expected values and formats. Correct the statement and restart the TEDA server.
KRN0181E id Maximum number of object reached
Explanation: The maximum number of items has been reached for the indicated object object. All following items of
the same type will be ignored.
Operator response: Contact IBM Support.
KRN0182E id Invalid length of keyword_or_statement
Explanation: An invalid length was detected for the indicated keyword or statement keyword_or_statement.
Operator response: Refer to the Monitoring Agent Planning and Configuration Guide for more information on the
keywords and expected values and formats. Re-specify the keyword with valid values.
KRN0183E id Non-Hexadecimal characters in keyword
Explanation: A keyword keyword was expecting only hexadecimal characters (0-9 and A-F) its value, however
non-hexadecimal characters have been detected.
Operator response: Refer to the Monitoring Agent Planning and Configuration Guide for more information on the
keywords and expected values and formats. Re-specify the keyword with valid values.
KRN0184E id Value of value greater than maximum allowed maximum
Explanation: The keyword value value is greater than the allowed maximum maximum. The value is rejected.
Operator response: Refer to the Monitoring Agent Planning and Configuration Guide for more information on the
keywords and expected values and formats. Re-specify the keyword with valid values.
KRN0185E id Value of value less than minimum allowed minimum
Explanation: The keyword value value is less than the allowed minimum minimum. The value is rejected.
Operator response: Refer to the Monitoring Agent Planning and Configuration Guide for more information on the
keywords and expected values and formats. Re-specify the keyword with valid values.
KRN0186E id Non-Numeric characters in keyword
Explanation: A keyword keyword was expecting only numerical characters (0-9) in its value, however non-numerical
characters have been detected.
Operator response: Refer to the Monitoring Agent Planning and Configuration Guide for more information on the
keywords and expected values and formats. Re-specify the keyword with valid values.
KRN0187E id Invalid time specification in keyword
Explanation: A keyword was expecting a time format value and it detected an invalid value. The time format is :
hh:mm:ss.th with all leading zeros included.
Operator response: Refer to the Monitoring Agent Planning and Configuration Guide for more information on the
keywords and expected values and formats. Re-specify the keyword with valid values.
Appendix B. Problem determination 89
KRN0188E id Invalid range specification in keyword
Explanation: The value in keyword keyword is not in a valid range as required by the keyword.
Operator response: Refer to the Monitoring Agent Planning and Configuration Guide for more information on the
keywords and expected values and formats. Re-specify the keyword with valid values.
KRN0189E id Invalid value specification in keyword
Explanation: The value in keyword keyword is invalid.
Operator response: Refer to the Monitoring Agent Planning and Configuration Guide for more information on the
keywords and expected values and formats. Re-specify the keyword with valid values.
KRN0190W id Bad statement found : Abort, Continue or Ignore (A,C,I)
Explanation: During the process of reading the KppPRDxx and KppSHRxx members, there has been an error
encountered in at least one statement.
Operator response: Examine earlier error messages to determine the reason for the failure. Refer to the Monitoring
Agent Planning and Configuration Guide for more information on the keywords and expected values and formats.
Reply with one of the following choices :
v A — Abort the server startup.
v C — Continue with startup and ignore this statement only.
v I — Continue with startup and ignore all following statement errors.
KRN0191E id Load failed for module module RC=rc RSN=rsn
Explanation: The indicated load module module could not be loaded. The return code rc and reason code rsn is
shown.
Operator response: Verify that the indicated load module can be found in either the JOBLIB or STEPLIB data sets
or the z/OS system linklist. A server restart will be required to resolve the problem.
KRN0192E id Invalid reply
Explanation: The reply to the TEDA server WTOR did not match one of the valid value. The reply will be ignored.
Operator response: Reply to the WTOR with one of the listed values.
KRN0194I id Server Abend ac RSN=rsn
Explanation: The TEDA server abended with the indicated abend code ac and reason code rsn.
Operator response: Please contact IBM Support.
KRN0195I id SMF Exit exit installed successfully
Explanation: The indicated SMF exit exit has been installed successfully.
Operator response: No action is required.
KRN0196E id CSVDYNEX DEFINE for exit failed RC=rc RSN=rsn
Explanation: During the DEFINE for the indicated SMF exit exit, the TEDA server received an unexpected return
code rc and reason code rsn.
Operator response: Please contact IBM Support.
90 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
KRN0197E id CSVDYNEX ADD for exit failed RC=rc RSN=rsn
Explanation: During the ADD for the indicated SMF exit exit, the TEDA server received an unexpected return code
rc and reason code rsn.
Operator response: Please contact IBM Support.
KRN0198E id Service service failed RC=rc RSN=rsn
Explanation: The indicated service service failed with return code rc and reason code rsn.
Operator response: Please contact IBM Support.
KRN0999I id msgtext
Explanation: This is a trace message written by the various agents when the MsgLevel is greater than 0.
Operator response: No action is required.
BegiN_ID_EnD BegiN_MESSAGE_EnD
Explanation: BegiN_EXPLANATION_EnD
Operator response: BegiN_OPERATOR_RESPONSE_EnD
BegiN_ID_EnD
Appendix B. Problem determination 91
92 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Appendix C. Accessibility
Accessibility features help users with physical disabilities, such as restricted mobility
or limited vision, to use software products successfully. The major accessibility
features in this product enable users to do the following:
v Use assistive technologies, such as screen-reader software and digital speech
synthesizer, to hear what is displayed on the screen. Consult the product
documentation of the assistive technology for details on using those technologies
with this product.
v Operate specific or equivalent features using only the keyboard.
v Magnify what is displayed on the screen.
In addition, the product documentation was modified to include the following
features to aid accessibility:
v All documentation is available in both HTML and convertible PDF formats to give
the maximum opportunity for users to apply screen-reader software.
v All images in the documentation are provided with alternative text so that users
with vision impairments can understand the contents of the images.
Navigating the interface using the keyboard
Standard shortcut and accelerator keys are used by the product and are
documented by the operating system. Refer to the documentation provided by your
operating system for more information.
Magnifying what is displayed on the screen
You can enlarge information on the product windows using facilities provided by the
operating systems on which the product is run. For example, in a Microsoft®
Windows environment, you can lower the resolution of the screen to enlarge the
font sizes of the text on the screen. Refer to the documentation provided by your
operating system for more information.
© Copyright IBM Corp. 2007 93
94 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Appendix D. Notices
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
IBM Corporation
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 writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, 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 will be
incorporated in new editions of the publication. IBM may make improvements and/or
changes in the product(s) and/or the program(s) described in this publication at any
time without notice.
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 may use or distribute any of the information you supply in any way it believes
appropriate without incurring any obligation to you.
© Copyright IBM Corp. 2007 95
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, should contact:
IBM Corporation
2Z4A/101
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.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which
illustrate programming techniques on various operating systems. You may copy,
modify, and distribute these sample programs in any form without payment to IBM,
for the purposes of developing, using, marketing or distributing application programs
conforming to the application programming interface for the operating system for
which the sample programs are written. These examples have not been thoroughly
tested under all conditions. IBM, therefore, cannot guarantee or imply reliability,
serviceability, or function of these programs. You may copy, modify, and distribute
these sample programs in any form without payment to IBM for the purposes of
developing, using, marketing, or distributing application programs conforming to
IBM’s application programming interfaces.
If you are viewing this information in softcopy form, the photographs and color
illustrations might not appear.
Trademarks
DB2®, developerWorks®, eServer™, IBM, ibm.com, IBMLink™, the IBM logo,
iSeries™, Lotus®, OS/390®, Passport Advantage®, pSeries®, Rational®, Redbooks™,
Tivoli, the Tivoli logo, Tivoli Enterprise, Tivoli Enterprise Console, WebSphere®, and
zSeries® are trademarks or registered trademarks of International Business
Machines Corporation in the United States, other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Linux is a trademark of Linus Torvalds in the United States, other countries, or both.
Microsoft, and Windows are registered trademarks of Microsoft Corporation in the
United States, other countries, or both.
96 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
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.
Appendix D. Notices 97
98 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Index
Aabend 69
accessibility xi, 93
actionsSee Take Action commands
agent, monitoringSee monitoring agent
Alias Spacesituations 34, 35
workspacesdescriptions 12
list 11
Alias Space attribute group 18
Alias Space Trend workspace 12
Alias Space workspace 12
ALIASAVLEN attribute 18
ALIASCOUNT attribute 18
ALIASROOM attribute 19, 25
ALIASTLEN attribute 19
ALLOCCAS attribute 22
ALLOCSPC attribute 26
ALLOCTYPE attribute 24
attribute (ATR) files 67
attribute groupsAlias Space 18
Cache Performance 19
Catalog Dataset Attributes 21
Catalog Summary 24
Catalog Volume Summary 26
Last Catalog Backup 27
list of all 17
more information 17
overview 17
Performance Object Status 28
attributesAlias Space 18
ALIASAVLEN 18
ALIASCOUNT 18
ALIASROOM 19, 25
ALIASTLEN 19
ALLOCCAS 22
ALLOCSPC 26
ALLOCTYPE 24
BCSNAME 18, 19, 21, 25, 27
Cache Performance 19
CACHETYPE 20, 23
Catalog Dataset Attributes 21
Catalog Summary 24
Catalog Volume Summary 26
CATLOCKED 23
CATSHARED 23
CATTYPE 20, 25
CCHDELETE 20
CCHFOUND 20
CCHPCTHIT 20
CCHPURGE 20
CCHRECORDS 19
attributes (continued)CCHSEARCH 20
CCHUPDATE 20
CICA 22
CISIZE 22
DEVCAP 26
ECS 23
Error Code 30
EXTENTS 21, 25
FRAGIDX 27
FREESPC 26
HIFREEEXT 26
Last Catalog Backup 27
LBKPNAME 27
LBKPRC 25, 28
LBKPSTMPL 25
LBKPVOLSER 27
LDIAGRC 28
LENDSTMPL 28
LENDSTMPU 28
LEXAMRC 28
LSTRTSTMPL 27
LSTRTSTMPU 28
LVFYRC 28
more information 17
Node 18, 19, 21, 24, 26, 27, 29
NUMUSEDCA 22
Object Name 29
Object Status 29
Object Type 29
overview 17
PCT4GBLIM 24
PCTFULL 27
PCTUSEDCA 22
Performance Object Status 29
PRIALLOC 24
Query Name 29
SECALLOC 24
SMS 22
STRINGS 25
Timestamp 18, 19, 21, 25, 26, 27, 29
VOLSER 18, 19, 21, 25, 26
XHARBA 22
XHURBA 21
BBasic System Services (BSS1) 60
BCSNAME attribute 18, 19, 21, 25, 27
booksfeedback x
online x
ordering x
see publications xi
browser client 51
buffers, log 65
built-in problem determination features 50
© Copyright IBM Corp. 2007 99
CCache Performance
situations 34, 35
workspacesdescriptions 12
list 11
Cache Performance attribute group 19
Cache Performance workspace 12
CACHETYPE attribute 20, 23
calculate historical data disk space 31
capacity planningIBM Tivoli Advanced Catalog Management 31
capacity planning for historical data 31
catalog (CAT) files 67
Catalog Dataset Attributessituations 34, 36
workspacesdescriptions 13
list 11
Catalog Dataset Attributes attribute group 21
Catalog Dataset Attributes workspace 13
Catalog Details workspace 13, 14
Catalog Summarysituations 34, 37
workspacesdescriptions 13
list 11
Catalog Summary attribute group 24
Catalog Summary workspace 13
Catalog Volume Details workspace 14
Catalog Volume Summarysituations 34, 37
workspacesdescriptions 14
list 12
Catalog Volume Summary attribute group 26
Catalog Volume Summary workspace 14
CATLOCKED attribute 23
CATSHARED attribute 23
CATTYPE attribute 20, 25
CCHDELETE attribute 20
CCHFOUND attribute 20
CCHPCTHIT attribute 20
CCHPURGE attribute 20
CCHRECORDS attribute 19
CCHSEARCH attribute 20
CCHUPDATE attribute 20
CICA attribute 22
CISIZE attribute 22
code, productSee product code
collecting data 9
commandsECHO 65
RAS1 60
service console 60
TLVLOG 63
commands, Take Action 41
communication failure 68
communication tracing 56, 61
component codeSee product code
components 2
configuration 3
Configuration Toolsetting trace levels 60, 61, 62
conventionsoperating system xiii
typeface xii
cross-product links 70
customer supportSee Software Support
customizingmonitoring environment 7
situations 8
Ddata
collecting 9
viewing 9
data loggedIBM Tivoli Advanced Catalog Management 31
debuggingcommunication 56, 68
default port 69
historical data collection 69
debugging toolsLog and Trace Analyzer 67
detecting problems, modifying situation values 8
DEVCAP attribute 26
directory names, notation xiii
disk capacity planningSee capacity planning
disk capacity planning for historical data 31
dynamic workspace links 70
EECHO command 65
ECS attribute 23
education 74
see Tivoli technical training xii
environmentcustomizing 7
features 1
functions 1
monitoring real-time 5
real-time monitoring 5
environment variables, notation xiii
Error Code attribute 30
eventmapping 45
eventsinvestigating 6
workspaces 6
EXTENTS attribute 21, 25
100 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
Ffeatures, IBM Tivoli Advanced Catalog Management 1
files, catalog and attribute 67
fixes, obtaining 75
FRAGIDX attribute 27
FREESPC attribute 26
functions, IBM Tivoli Advanced Catalog Management 1
Ggathering support information 49
HHIFREEEXT attribute 26
historical datacalculate disk space 31
capacity planningIBM Tivoli Advanced Catalog Management 31
disk capacity planning 31
historical data collectioninstallation and configuration problems 69
historical data, collecting and viewing 9
IIBM Redbooks 74
IBM Software SupportSee support
IBM Support Assistant 74
IBM Tivoli Advanced Catalog Managementabend 69
components 2
features 1
functions 1
log filesRKLVLOG 54
RKLVSNAP 54
RKPDLOG 54
product code 55
situations 34, 35
termination, abnormal 69
trace levels 62
workspacesdescriptions 12
list 11
IBM Tivoli Advanced Catalog Management
workspace 12
IBM Tivoli Enterprise Consoleevent mapping 45
informationproblem determination 49
information, additionalattributes 17
policies 43
procedural 5
situations 33
Take Action commands 41
workspaces 11
installationmore information 5
problems 67
installation and configuration problemshistorical data collection 69
monitoring agent 68
monitoring server 68
remote monitoring server 68
interface, user 2
investigating an event 6
IP address 68
ITMS:Enginedefined 55
initialization message 55
product code 55
RKLVLOG 55
KKBB library service 56
KBBENV file 49
KDC_DEBUG environment variable 56
KDE_TRANSPORT statement 68
KDEB_INTERFACELIST statement 68
KDSENV member 49, 56, 68
KDSSTART member 61, 62
KFWITM081E message 70
KFWITM217E 68
KRN_KRN_Alias_Remain_Critical situation 35
KRN_KRN_Cat_4GB_Limit_Critical situation 36
KRN_KRN_Cat_Backup_Critical situation 38
KRN_KRN_Cat_Backup_Warning situation 38
KRN_KRN_Cat_Extents_Critical situation 36
KRN_KRN_Cat_Hit_Pct_Warning situation 35
KRN_KRN_Vol_Frag_Idx_Critical situation 37
KRN_KRN_Vol_Pct_Full_Critical situation 37
KRNENV member 56, 68
LLast Catalog Backup
situations 34, 38
workspacesdescriptions 15
list 12
Last Catalog Backup attribute group 27
Last Catalog Backup workspace 15
LBKPNAME attribute 27
LBKPRC attribute 25, 28
LBKPSTMPL attribute 25
LBKPVOLSER attribute 27
LDIAGRC attribute 28
legal notices 95
LENDSTMPL attribute 28
LENDSTMPU attribute 28
LEXAMRC attribute 28
links, workspace 70
list of messages 79
Log and Trace Analyzer tool 67
log buffers 65
Index 101
log filesIBM Tivoli Advanced Catalog Management 54
monitoring agent 54
monitoring serverdistributed 52
z/OS 54
persistent data store 54, 55
portal client 51
portal server 52
RKLVLOG 54
RKLVSNAP 54
RKPDLOG 54, 55
Tivoli Enterprise Monitoring Serverdistributed 52
z/OS 54
Tivoli Enterprise Portal client 51
Tivoli Enterprise Portal Server 52
WAREHOUSELOG table 55
logged dataIBM Tivoli Advanced Catalog Management 31
loggingbuilt-in features 50
storage 61
write-to-operator (WTO) messages 62
LSTRTSTMPL attribute 27
LSTRTSTMPU attribute 28
LVFYRC attribute 28
MManage Tivoli Monitoring Services 52, 53
manualsfeedback x
online x
ordering x
see publications xi
messagesbuilt-in features 50
for IBM Tivoli Advanced Catalog Management 79
format 66, 78
ITMS:Engine 55
KFWITM081E 70
overview 78
syntax 78
U200 69
write-to-operator (WTO) 62
messages, displayingmonitoring server 53
portal server 52
Tivoli Enterprise Monitoring Server 53
Tivoli Enterprise Portal Server 52
missing data 68
modifying situation values to detect problems 8
monitoring agent 54
abend 69
communication failure 68
installation and configuration problems 68
log filesRKLVLOG 54
RKLVSNAP 54
RKPDLOG 54
monitoring agent (continued)product code 55
termination, abnormal 69
trace levels 62
using 5
monitoring servercommunication failure 68
displaying messages 53
installation and configuration problems 68
log filesdistributed 52
RKLVLOG 54
RKLVSNAP 54
z/OS 54
product code 55
remote 68
trace levels 61
monitoring, viewing the real-time environment 5
multi-home environment 68
NNode attribute 18, 19, 21, 24, 26, 27, 29
notationenvironment variables xiii
path names xiii
typeface xiii
NUMUSEDCA attribute 22
OObject Name attribute 29
Object Status attribute 29
Object Type attribute 29
online publicationsaccessing xi
operation of resource, recovering 6
ordering publications xi
Ppatch levels 49
path names, notation xiii
PCT4GBLIM attribute 24
PCTFULL attribute 27
PCTUSEDCA attribute 22
Performance Object Status attribute group 28
persistent data storelog files 54, 55
policiesmore information 43
overview 43
portal clientirreproducible problems 53
log files 51
reproducible problems 51
portal serverdisplaying messages 52
irreproducible problems 54
log files 52
ports, communication 69
102 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
PRIALLOC attribute 24
problem determination 49, 67
built-in features 50
communication 56
communication failure 68
data to collect 49
default port 69
describing problems 77
determining business impact 77
historical data collection 69
installation 67
messages 78
situations 71
submitting problems 77
uninstallation 67
workspaces 70
problem resolution 74
problemsdetecting 8
problems and workarounds 67
procedures 5
product code 55
IBM Tivoli Advanced Catalog Management 55
ITMS:Engine 55
monitoring agent 55
monitoring server 55
Tivoli Enterprise Monitoring Server 55
proxy, warehouse 55
publicationsaccessing online xi
feedback x
online x
ordering x, xi
purposescollecting data 9
customizing monitoring environment 7
investigating events 6
monitoring with custom situations 8
problem determination 49
recovering resource operation 6
viewing data 9
viewing real-time monitoring environment 5
Qqueries, using attributes 17
Query Name attribute 29
RRAS1 command 60
RAS1 tracesdefined 50
KBB library service 56
levels 58, 59, 60, 61, 62
message format 66
overhead 55
syntax 57
unit 58
z/OS 55
real-time data, viewing 5
recovering the operation of a resource 6
Redbooks, IBM 74
requirements 3
resource, recovering operation 6
RKANCMDU data set 61, 62
RKANDATV data set 68
RKANPARU data set 49, 56, 58, 68
RKLVLOG 69
closing 63
ending 63
ITMS:Engine 55
monitoring agent 54
monitoring server 54
opening 63
printing to data set 63
saving 62
starting 63
RKLVSNAP 54
RKPDLOG 54, 55
SSampleAction action 42
SDSF Print to Data Set panel 63
SECALLOC attribute 24
service consolecommands 60
defined 59
starting 59
situationsKRN_KRN_Alias_Remain_Critical 35
KRN_KRN_Cat_4GB_Limit_Critical 36
KRN_KRN_Cat_Backup_Critical 38
KRN_KRN_Cat_Backup_Warning 38
KRN_KRN_Cat_Extents_Critical 36
KRN_KRN_Cat_Hit_Pct_Warning 35
KRN_KRN_Vol_Frag_Idx_Critical 37
KRN_KRN_Vol_Pct_Full_Critical 37
list of all 34
more information 33
overview 33
predefined 34
values, modifying 8
situations, using attributes 17
SMS attribute 22
software support 74
Software Supportcontacting 76
describing problems 77
determining business impact 77
receiving weekly updates 75
submitting problems 77
storage logging 61
STRINGS attribute 25
supportgathering information for 49
IBM Support Assistant 74
list of messages 79
messages 78
Support Assistant 74
Index 103
syntaxmessages 78
syntax, RAS1 traces 57
TTake Action commands 6
list of all 41
more information 41
overview 41
predefined 41
SampleAction 42
TCP/IP profile 69
termination, abnormal 69
Timestamp attribute 18, 19, 21, 25, 26, 27, 29
Tivoli Data Warehousedebugging 55
WAREHOUSELOG table 55
Tivoli Enterprise Monitoring Servercommunication failure 68
displaying messages 53
installation and configuration problems 68
log filesdistributed 52
RKLVLOG 54
RKLVSNAP 54
z/OS 54
product code 55
remote 68
trace levels 61
Tivoli Enterprise Portal clientirreproducible problems 53
log files 51
reproducible problems 51
Tivoli Enterprise Portal Serverdisplaying messages 52
irreproducible problems 54
log files 52
Tivoli software information center xi
Tivoli technical training xii
TLVLOG command 63
tools, debuggingLog and Trace Analyzer 67
tracingchanging settings 52, 53
communication 56, 61
defined 50
enabling in browser 51
KBB library service 56
levels 50, 55, 58, 59, 60, 61, 62
message format 66
monitoring agent 62
monitoring server 61, 62
overhead 55
RAS1 50, 55
syntax 57
Tivoli Enterprise Monitoring Server 61
unit 58
z/OS 55
trademarks 96
training, Tivoli technical xii
troubleshooting 49
typeface conventions xii
UU200 message 69
unit traces 58
user interfaces options 2
using a monitoring agentpurposes 5
Vvalues, modifying situations 8
variables, notation for xiii
version numbers 49
viewing data 9
viewing real-time monitoring environment 5
viewsAlias Space Trend workspace 12
Alias Space workspace 12
Cache Performance workspace 12
Catalog Dataset Attributes workspace 13
Catalog Details workspace 13, 14
Catalog Summary workspace 13
Catalog Volume Details workspace 14
Catalog Volume Summary workspace 14
IBM Tivoli Advanced Catalog Management
workspace 12
Last Catalog Backup workspace 15
Virtual Internet Protocol Addressing (VIPA) 68
VOLSER attribute 18, 19, 21, 25, 26
VSAM buffers 61, 62
Wwarehouse proxy 55
WAREHOUSELOG table 55
Windows Event Viewer 52, 53
workarounds 67
situations 71
workspaces 70
workspaces_EnDNAVIGATOR_ITEM_EnD 12, 13, 14, 15
Alias Space 12
Alias Space Trend 12
Cache Performance 12
Catalog Dataset Attributes 13
Catalog Details 13, 14
Catalog Summary 13
Catalog Volume Details 14
Catalog Volume Summary 14
event 6
IBM Tivoli Advanced Catalog Management 12
inconsistent information 70
Last Catalog Backup 15
links 70
list of all 11
more information 11
no rows in a table 70
overview 11
104 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
workspaces (continued)predefined 11
problem determination 70
write-to-operator (WTO) messages 62
XXHARBA attribute 22
XHURBA attribute 21
Index 105
106 IBM Tivoli Advanced Catalog Management for z/OS: Monitoring Agent User’s Guide
����
Printed in USA
SC23-7974-00