IBM Z OMEGAMON for CICS

5.6.0

Planning and Configuration Guide

IBM
 Note
Before using this information and the product it supports, read the information in “Notices” on page
353.

Notices
This edition applies to Version 5, Release 6 of IBM® Tivoli® OMEGAMON® XE for CICS on z/OS (program number 5698-
T07) and to all subsequent releases and modifications until otherwise indicated in new editions.
© Copyright International Business Machines Corporation 2004, 2022.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with
IBM Corp.
Contents

Figures................................................................................................................ vii

Tables.................................................................................................................. ix

Chapter 1. Introducing IBM Z OMEGAMON for CICS................................................ 1

OMEGAMON infrastructure: Tivoli Management Services ......................................................................... 2
OMEGAMON XE shared components ......................................................................................................... 3
OMEGAMON enhanced 3270 user interface......................................................................................... 7
IBM Z OMEGAMON for CICS component.................................................................................................... 8
IBM Z OMEGAMON for CICS component.................................................................................................... 8
OMEGAMON for CICS TG on z/OS component............................................................................................ 9
Interoperability with other products........................................................................................................... 9

Chapter 2. Planning your configuration.................................................................11

Configuration prerequisites....................................................................................................................... 11
PTFs required for using embedded OMEGAMON for Storage data retrieved with DFSMS......................11
Configuring components ...........................................................................................................................12
Determining the products and components to configure................................................................... 12
Planning configuration of OMEGAMON for CICS (3270).......................................................................... 14
Planning configuration of IBM Z OMEGAMON for CICS............................................................................ 15
Planning configuration of IBM Z OMEGAMON for CICS TG on z/OS.........................................................16

Chapter 3. Upgrading to the new release.............................................................. 17

Enabling new features............................................................................................................................... 17
Enabling the self-describing agent............................................................................................................17
Performing a staged upgrade.................................................................................................................... 18
OMEGAMON for CICS (3270) upgrade considerations.............................................................................19
IBM Z OMEGAMON for CICS considerations.............................................................................................22
IBM Z OMEGAMON for CICS TG considerations....................................................................................... 23

Chapter 4. Configuring IBM Z OMEGAMON for CICS.............................................. 25

Configuration roadmap.............................................................................................................................. 25
Configuring IBM Z OMEGAMON for CICS using the PARMGEN method...................................................26
Configuring the OMEGAMON for CICS (3270) component................................................................. 28
Configuring the IBM Z OMEGAMON for CICS monitoring agent......................................................... 30
Configuring the IBM Z OMEGAMON for CICS TG component using the PARMGEN method................... 31
Completing the configuration.................................................................................................................... 32
Copying started task procedures and VTAM definitions to your procedure library and VTAMLST
system............................................................................................................................................. 33
Varying the VTAM major node active................................................................................................... 34
Granting APF authorization for the runtime load libraries.................................................................. 34
Completing the configuration for OMEGAMON for CICS..................................................................... 34
Completing the configuration for OMEGAMON for CICS TG............................................................... 43
Completing the configuration for IBM Z OMEGAMON for CICS TG.....................................................43
Verifying the configuration................................................................................................................... 49
Verifying self-describing agent enablement........................................................................................53
Enabling security.................................................................................................................................. 54
Installing language support................................................................................................................. 54
Reporting on groups of CICS Regions: CICSplexes...................................................................................54

iii
 Accessing the CICSplex Rules and Agent Preferences panel............................................................. 55
Creating complex CICSplex classification rule definitions using wild card characters .....................63
Controlling application trace using the enhanced 3270 user interface................................................... 64
Specifying repeating trace in the Global Data Area.................................................................................. 66
Configuring Service Level Analysis definitions using the Tivoli Enterprise Portal................................... 66
Accessing the CICS SLA view...............................................................................................................67
Configuring Service Level Analysis definitions using the enhanced 3270 user interface....................... 74
Accessing the Service Level Configuration panel................................................................................ 75
Viewing the Service Level Configuration panel....................................................................................75
Using the Service Classes of DFLTSPOL subpanel.............................................................................. 76
Using the Service Class tabbed panel..................................................................................................78
Using the Service Policy tabbed panel.................................................................................................80
Using the Workload tabbed panel........................................................................................................81
Using the SLA Options tabbed panel................................................................................................... 82
Configuring Service Level Analysis definitions using the batch utility..................................................... 82
Accessing the batch utility................................................................................................................... 82

Chapter 5. Reference........................................................................................... 95
Enabling security for OMEGAMON XE and OMEGAMON for CICS............................................................ 95
Securing OMEGAMON for CICS on z/OS Take Action commands....................................................... 95
Resource names used for Take Action commands by the agent........................................................ 95
Adding the NetView CNMLINK library to the Tivoli Enterprise Monitoring Server or agent
started task......................................................................................................................................98
Securing the OMEGAMON for CICS (3270)......................................................................................... 99
Modifying the security table.............................................................................................................. 108
Optional external security features................................................................................................... 117
Customizing profiles and security......................................................................................................118
Configuring historical data tables........................................................................................................... 121
Historical data collection................................................................................................................... 121
Enabling historical data collection in the enhanced 3270UI............................................................122
Enabling historical data collection in the Tivoli Enterprise Portal.................................................... 122
Determining PDS sizes for near-term history collection................................................................... 122
Configuring task history data...................................................................................................................126
Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas.....................127
Overview of the Global Data Area......................................................................................................127
Determining the values for the monitoring options in IBM Z OMEGAMON for CICS........................128
Refreshing the monitoring options.................................................................................................... 164
Additional Considerations..................................................................................................................164
SAS historical reporting........................................................................................................................... 166
Using the SAS historical reporter.......................................................................................................166
Overview of the SAS historical reporting process............................................................................. 167
Preparing to run the sample SAS reports.......................................................................................... 167
Installation procedures......................................................................................................................168
Customization procedures................................................................................................................. 168
Running the daily collection jobs....................................................................................................... 169
Producing reports from the SAS DETAIL data set............................................................................. 173
Producing reports from the SAS DAILY data set............................................................................... 178
Producing reports through the Generalized Report Writer............................................................... 182
Building response time transaction groups.......................................................................................186
OMEGAMON for CICS optional features................................................................................................. 190
Enabling monitoring for user-defined events....................................................................................190
System Management Facility considerations....................................................................................193
Installing third-party support............................................................................................................ 196
Umbrella transaction services........................................................................................................... 202
OMEGAMON for CICS (3270) address space.................................................................................... 206
Virtual terminal pool considerations................................................................................................. 214
Interfacing with other products for transaction tracking support.................................................... 217

iv
 Default DD Names................................................................................................................................... 218
Standard DD names for the OMEGAMON for CICS (3270) address space.......................................218

Appendix A. Enabling security for OMEGAMON XE and OMEGAMON for CICS.......221

Securing OMEGAMON for CICS on z/OS Take Action commands.......................................................... 221
Resource names used for Take Action commands by the agent............................................................221
Adding the NetView CNMLINK library to the Tivoli Enterprise Monitoring Server or agent started
task......................................................................................................................................................224
Securing the OMEGAMON for CICS (3270).............................................................................................224
Modifying the security table.................................................................................................................... 234
Optional external security features.........................................................................................................243
Customizing profiles and security........................................................................................................... 244
The System Management Facilities audit..........................................................................................246

Appendix B. Configuring historical data tables....................................................249

Historical data collection.........................................................................................................................249
Enabling historical data collection in the enhanced 3270UI................................................................. 250
Enabling historical data collection in the Tivoli Enterprise Portal..........................................................250
Determining PDS sizes for near-term history collection........................................................................ 250
Sample PDS estimates for OMEGAMON for CICS on z/OS................................................................251
Sample PDS estimates for OMEGAMON for CICS TG on z/OS.......................................................... 253

Appendix C. Configuring task history data.......................................................... 255

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270)
Global Data Areas.......................................................................................... 257
Overview of the Global Data Area........................................................................................................... 257
Determining the values for the monitoring options in IBM Z OMEGAMON for CICS............................. 258
Refreshing the monitoring options..........................................................................................................294
Additional Considerations....................................................................................................................... 294

Appendix E. SAS historical reporting.................................................................. 297

Using the SAS historical reporter............................................................................................................ 297
Overview of the SAS historical reporting process...................................................................................297
Preparing to run the sample SAS reports................................................................................................298
Installation procedures........................................................................................................................... 298
Customization procedures...................................................................................................................... 299
Running the daily collection jobs............................................................................................................ 300
Producing reports from the SAS DETAIL data set...................................................................................303
Producing reports from the SAS DAILY data set.....................................................................................309
Producing reports through the Generalized Report Writer.....................................................................313
Building response time transaction groups............................................................................................ 317

Appendix F. OMEGAMON for CICS optional features............................................321

Enabling monitoring for user-defined events......................................................................................... 321
Background about monitoring for user-defined events.................................................................... 321
The process for monitoring for a user-defined event .......................................................................321
System Management Facility considerations......................................................................................... 324
System Management Facility record type......................................................................................... 324
Record layout..................................................................................................................................... 324
Interval records..................................................................................................................................325
System records...................................................................................................................................325
File and database records..................................................................................................................326
Transaction records........................................................................................................................... 327
Dictionary records.............................................................................................................................. 327
Installing third-party support..................................................................................................................327

v
 Installing ADABAS support................................................................................................................ 328
Installing CA-DATACOM and CA-IDEAL support............................................................................... 328
Installing GENER/OL support............................................................................................................ 329
Installing IDMS support..................................................................................................................... 330
Installing Millennium support............................................................................................................331
Installing NATURAL support.............................................................................................................. 331
Installing PCS support....................................................................................................................... 332
Installing SUPRA support.................................................................................................................. 332
Installing UFO/Forms support........................................................................................................... 333
Umbrella transaction services.................................................................................................................333
Using subroutines.............................................................................................................................. 333
Subroutine call syntax and parameters.............................................................................................334
Using umbrella services for Web service details...............................................................................336
OMEGAMON for CICS (3270) address space..........................................................................................337
OMEGAMON for CICS (3270) operation............................................................................................ 338
OMEGAMON for CICS (3270) interface commands.......................................................................... 338
Installing multiple OMEGAMON address space pairs.......................................................................345
Virtual terminal pool considerations.......................................................................................................346
Modifying the default virtual terminal pool definition.......................................................................346
Sharing virtual terminal pool definitions........................................................................................... 346
Interfacing with other products for transaction tracking support......................................................... 348
Starting ITCAM for CICS in a CICS region..........................................................................................348
Using OMEGAMON for CICS to start or stop ITCAM for CICS in a specific region............................349

Appendix G. Default DD Names.......................................................................... 351

Standard DD names for the OMEGAMON for CICS (3270) address space............................................ 351

Notices..............................................................................................................353
Privacy policy considerations ................................................................................................................. 354
Trademarks.............................................................................................................................................. 355

Index................................................................................................................ 357

vi
Figures

1. Tivoli Management Services..........................................................................................................................3

2. The OMEGAMON enhanced 3270 user interface is a base component of the OMEGAMON for CICS
on z/OS product............................................................................................................................................7

3. MCT additions for installation..................................................................................................................... 39

4. CICSplex Rules and Agent Preferences panel............................................................................................55

5. Add a new CICSplex Classification Rule panel...........................................................................................58

6. xxxxxxxx CICSplex Agent Preferences (KCPPLXAA) panel........................................................................ 58

7. The Delete this CICSplex Classification Rule panel................................................................................... 60

8. Add Preferences for a CICSplex Agent panel............................................................................................. 61

9. Update this CICSplex Agent's Preferences panel ..................................................................................... 62

10. Delete this CICSplex Agent's Preferences panel .................................................................................... 63

11. CICSplex Classification Rule Definitions panel example of wild card characters (1 of 2)...................... 64

12. CICSplex Classification Rule Definitions panel example of wild card characters (2 of 2)...................... 64

13. Service Level Configuration panel............................................................................................................ 75

14. Example of the JCL you enter to specify the DETAIL and DAILY reports.............................................. 171

15. Example of the JCL to use when you want to add report statements to the SYSIN DD statement..... 173

16. Example of a JCL to enter to specify the DETAIL and DAILY reports.................................................... 177

17. List of Requests for the KOCRMCLL subroutine..................................................................................... 204

18. A request for information about Web Services Name and Operation from CICS................................. 205

19. Issue Collector Command Menu Panel.................................................................................................. 207

20. DISPLAY Command Output.................................................................................................................... 208

21. HELP Command Output.......................................................................................................................... 210

22. HSAA VTAM Definition Statements........................................................................................................ 216

vii
 23. HSAB VTAM Definition Statements........................................................................................................ 216

24. The OMEGAMON for CICS (3270) interface provides the capability to dynamically enable or
disable ITCAM for CICS in a specific region............................................................................................ 218

25. Example of the JCL you enter to specify the DETAIL and DAILY reports.............................................. 302

26. Example of the JCL to use when you want to add report statements to the SYSIN DD statement..... 303

27. Example of a JCL to enter to specify the DETAIL and DAILY reports.................................................... 308

28. List of Requests for the KOCRMCLL subroutine..................................................................................... 335

29. A request for information about Web Services Name and Operation from CICS................................. 336

30. Issue Collector Command Menu Panel.................................................................................................. 338

31. DISPLAY Command Output.................................................................................................................... 339

32. HELP Command Output.......................................................................................................................... 341

33. HSAA VTAM Definition Statements........................................................................................................ 347

34. HSAB VTAM Definition Statements........................................................................................................ 348

35. The OMEGAMON for CICS (3270) interface provides the capability to dynamically enable or
disable ITCAM for CICS in a specific region............................................................................................ 349

viii
Tables

1. OMEGAMON for CICS product components................................................................................................. 4

2. Determining the required products or components, location of information, and whether they can
be shared....................................................................................................................................................12

3. Storage Required in CSA and ECSA............................................................................................................ 15

4. Storage Required in CICS............................................................................................................................15

5. Elements to upgrade from versions of OMEGAMON for CICS................................................................... 21

6. Historical reporting considerations for OMEGAMON for CICS (3270).......................................................22

7. Tasks to complete before configuring IBM Z OMEGAMON for CICS..........................................................26

8. Steps to complete the configuration.......................................................................................................... 32

9. Post-configuration steps............................................................................................................................. 33

10. Parameters that can be passed on the INITPARM.................................................................................. 35

11. Properties for defining com.ibm.omegamon.kgw.rmexit.sweepTimeout and

com.ibm.omegamon.kgw.rmexit.sweepInterval...................................................................................... 48

12. kcp_slabatch utility commands................................................................................................................ 83

13. Tags for the Workload element and their values......................................................................................88

14. The ServiceClass element and their values............................................................................................. 89

15. The ServicePolicy element and their values............................................................................................ 90

16. Values for the Workload element in a XML document............................................................................. 91

17. Values for the ServiceClass element in a XML document........................................................................92

18. Values for the Service Policy element in a XML document...................................................................... 92

19. Values for the Override Goal element in a XML document...................................................................... 93

20. Return codes for the kcp_slabatch utility.................................................................................................94

21. The naming conventions for the user exit module called by OMEGAMON for CICS (3270).................107

22. Available control statements for updating the security table............................................................... 108

ix
 23. Explaining control statement settings....................................................................................................115

24. TYPE specifies these commands............................................................................................................117

25. Total DASD Space estimates for a varied number of CICS regions....................................................... 123

26. OMEGAMON for CICS on z/OS near-term history tables....................................................................... 124

27. Total DASD Space estimates for a varied number of CICS TG address spaces.................................... 125

28. OMEGAMON for CICS TG on z/OS near-term history tables..................................................................126

29. Global options information..................................................................................................................... 129

30. Startup controls information.................................................................................................................. 131

31. Exception analysis intervals information............................................................................................... 139

32. Database collection values information.................................................................................................140

33. Additional database collection options available when USREVNT1 is specified..................................141

34. Program Tracking information................................................................................................................ 141

35. Bottleneck options information..............................................................................................................142

36. User excluded transactions.................................................................................................................... 144

37. User event monitoring information........................................................................................................ 145

38. CPU monitoring information................................................................................................................... 148

39. Group Definitions information................................................................................................................ 148

40. Group Elements information.................................................................................................................. 149

41. Interval Collector information................................................................................................................ 151

42. Online Viewer information...................................................................................................................... 152

43. Resource Limiting Parameters............................................................................................................... 155

44. Resource limiting interval information................................................................................................... 160

45. Response time collection information................................................................................................... 160

46. Dedicated sessions information............................................................................................................. 162

47. Service level analysis information.......................................................................................................... 163

x
48. Outbound API Request Monitoring ........................................................................................................163

49. TRUE Monitoring information................................................................................................................. 163

50. OMEG INIT processing scenarios...........................................................................................................165

51. Settings Before Initialization.................................................................................................................. 165

52. After OMEG INIT..................................................................................................................................... 166

53. After CEMT SET MONITOR PERF ON......................................................................................................166

54. Steps in the SAS historical reporting process........................................................................................ 167

55. Parameters available for USREVNT1......................................................................................................191

56. Data set and member purpose for event monitoring sample code.......................................................191

57. Where to specify the call to the subroutine for monitoring user-defined events................................. 192

58. Location of file or database sample record layouts............................................................................... 195

59. Suffix for Transaction Server by version.................................................................................................198

60. START options for OMEGAMON for CICS (3270) and OBVTAM............................................................. 212

61. The naming conventions for the user exit module called by OMEGAMON for CICS (3270).................232

62. Available control statements for updating the security table............................................................... 234

63. Explaining control statement settings....................................................................................................240

64. TYPE specifies these commands............................................................................................................243

65. Total DASD Space estimates for a varied number of CICS regions....................................................... 251

66. OMEGAMON for CICS on z/OS near-term history tables....................................................................... 252

67. Total DASD Space estimates for a varied number of CICS TG address spaces.................................... 253

68. OMEGAMON for CICS TG on z/OS near-term history tables..................................................................254

69. Global options information..................................................................................................................... 259

70. Startup controls information.................................................................................................................. 261

71. Exception analysis intervals information............................................................................................... 269

72. Database collection values information.................................................................................................270

xi
 73. Additional database collection options available when USREVNT1 is specified..................................271

74. Program Tracking information................................................................................................................ 271

75. Bottleneck options information..............................................................................................................272

76. User excluded transactions.................................................................................................................... 274

77. User event monitoring information........................................................................................................ 275

78. CPU monitoring information................................................................................................................... 278

79. Group Definitions information................................................................................................................ 278

80. Group Elements information.................................................................................................................. 279

81. Interval Collector information................................................................................................................ 281

82. Online Viewer information...................................................................................................................... 282

83. Resource Limiting Parameters............................................................................................................... 285

84. Resource limiting interval information................................................................................................... 290

85. Response time collection information................................................................................................... 290

86. Dedicated sessions information............................................................................................................. 292

87. Service level analysis information.......................................................................................................... 293

88. Outbound API Request Monitoring ........................................................................................................293

89. TRUE Monitoring information................................................................................................................. 293

90. OMEG INIT processing scenarios...........................................................................................................295

91. Settings Before Initialization.................................................................................................................. 295

92. After OMEG INIT..................................................................................................................................... 296

93. After CEMT SET MONITOR PERF ON......................................................................................................296

94. Steps in the SAS historical reporting process........................................................................................ 297

95. Parameters available for USREVNT1......................................................................................................321

96. Data set and member purpose for event monitoring sample code.......................................................322

97. Where to specify the call to the subroutine for monitoring user-defined events................................. 323

xii
98. Location of file or database sample record layouts............................................................................... 326

99. Suffix for Transaction Server by version.................................................................................................329

100. START options for OMEGAMON for CICS (3270) and OBVTAM...........................................................343

xiii
xiv
Chapter 1. Introducing IBM Z OMEGAMON for CICS
IBM Z OMEGAMON for CICS is a member of the latest generation of the OMEGAMON family of mainframe
monitoring products.
IBM Z OMEGAMON for CICS helps you proactively manage performance and availability of CICS®
Transaction Server and CICS Transaction Gateway systems from an integrated interface in order to
understand how resources are used and how system performance affects users.
IBM Z OMEGAMON for CICS helps you clearly see and understand application and system events. You
can monitor and manage CICS transactions and CICS TG transaction level activities, at the big picture
and granular levels and interact with other applications, within a single interface. OMEGAMON for CICS on
z/OS® is designed to enable you to detect problems quickly and take action in real time to speed up your
problem resolution.
The data collected by the monitoring agents and the alerts that are triggered by monitored conditions are
displayed in a graphical, Java-based interface, shared with other OMEGAMON and IBM Tivoli Monitoring
products. The enhanced 3270UI enables summarization of data at the CICSplex reporting level and also
provides access to CICS TG information.
When used in conjunction with other OMEGAMON XE monitoring products, the data, analyses, and alerts
presented by IBM Z OMEGAMON for CICS help you develop a holistic view of your entire computing
enterprise from a single console.
IBM Z OMEGAMON for CICS contains these five configured z/OS system components:
• Tivoli Enterprise Monitoring Server
• OMEGAMON enhanced 3270 user interface
• IBM Z OMEGAMON for CICS monitoring agent
• IBM Z OMEGAMON for CICS TG on z/OS monitoring agent
This guide describes the planning and configuration information for the IBM Z OMEGAMON for CICS and
IBM Z OMEGAMON for CICS TG monitoring components. Planning and configuring information for the
Tivoli Enterprise Monitoring Server, as well as the OMEGAMON enhanced 3270 user interface is available
in the OMEGAMON shared documentation.
OMEGAMON infrastructure management solutions help you achieve a true on-demand computing
environment. These products can help you meet the demands of increasing data center volume,
complexity, and volatility by giving your information technology team the tools to quickly identify, isolate,
and fix any issues before they impact your customers.
The OMEGAMON XE System z® suite of products includes solutions for z/OS-based database products,
applications, for example, CICS and CICS TG, storage, and networks. OMEGAMON XE System z monitoring
agents are available for the following products:
• IBM Z OMEGAMON for CICS
• IBM OMEGAMON for DB2 Performance Monitor/Expert on z/OS
• IBM OMEGAMON for IMS on z/OS
• IBM OMEGAMON for Mainframe Networks on z/OS
• IBM OMEGAMON for Storage on z/OS
• IBM OMEGAMON for Messaging
• IBM OMEGAMON for z/OS
• IBM OMEGAMON for zVM/Linux

© Copyright IBM Corp. 2004, 2022 1

OMEGAMON infrastructure: Tivoli Management Services
IBM Z OMEGAMON for CICS uses the Tivoli Management Services infrastructure.
This infrastructure provides security, data transfer and storage, notification mechanisms, user interfaces,
and communication for products in the IBM Tivoli Monitoring and IBM OMEGAMON suites.
Tivoli Management Services includes the following components:
• Tivoli Enterprise Portal
• Tivoli Enterprise Monitoring Server
• Tivoli Data Warehouse and the warehouse proxy
• Tivoli Management Services: Engine (TMS:Engine, TMS:Persistent Data Store)
• OMEGAMON monitoring agents
It's important to understand the components of Tivoli Management Services and how they work
together with the OMEGAMON products. The OMEGAMON shared documentation has an overview of
the components of Tivoli Management Services.
A Tivoli Enterprise Monitoring Server (TEMS) acts as a collection and control point for alerts received
from the monitoring agents, and collects performance and availability data. The Hub TEMS correlates the
monitoring data collected by agents and remote servers and passes it to the TEPS for presentation and
evaluation.
For more information on what a TEMS does, see Tivoli Enterprise Monitoring Server in the OMEGAMON
shared documentation.
OMEGAMON monitoring agents are located on monitored or managed systems. The agents collect data
and pass it along to a Tivoli Enterprise Monitoring Server. From there, the data are displayed in a Tivoli
Enterprise Portal client or in the enhanced 3270 user interface.
Monitoring agents can compare the current values of monitored properties against a set of defined
conditions (situations) and trigger alerts or actions when these conditions are met, to alert you to
potential performance issues. The agents can execute actions relayed to them from the Tivoli Enterprise
Portal and enhanced 3270 user interface clients by the Hub TEMS.
Note that each IBM Z OMEGAMON for CICS monitoring agent needs to establish a connection to the Hub
TEMS, using the defined protocols. The agent needs this connection to retrieve configuration information
as well as to be able to request data for other agents for CICSplex-wide data collection.
For more information on OMEGAMON monitoring agents, see Monitoring agents in the shared
documentation. For more information on connecting agents to the Hub TEMS, see How to: Connect agents
on local RTE and agents on remote RTEs to the Hub TEMS, also in the shared documentation.
This illustration shows the components of the Tivoli Management Services infrastructure:

2 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 Figure 1. Tivoli Management Services

Not all components are required for IBM Z OMEGAMON for CICS. For example, you do not have to have
Tivoli Enterprise Portal or Tivoli Data Warehouse installed in your environment to run OMEGAMON for
CICS on z/OS.
Some components of Tivoli Management Services, such as Tivoli Enterprise Portal and the Warehouse
Proxy and Summarization and Pruning agents, run on distributed systems (Windows or UNIX). The Tivoli
Enterprise Monitoring Server and the Tivoli Data Warehouse can run on either distributed or mainframe
systems. The Tivoli Management Services: Engine and Persistent Data Store run only on mainframe
systems.

OMEGAMON XE shared components

OMEGAMON XE monitoring agents on a z/OS system share several components (referred to as common
components).
These components, along with the monitoring agent software and the PARMGEN configuration tool, are
distributed on the OMEGAMON for CICS on z/OS product tape.
For more detailed information on the common components that are shared among OMEGAMON XE
monitoring agents, see the OMEGAMON shared documentation Version 6.3.0 Fix Pack 2.
OMEGAMON for CICS product components summarizes the OMEGAMON for CICS product components.

Chapter 1. Introducing IBM Z OMEGAMON for CICS 3

 Table 1. OMEGAMON for CICS product components
Provides data
Default Provides these for these
FMID Name Required? STC name interfaces interfaces
HKCI310 Configuration Y NA PARMGEN PARMGEN
Assistance Tool Workflow Workflow
interface interface
HKDS63 Tivoli Enterprise Y IBMDS • Tivoli Enterprise • Tivoli
0 Monitoring Server on Portal Browser Enterprise
z/OS Client Portal Browser
• Tivoli Enterprise Client
Portal Java™ • Tivoli
Webstart Client Enterprise
• Tivoli Enterprise Portal Java
Portal Desktop Webstart Client
• Tivoli
Enterprise
Portal Desktop

HKLV630 TMS:Engine Y Runs inside None None

the IBMDS,
IBMC5,
IBMGW,
and
IBMC20
address
spaces

4 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 1. OMEGAMON for CICS product components (continued)
Provides data
Default Provides these for these
FMID Name Required? STC name interfaces interfaces
HKC5530 IBM Z OMEGAMON for CICS which includes the following:
OMEGAMON XE Y IBMC5 None • Enhanced
CICS monitoring 3270 user
agent interface
• Tivoli
Enterprise
Portal Browser
Client
• Tivoli
Enterprise
Portal Java
Webstart Client
• Tivoli
Enterprise
Portal Desktop

OMEGAMON XE Y IBMC5 None • Enhanced

CICSplex monitoring 3270 user
agent interface
• Tivoli
Enterprise
Portal Java
Webstart Client
• Tivoli
Enterprise
Portal Browser
Client
• Tivoli
Enterprise
Portal Desktop

OMEGAMON for Y IBMOC0 • OMEGAMON for • OMEGAMON

CICS (3270) CICS (3270) for CICS (3270)
The OMEGAMON
for CICS (3270) VTAM interface VTAM interface
started task • TSO ISPF • TSO ISPF
provides critical interface interface
data to the • Dedicated • Dedicated
OMEGAMON XE product- product-
CICS and provided provided
CICSplex agents. interface interface

Chapter 1. Introducing IBM Z OMEGAMON for CICS 5

 Table 1. OMEGAMON for CICS product components (continued)
Provides data
Default Provides these for these
FMID Name Required? STC name interfaces interfaces
HKGW53 OMEGAMON for N IBMGW None • Enhanced
0 CICS TG on z/OS 3270 User
Interface
• Tivoli
Enterprise
Portal Browser
Client
• Tivoli
Enterprise
Portal Java
Webstart Client
• Tivoli
Enterprise
Portal Desktop

HKOB73 OMNIMON BASE which includes the following:

0
OMEGAMON N IBMCN None None
Subsystem
Tivoli OMEGAMON N but is highly IBMTOM Enhanced 3270 Enhanced 3270
Manager recommended User Interface User Interface

The relationships among these components are shown in Figure 2 on page 7.

6 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 Figure 2. The OMEGAMON enhanced 3270 user interface is a base component of the OMEGAMON for CICS
on z/OS product

OMEGAMON enhanced 3270 user interface

The OMEGAMON enhanced 3270 user interface is a shared component of the OMEGAMON for CICS on
z/OS product.
The OMEGAMON enhanced 3270 user interface component is the latest generation of 3270 interfaces for
the OMEGAMON family of monitoring products. The new interface preserves many of the valued features
of the earlier OMEGAMON for CICS (3270) and OMEGAMON II for CICS (CUA) interfaces, but extends the
functionality to include many new features including cross-system and cross-product reporting.
The OMEGAMON enhanced 3270 user interface component enables you to monitor the performance of
your z/OS systems, applications, and devices in your environment and helps you identify and troubleshoot
problems with those monitored resources. The OMEGAMON enhanced 3270 user interface is developed
upon the common OMNIMON base component and provides CICSplex reporting for service level and
transaction analysis. In the interface, data is presented in workspaces and sub panels in which the
collected data and relevant information is displayed. IBM Z OMEGAMON for CICS provides predefined
workspaces that enable you to quickly and easily diagnose problems with monitored resources and take
action to correct them. You can customize the workspaces to suit your requirements, even design and
create your own workspaces and navigation.
For more information see the OMEGAMON shared documentation Version 6.3.0 Fix Pack 2.
The OMEGAMON enhanced 3270 user interface displays information about the following:
• Bottleneck Analysis
• CICSPlex Region Overview
• Connections Summary

Chapter 1. Introducing IBM Z OMEGAMON for CICS 7

 • DB2 Summary
• Enqueue Analysis
• File Analysis
• Program Definitions
• Service Level Analysis
• Storage Analysis
• Temporary Storage Analysis
• Task History
• Transaction Analysis
• Transaction Definitions
• Web Services
You can also configure the following settings using the OMEGAMON enhanced 3270 user interface:
• Application trace
• CICSplex classification rules

IBM Z OMEGAMON for CICS component

IBM Z OMEGAMON for CICS is a comprehensive software performance monitor that alerts you to CICS
response time degradation and overall system problems through color-coded status bars or through
user-defined status words.
The OMEGAMON for CICS component has the OMEGAMON for CICS (3270) interface (also known as
classic, menu system or KOCCI).
The OMEGAMON for CICS (3270) interface provides a realtime window into CICS activity. It automatically
detects and warns of problems that affect CICS availability and performance, and identifies any
degradation associated with resources internal or external to CICS in the z/OS environment.
Also included as part of the OMEGAMON for CICS component configuration is the OMEGAMON subsystem
component. OMEGAMON Subsystem is configured as part of the OMEGAMON product configuration, but
it is an optional component, which you can elect not to start or copy to your started task PROCLIB.
The OMEGAMON Subsystem provides Interval record recording (INTR) and dynamic I/O information to
OMEGAMON for CICS.

IBM Z OMEGAMON for CICS component

OMEGAMON for CICS on z/OS is a component within the OMEGAMON for CICS on z/OS base product.
The OMEGAMON for CICS on z/OS component enables you to do the following tasks:
• Manage performance and availability of IBM CICS systems from a single integrated interface
• Resolve common problem scenarios that span multiple CICS regions using the OMEGAMON enhanced
3270 user interface set of predefined workspaces
• Monitor groups of CICS regions as a CICSplex. It can help resolve problems spanning multiple regions.
• Locate and monitor transactions that participate in a composite transaction across a defined CICSplex.
• Monitor transactions to understand how resource usage and performance affect internal users and
customers
• Identify tasks waiting for specific resources and pinpoint excessive wait times to resolve issues quickly
• Monitor virtual storage access method (VSAM) files, identify record-level sharing locks and facilitate
rapid resolution to maximize availability
• Correlate CICS log streams with associated facility structures to fine-tune CICS systems for optimal
performance

8 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 • Integrate information from other OMEGAMON XE monitors across multiple and third-party software into
a single view
• Monitor CICS Transaction Server for z/OS, Version 4.2 with respect to additional LSR Pools and record
sequential delimited file system monitoring capabilities

OMEGAMON for CICS TG on z/OS component

IBM Z OMEGAMON for CICS TG is a component within the IBM Z OMEGAMON for CICS base product.
IBM Z OMEGAMON for CICS TG offers a central point of management for CICS TG on z/OS and CICS
TG resource adapters deployed within the IBM WebSphere® Application Server on z/OS. OMEGAMON
for CICS TG on z/OS comprehensively gathers the information necessary to detect, correct, and prevent
problems within your CICS TG applications. Using the Tivoli Enterprise Portal or the Enhanced 3270 User
Interface, you can view the data gathered from the monitoring agent in tables and charts. These tables
and charts indicate the status of your managed CICS TG address spaces (that is, instances of the CICS
TG daemon), CICS TG connection factories in WebSphere Application Server, and connectivity to CICS
Transaction Server.
IBM Z OMEGAMON for CICS TG enables you to do the following tasks:
• Collect and analyze reliable, up-to-the-minute data that allows you to make faster, better informed
operating decisions
• Manage all CICS TG applications from a single point to identify problems at any time
• Track performance against goals
• Collect CICS TG statistics, which you can use to view thread activity, report CICS Transaction Server
communication failures, examine resource waits and EXCI (External CICS Interface) pipe usage, and
check for excessive transaction rollbacks, among other monitoring activities
• Monitor CICS TG active transactions and provide response time analysis. CICS TG V7.1 or higher is
required for transaction monitoring.
• Monitor CICS TG resource adapters deployed within the WebSphere Application Server.
With OMEGAMON for CICS TG on z/OS, systems administrators can set threshold levels and flags to alert
them when system conditions reach these thresholds. They can use these advanced monitoring facilities:
• User-defined and predefined situations based on thresholds to raise different types of alerts
• At-a-glance status of all CICS TG regions
• The capability to monitor multiple CICS TG regions simultaneously from one or more centralized
workstations

Interoperability with other products

IBM Z OMEGAMON for CICS is designed to integrate with all products that use Tivoli Management
Services.
These products exploit the ability of the Tivoli Enterprise Portal to integrate and correlate performance
and availability information from a variety of sources. For example, the Tivoli Enterprise Portal allows
you to create custom workspaces composed of data from a range of Tivoli monitoring solutions (IBM
Tivoli Monitoring, IBM Tivoli Composite Application Manager, and IBM Tivoli NetView® for z/OS, as well as
OMEGAMON XE monitoring agents). You can create context-sensitive links between product workspaces
to obtain additional information about systems, subsystems, resources or network components that are
being monitored by other monitoring agents, or to 3270-based applications.
In addition, OMEGAMON XE products are being integrated with an increasing number of other Tivoli and
IBM products.
Situation events reported by IBM Z OMEGAMON for CICS can be forwarded to Tivoli Event Console
or Tivoli Netcool®/OMNIbus™ for event correlation and management. From the Tivoli Enterprise Portal,
you can launch into other Web-based or Web-enabled Tivoli applications without having to reenter user

Chapter 1. Introducing IBM Z OMEGAMON for CICS 9

 credentials, and you can launch in context into the Tivoli Enterprise Portal from applications like Tivoli
Business Services Management.
IBM Z OMEGAMON for CICS uses IBM Tivoli Common Reporting as its integrated reporting solution and
also provides information for ITCAM for CICS Transactions, which provides transaction tracking for CICS
regions.
OMEGAMON XE System z products are compatible with each other and can coexist in a single
OMEGAMON XE environment (that is, with a common Tivoli Enterprise Monitoring Server). These
products, including the OMEGAMON for z/OS product, also interoperate with Tivoli Enterprise Monitoring
Agents running on distributed systems and communicating through the same monitoring server.

10 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Chapter 2. Planning your configuration
This section contains information concerning your configuration planning as it relates to the OMEGAMON
for CICS on z/OS, OMEGAMON for CICS TG on z/OS, and OMEGAMON for CICS (3270) monitoring
components.
The configuration of the Tivoli Enterprise Monitoring Server and the OMEGAMON enhanced 3270 user
interface is discussed in the OMEGAMON shared documentation.
If you are installing the OMEGAMON for CICS on z/OS base product for the first time, read the entire
section. If you are upgrading from a prior version, you can proceed to Chapter 3, “Upgrading to the new
release,” on page 17 after you have reviewed the configuration requirements for this release.

Configuration prerequisites
Before you configure IBM Z OMEGAMON for CICS, you must have completed the following tasks:
• Installed the product package. See the IBM Z OMEGAMON for CICS: Program Directory.
• Configured a monitoring server.
• If your hub Tivoli Enterprise Monitoring Server is running on a distributed platform, then you must install
IBM Tivoli Monitoring V6.3.0 Fix Pack 2
• If your hub Tivoli Enterprise Monitoring Server is running on a z/OS operating system but is not installed
into the same CSI as IBM Z OMEGAMON for CICS, then you must install these required PTFs:
– PTFs UA70676 and UA70677 for FMID HKLV630
– PTFs UA70675 and UA70678 for FMID HKDS630
– PTF for FMID HKCI310
For more information on planning and configuration prerequisites see the OMEGAMON shared
documentation Version 6.3.0 Fix Pack 2.

PTFs required for using embedded OMEGAMON for Storage data

retrieved with DFSMS
The e3270 user interface CICS RLS File details for filename in cicsname workspace (KCPRLSD) can embed
data retrieved from the OMEGAMON for Storage product if the Storage monitoring agent is configured
and running in the same runtime environment (RTE) as the CICS monitoring agent agent. OMEGAMON for
Storage retrieves this data using IBM Data Facility Storage Management Subsystem (DFSMS).
Before this embedded data can be retrieved, the following DFSMS PTFs must be applied to DFSMS:
• APAR OA41786, enabled by the following PTFs:
– PTF UA70448 HDZ1C10
– PTF UA70449 HDZ1D10
– PTF UA70450 HDZ2210
• APAR OA42288
• APAR OA42798
• APARs OA43380 and OA43381, enabled by the following PTFs:
• APAR OA43376, enabled by the following PTFs
– SMF 42 Subtype 16 field SMF42GAI problem
– SMF 42 Subtype 19 fields SMF2AJNO and SMF2AJNR.

© Copyright IBM Corp. 2004, 2022 11

Configuring components
In some cases, a product or component can be shared by more than one product.
If you have already configured these types of components, you can use the existing component. For
example, you can use the monitoring server with more than one IBM product.
If you are going to use an existing component, the component must be current. You must have installed
and configured the component for another IBM product at the same or higher level. For installation
instructions, see the program directory for your product.

Determining the products and components to configure

This section explains the products and components available for some IBM Tivoli Monitoring products,
including the following information:
• A typical OMEGAMON XE product and its components, and whether or not the components are required
(R) or optional (O)
• Whether or not the component can be shared
• Location of any relevant information for your configuration
• Additional information that might help you decide if you want to configure the component
Table 2. Determining the required products or components, location of information, and whether they can be shared

Component name Product Location of information Shared? Additional information (if any)

Tivoli Enterprise Monitoring R For z/OS monitoring servers, Y

Server see the OMEGAMON shared
documentation. For non-z/OS
monitoring servers, see the IBM
Tivoli Monitoring Installation and
Setup Guide.

Tivoli Enterprise Portal Server O/R IBM Tivoli Monitoring: Installation Y The Tivoli Enterprise Portal Server
and Setup Guide is required if you want to use
any of the Tivoli Enterprise Portal
reporting features. These include
customization of the Service Level
Analysis configuration, configuring
historical data collection, and using
the SLA Batch utility.

OMEGAMON for CICS (3270) R This documentation N This interface is OMEGAMON for
CICS (3270).

IBM Z OMEGAMON for CICS R This documentation N The OMEGAMON for CICS on z/OS
monitoring agent, which provides
the collection and monitoring data
that is displayed by the Tivoli
Enterprise Portal interface and the
OMEGAMON enhanced 3270 user
interface.

IBM Z OMEGAMON for CICS O This documentation N This is the OMEGAMON for
CICS TG on z/OS monitoring
component; it offers a central
point of management for CICS TG
on z/OS and CICS TG resource
adapters deployed within the IBM
WebSphere Application Server on
z/OS.

12 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 2. Determining the required products or components, location of information, and whether they can be shared (continued)

Component name Product Location of information Shared? Additional information (if any)

OMEGAMON enhanced 3270 O/R "OMEGAMON Enhanced 3270 N This interface preserves many
user interface user interface" in the Reference of the valuable features of the
section of OMEGAMON shared earlier OMEGAMON for CICS (3270)
documentation Version 6.3.0 Fix and OMEGAMON II for CICS
Pack 2 (CUA) interfaces, but extends the
functionality to include many new
features including cross-system,
cross-product and CICSplex level
reporting.

End-to-end response time O "End-to-End Response Time Y Required only if you configure
(ETE) Feature Reference" in the the OMEGAMON for CICS RTA
Reference section ofOMEGAMON VTAM® LU End-to-End Response
shared documentation Version 6.3.0 Time monitoring feature. Use one
Fix Pack 2 OMEGAMON ETE subsystem for all
the products and components you
install and configure.

Tivoli Monitoring Web Services R For z/OS monitoring servers, Y You enable the SOAP server during
(SOAP Server) see the OMEGAMON shared configuration of the hub monitoring
documentation Version 6.3.0 Fix server. This is required for various
Pack 2. For non-z/OS monitoring IBM Tivoli Monitoring administrator
servers, see the IBM Tivoli functions, for example, the TACMD
Monitoring Installation and Setup command, for controlling the self-
Guide. describing agent feature.

IBM Tivoli Monitoring self- O OMEGAMON shared documentation N The IBM-supplied self-describing
describing agent Version 6.3.0 Fix Pack 2,IBM Tivoli agent default for a hub Tivoli
Monitoring: Installation and Setup Enterprise Monitoring Server is
Guide, and IBM Tivoli Monitoring disabled by default on all
Administrator's Guide Tivoli Enterprise Monitoring Server
platforms.
Enabling the self-describing
capability ensures that the proper
level of application data is
installed in the Tivoli Enterprise
Monitoring Server and Tivoli
Enterprise Portal Server without
manual installation of support
files. If the self-description
feature is activated, runtime
verification checks for updated
application data. If inconsistent
conditions are detected, application
data is propagated from the
monitoring agent to the various
monitoring servers, which are
automatically updated without
requiring recycling. If you enable
self-description, you do not need
to install a Tivoli Enterprise Portal
Server for seeding application
support files for OMEGAMON for
CICS on z/OS or OMEGAMON for
CICS TG on z/OS.

Persistent Datastore (TMS/ O/R IBM Tivoli Monitoring N You can configure the persistent
Persistent Data Store) Administrator's Guide, "Maintaining data store with the monitoring
the persistent datastore" in the server or with the monitoring agent
Reference section of OMEGAMON (depending on how you choose to
shared documentation Version 6.3.0 configure the agent). If you choose
Fix Pack 2, and this documentation to configure IBM Tivoli Monitoring
historical data collection for any
z/OS based monitoring agent, the
persistent data store is required; it
is not required for OMEGAMON for
CICS (3270) component historical
reporting.

Chapter 2. Planning your configuration 13

 Table 2. Determining the required products or components, location of information, and whether they can be shared (continued)

Component name Product Location of information Shared? Additional information (if any)

Tivoli Enterprise Services User O/R IBM Tivoli Monitoring: Installation Y Required if you enable the IBM
Interface Extensions (KUE) and Setup Guide Tivoli Monitoring self-describing
agent feature and you do not install
a Tivoli Enterprise Portal Server.

OMEGAMON Subsystem O OMEGAMON shared documentation Y It is required for the Interval

Version 6.3.0 Fix Pack 2 Recording feature that is available
through OMEGAMON for CICS
(3270).
Use one OMEGAMON Subsystem
for all the products and
components you install and
configure.

Tivoli Enterprise Portal O/R IBM Tivoli Monitoring Installation Y This is comprised of the Tivoli
and Setup Guide and the IBM Tivoli Enterprise Portal browser, desktop
Enterprise Portal: User's Guide client, and Tivoli Enterprise
Portal Server. It is optional
with V5.5.0 of OMEGAMON for
CICS on z/OS, unless you want
to modify OMEGAMON service
level definitions or implement the
historical collection feature of IBM
Tivoli Monitoring.

Planning configuration of OMEGAMON for CICS (3270)

Use this section to determine if you want to plan your configuration of OMEGAMON for CICS (3270), the
Classic user interface.
The OMEGAMON for CICS component configuration generates these started tasks:
• OMEGAMON for CICS (3270) - (Required), default: IBMOC0
• OMEGAMON Subsystem - (Optional), default: IBMCN
You are only required to start the OMEGAMON for CICS (3270) started task (IBMOC0), the other
started tasks are optional and can be started depending on your product configuration. The OMEGAMON
Subsystem started task (IBMCN) is only required if you want to use the interval record (INTR) and
dynamic I/O information.
You must start at least one OMEGAMON for CICS (3270) started task on each LPAR where you plan to
monitor CICS regions.
OMEGAMON for CICS (3270) provides real time data to OMEGAMON for CICS on z/OS.
For more information on using OMEGAMON for CICS (3270), see IBM OMEGAMON for CICS on z/OS:
OMEGAMON for CICS User's Guide and Reference.
After you complete your review of the Scenarios and how-tos section of the OMEGAMON shared
documentation, here are some questions that you need to answer before you configure the OMEGAMON
for CICS component:
• Which CICS regions do I plan to monitor and on which LPARs are they located?
You must configure at least one OMEGAMON for CICS (3270) on each LPAR with the CICS regions you
plan to monitor
• Do you run test and production CICS regions on the same LPAR?
If so, you might want to consider separating your OMEGAMON monitoring systems out into distinct test
and production reporting views.

14 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 Requirements for virtual storage
The following tables provide information to help you determine how much virtual storage the OMEGAMON
for CICS component will use after it is installed and operating in the OMEGAMON for CICS (3270)
interface.
Use the following table to determine the storage required in CSA and ECSA for the OMEGAMON for CICS
(3270) interface.

Table 3. Storage Required in CSA and ECSA

ECSA Storage is
Function CSA required You require... required You require... freed when...
Each collector Approximately 1 Each collector
KB is terminated
Each CICS Approximately Monitoring is
region you 0.5 KB stopped
monitor

Use the following table to determine the amount of CICS storage that is required the first time the
OMEGAMON for CICS (3270) is activated within a CICS region.

Table 4. Storage Required in CICS

Usage Private Extended private DSA EDSA
Static Approximately 150 Approximately 6 Approximately 10
KB KB KB
Buffer for task Variable (see Note
history and #1 following)
response time
collector data
Buffer for file-level Variable (see Note
statistics #2 following)

Each task currently running uses approximately 2.6 KB of ECDSA storage. In some cases, an additional 32
bytes might be added to the tasks CDSA requirements.
Note:
1. Use the following calculation to help you determine approximate buffer storage requirements (buffer
size) for task history and the response time collector:

buffer size = (1+(n/300))*1200 + n*1200 + 88

Where n is the number of records you want the buffer to contain. (You set the number of buffer records
when you specify the monitoring options for the product using the Global Data Area.)
2. OMEGAMON for CICS (3270) allocates buffers of 64 KB to contain the file level statistics it collects
during monitoring of CICS transactions. OMEGAMON for CICS uses 50 to 150 bytes per task for each
file that a task accesses. OMEGAMON for CICS (3270) retains this storage for the lifetime of the task
and reuses it when the task ends.

Planning configuration of IBM Z OMEGAMON for CICS

Use this section to determine if you want to configure IBM Z OMEGAMON for CICS.
After you complete your review of the Scenarios and how-tos section of the OMEGAMON shared
documentation, here are some questions that you need to answer before you configure the IBM Z
OMEGAMON for CICS component:

Chapter 2. Planning your configuration 15

 • Which CICS regions do I plan to monitor and on which LPARs are they located?
You must configure at least one IBM Z OMEGAMON for CICS monitoring agent on each LPAR where you
wish to monitor one or more CICS regions.
• Do you run test and production CICS regions on the same LPAR?
If so, you might want to consider separating your OMEGAMON monitoring systems out into distinct test
and production reporting views.

Planning configuration of IBM Z OMEGAMON for CICS TG on z/OS

Use this section to determine if you want to configure IBM Z OMEGAMON for CICS TG.
After you complete your review of the Scenarios and how-tos section of the OMEGAMON shared
documentation Version 6.3.0 Fix Pack 2, here are some questions that you need to answer before you
configure the OMEGAMON for CICS component:
• Which CICS TG daemons do I plan to monitor and on which LPARs are they located?
You must configure at least one IBM Z OMEGAMON for CICS TG monitoring agent on each LPAR where
you wish to monitor one or more CICS TG daemons.
• Do you run test and production CICS TG daemons on the same LPAR?
If so, you might want to consider separating your OMEGAMON monitoring systems out into distinct test
and production reporting views.

16 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Chapter 3. Upgrading to the new release
This section covers only additional requirements specific to IBM Z OMEGAMON for CICS.
OMEGAMON shared documentation Version 6.3.0 Fix Pack 2: Upgrading covers upgrade requirements and
instructions common to all OMEGAMON XE products, including the following topics:
• Required versions of Tivoli Management Services components.
• Requirements for staged upgrades.
• Instructions for upgrading in place and in a new CSI.
• Example scenarios for using the PARMGEN configuration method to roll out an upgrade. See also
the Scenarios and how-tos section in OMEGAMON shared documentation Version 6.3.0 Fix Pack 2 for
deployment scenarios for this configuration method.
The following statement applies to all components of the IBM Z OMEGAMON for CICS product:
If you are upgrading from a previous release of IBM Z OMEGAMON for CICS, the product continues to
run with the existing parameters, but new features introduced with this release are not fully implemented
until after your product configuration has been completed.

Enabling new features

If you are upgrading from a release prior to V5.5.0 of IBM Z OMEGAMON for CICS, the CICS agent will
continue to run with the existing parameters, but the new features will not be enabled and will not be
started.
To generate the updated parameters, which will enable new features introduced with V5.5.0, you need
to configure the IBM Z OMEGAMON for CICS component again. If your hub Tivoli Enterprise Monitoring
Server is not self-describing agent enabled, you will need to manually add application support to the hub
Tivoli Enterprise Monitoring Server.

Enabling the self-describing agent

By default, support for self-describing agents is disabled on the hub monitoring server. To use this feature,
you must enable it on the hub monitoring server and configure that particular runtime environment where
the Tivoli Enterprise Monitoring Server resides to support it.
In IBM Z OMEGAMON for CICS, if the self-describing agent is enabled, and, if there is a hub Tivoli
Enterprise Monitoring Server configured in the runtime environment, and there are any other agents
configured to run in the hub Tivoli Enterprise Monitoring Server, you might consider creating a high
availability hub runtime environment and converting the hub Tivoli Enterprise Monitoring Server in this
runtime environment to a remote Tivoli Enterprise Monitoring Server.
If you elect not to create a high availability hub runtime environment, a hub recycle might be required
when you install maintenance for self-described enabled agents configured to run in the hub Tivoli
Enterprise Monitoring Server address space (such as OMEGAMON for z/OS).
If you would like to avoid having to install a Tivoli Enterprise Portal Server or to perform a manual
seeding of application support files from a distributed platform, then you should consider enabling self-
description at your hub Tivoli Enterprise Monitoring Server before starting or bringing the new IBM Z
OMEGAMON for CICS V5.5.0 agent online.
If you are running a Tivoli Enterprise Monitoring Server on z/OS and are planning to enable the self-
describing agent, you are required to create HFS directories on z/OS UNIX System Services (USS).
The USS system where you create these directories must have access to a Java Runtime Environment
running under IBM's 31-bit or 64-bit Java SDK Version 5 (or higher) and an HFS or zFS file system. See
OMEGAMON shared documentation for more information.

© Copyright IBM Corp. 2004, 2022 17

 Self-describing agent administration requires access to the tacmd CLI command from a distributed
platform such as Windows, UNIX or Linux®. If you do not want to install a Tivoli Enterprise Portal
Server or Tivoli Enterprise Monitoring Server on a distributed platform, but you do intend to run with
self-description enabled, install the tacmd CLI on at least one distributed platform. It does not need to
be installed on a distributed server, but the system that it is installed on requires access through a SOAP
services connection to the your hub Tivoli Enterprise Portal Server. To install the tacmd CLI, from your
IBM Tivoli Monitoring, version 6.2.3 (or higher) installation image, select the Tivoli Enterprise Services
User Interface Extensions feature (KUE) when running the IBM Tivoli Monitoring installation program; see
the IBM Tivoli Monitoring Installation and Setup Guide for more information. For additional information
regarding using tacmd to control self-description, refer to the IBM Tivoli Monitoring: Administrator's
Guide.
For more information on enabling the self-describing agent, see the OMEGAMON shared documentation.

Performing a staged upgrade

To make product upgrades easier, IBM Z OMEGAMON for CICS supports upgrading agents gradually, by
allowing a mixture of monitoring agents of the current version and the previous version in the same
environment.
You can deploy new monitoring agents to your z/OS systems along with older monitoring agents of the
same product, during an upgrade transition period.
IBM Z OMEGAMON for CICS monitoring agent can only monitor CICS regions where the level of
OMEGAMON initialized within the CICS region is that of the same level or less. For example, an IBM
Z OMEGAMON for CICS V5.5.0 agent will monitor a CICS region initialized with V4.2.0, V5.1.0 or V5.3.0,
but a V5.1.0 agent will not monitor a CICS region with IBM Z OMEGAMON for CICS V5.5.0 initialized in it.
The IBM Z OMEGAMON for CICS V5.5.0 agent only supports a connection to Tivoli Enterprise Monitoring
Server running with IBM Tivoli Monitoring, V6.2.3 or higher level.
If you are upgrading a monitoring agent and Tivoli Management Services, refer to OMEGAMON shared
documentation Version 6.3.0 Fix Pack 2: Upgrading.
IMPORTANT: Only CICS regions monitored by OMEGAMON for CICS on z/OS V5.1.0 and later can be
viewed in the OMEGAMON enhanced 3270 user interface.

Migration considerations
When upgrading the OMEGAMON for CICS (3270) address space all CICS regions that it monitors should
be upgraded to the matching release. It is possible to have two different releases of OMEGAMON for CICS
(3270) monitoring the same CICS region, however, Response Time Analysis, and Task History will only
function in the address space that matches the release that is installed in the CICS region. OMEGAMON
will not initialize in a CICS region if no OMEGAMON for CICS (3270) address space is located at the same
release level; this means that Resource Limiting and SMF data would not be produced.

How to avoid a CICS region recycle when upgrading to IBM Z OMEGAMON for CICS
V5.5.0
If you want to avoid recycling your CICS regions during the upgrade to IBM Z OMEGAMON for CICS, the
following upgrade scenario is suggested:
1. Complete your first runtime environment upgrade (see OMEGAMON shared documentation Version
6.3.0 Fix Pack 2: Upgrading for additional information regarding staged upgrade requirements).
2. As part of the runtime environment upgrade, after you load the runtime environment, your RKANMOD
and RKANMODR libraries will contain the V5.5.0 modules. Your CICS region should have the same
RKANMOD and RKANMODR libraries allocated.
3. Recycle your upgraded OMEGAMON for CICS (3270) V5.5.0 address space, leaving your CICS regions
running.

18 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 Note: After the recycle is complete, your response time analysis, task history and interval recorder
features will not be restarted until after the next step (4) is completed.
4. For each CICS region that you want to upgrade to IBM Z OMEGAMON for CICS V5.5.0, enter the OMEG
RECYCLE command or the OMEG REMOVE command, followed by the OMEG INIT command. This will
remove the previous version of OMEGAMON for CICS (3270) and restart the monitoring by loading
the V5.5.0 version of OMEGAMON for CICS (3270) that exists in your upgraded runtime environment
RKANMOD and RKANMODR libraries.

OMEGAMON for CICS (3270) upgrade considerations

You might want to consider a staged upgrade, which might include upgrading your IBM Z OMEGAMON for
CICS agent prior to upgrading your OMEGAMON for CICS (3270) component.
See “Performing a staged upgrade” on page 18 for further information.

CICS-specific PARMGEN updates

The following CICS-specific PARMGEN updates have been made.
• The KC5_WLM_BLOCKS configuration parameter has been changed from 236 blocks to 2048 blocks.
This change also affects the Service Task Details situation.
• The KC2_CCnn_CLASSIC_XMIT parameter is used to specify the XMIT number for the OMEGAMON
for CICS (3270) address space starting in V5.3.0, you can minimize the JCL changes that are required
to your CICS regions. In earlier releases, you were required to add load libraries to your CICS regions
and DD cards that controlled the monitoring of those regions (RKCPXMnn, RKC2XMnn and KC2GLBcc).
V5.3.0 or later release implement support for a new CICS library definition.
• The default started task prefix specified with the KC2_CCnn_CUA_STC parameter has been changed
from CANS to IBM.

Impact of near-term history on the persistent data store

In version 5.3.0 or later, OMEGAMON for CICS supports near term history for the enhanced 3270 user
interface (3270UI) workspaces.
Near term history provides the capability to investigate problems that occurred in the recent past by using
the enhanced 3270UI. Near term history provides intuitive access to historical data collected by both
agents and IBM Tivoli Monitoring. Two types of historical workspace are provided: the historical summary
and the historical snapshot.
This enhancement requires that the size of the persistent data store (PDS) on z/OS or the number of
persistent data stores be increased. See the historical data tables in this guide for more information
about PDS sizing. Also, see "Maintaining the persistent data store" topic in the Reference section of the
OMEGAMON shared documentation Version 6.3.0 Fix Pack 2.
Because of this change, the number of persistent data store historical files is increasing from three to six,
and the group file count is decreasing from three to one.
This enhancement increased the count of persistent data store historical files from three to six to increase
the amount of online viewing data because one file is always empty. The group file count was decreased
from three to one as only one file is needed and there is no need to swap the group files.
For more information about using near term history, see the OMEGAMON shared documentation Version
6.3.0 Fix Pack 2: OMEGAMON Enhanced 3270 user interface.

Change to the definition of KOCOME00 in CICS

It is now recommended that you define KOCOME00 as follows:

DEFINE TRANSACTION(OMEG) PROGRAM(KOCOME00) GROUP(OMEGAMON)

TASKDATAKEY(CICS) TASKDATALOC(ANY)

Chapter 3. Upgrading to the new release 19

 This change of the TASKDATALOC to ANY avoids a potential situation where OMEGAMON forces
application GETMAINs to obtain storage below the line.
The sample provided in hilev.TKANSAM(KOCCSD) contains the currently recommended values.

Cross-memory considerations
The PARM=LXRES parameter is not coded on the EXEC statement. PARMGEN generates the PROC without
this statement. If you are reusing an existing PROC, you should ensure this statement is removed.

Basic system configuration

Configuring OMEGAMON for CICS creates a set of address spaces independent of your existing CICS
regions. To avoid installing processes that invade any CICS system, the basic system that you configure
will not include the following functions:
• Response time collection
• Task history collection
• Internal bottleneck collection
• Interval record collection
• Resource limiting

Dispatching priority
To ensure availability, you must run the OMEGAMON for CICS (3270, required) and OMEGAMON for CICS
on z/OS (required) components and OMEGAMON for CICS on z/OS agent with a z/OS system dispatching
priority higher than any CICS region you are monitoring. OMEGAMON for CICS attempts to raise its
dispatching priority higher than the target CICS region. If this is not possible, OMEGAMON for CICS
produces the following message:
OC0830 OCRO CAUTION DISPATCHING PRIORITY GREATER THAN 239

Running OMEGAMON for CICS at a dispatching priority that is less than the target CICS region, especially
while you are collecting response time data, can seriously degrade the overall performance of your
system. Running OMEGAMON for CICS at a dispatching priority that is less than the target CICS region
affects the 3270 interface.
Address spaces that are running OMEGAMON XE components must run at a higher priority service class
than the address spaces and/or subsystems that are being monitored; this is a requirement for accurate
reporting. These considerations apply to the OMEGAMON enhanced 3270 user interface as well as
components that participate in the data collection. For example, Tivoli Enterprise Monitoring Servers (hub
or remote) and OMEGAMON XE Tivoli Enterprise Management Agents.

What elements to upgrade

The following table shows the elements you can upgrade from prior versions of the OMEGAMON for CICS.

20 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 5. Elements to upgrade from versions of OMEGAMON for CICS.
Element Upgrade Considerations
OMEGAMON Subsystem OMEGAMON Subsystem V7.0.0 is included in
this product package. As other OMEGAMON XE
products share these common components, you
might need to coordinate the deployment of these
common component upgrades.
If you have upgraded from a previous version of
the OMEGAMON Subsystem, and there are multiple
LPARs, OMEGAMON Subsystem use the KCNDLINT
V7.0.0 load module; the version included in this
package. If you are using a global LINKLST, verify
that KCNDLINT is V7.0.0.

Global Data Area The Global Data Area contains the parameters
that control the OMEGAMON for CICS monitoring
options. The values in these parameters apply to
all sessions that are monitoring the same CICS
region. A default global data module is shipped
with the product. You can install and migrate
the current release level, or change the default
settings.
SMF type 110 performance monitoring record OMEGAMON for CICS V4.1.0 and higher does
collection not require any monitoring control table (MCT)
event monitoring points to enable task history
or response time analysis to fully function. The
MCT definitions are only required if you have user
written reports that rely on the definitions.
OMEGAMON for CICS (3270) external security exit If you are upgrading from a previous release and
you have installed one of the OMEGAMON for CICS
(3270) sample security exits, you must reinstall the
exit using the updated samples.
CICS Region JCL Support for the xKANMODR library was introduced
in V3.2 (for DFHRPL usage). The new xKANMODR
library contains only those modules which are
loaded through the CICS DFHRPL DD statement.
Concatenation of RKANMOD is no longer a CICS
DFHRPL requirement. Instead you can choose to
use the xKANMODR library, where x = T for SMP
sharing RTEs; otherwise it is R.
You can modify your CICS region JCL or
use dynamic allocation to dynamically add the
RKANMOD DD and CICS Dynamic program library
concatenation to add the *KANMODR data set.

Historical reporting considerations

This table lists the considerations for the elements in historical reporting.

Chapter 3. Upgrading to the new release 21

 Table 6. Historical reporting considerations for OMEGAMON for CICS (3270).
Element Considerations
Global Data Area The Global Data Area lets you set options for the
task history collector and the historical reporter.
Initialize OMEGAMON for CICS in the CICS region To enable the task history collector, OMEGAMON
where historical data is to be collected. for CICS must be initialized in the CICS region.
SMF Logging You specify all the options for System Management
Facilities (SMF) logging using the Global Data Area.

Command Security considerations

If you are submitting the upgrading job as part of upgrading your OMEGAMON for CICS (3270)
component, you must rerun the KCIJPSEC job on the SUBMIT BATCH JOBS TO COMPLETE PARMGEN
SETUP menu. The KCIJPSEC job in the RTE's RKANSAMU data set picks up the new commands and
security.
For more information about implementing security for OMEGAMON for CICS (3270), see “Securing the
OMEGAMON for CICS (3270)” on page 99.

IBM Z OMEGAMON for CICS considerations

This section contains the upgrade considerations you must review before you begin to configure and
customize IBM Z OMEGAMON for CICS.

Hot Standby considerations for distributed hub configurations

If your IBM Z OMEGAMON for CICS agent is reporting to a hub server on a distributed platform
and you have configured Hot Standby with your distributed hub server, you will need to keep the
RKCPDEFW.db/idx files defined at the hub in sync with the Standby Hub copy of the RKCPDEFW.db/
idxfiles. If you customize your CICS SLA definitions or your OMEGAMON CICS CICSplex definitions, you
will need to copy the RKCPDEFW.db/idx files from your active or primary hub tables directory to your
standby hub tables directory, then recycle the Hot Standby hub. This will ensure that whenever a failover
to the Hot Standby hub is performed, that your customized CICS SLA and CICSPlex® definitions are
available after the failover switch has been completed. For more information, see IBM Tivoli Monitoring
High Availability Guide for Distributed Systems Version 6.3.0.

Removal of INTERVAL= override parameter for WLM startup command

In previous releases of IBM Z OMEGAMON for CICS, you were able to override the collection interval
value as part of the monitoring agent's WLM startup command to allow a collection interval of 1 minute.
To provide an accurate Service Level Analysis across all your defined CICSplexes, the collection interval
setting must be defined consistently at the runtime environment level rather than at the individual
monitoring agent level. For this reason, the INTERVAL= agent startup parameter has been deprecated
and is ignored if you specify it.
If you specify this startup parameter, the following message appears in the monitoring agent RKLVLOG
output:
KCP0233W: THE 'INTERVAL=' PARAMETER IS NO LONGER USED AND WILL BE IGNORED

The service level analysis collection interval defined either through the CICS SLA view in the Tivoli
Enterprise Portal or the SLA Batch command line utility is always used.
If you have used the INTERVAL= parameter in the past to enable a collection interval of 1 minute, you will
need to make the following changes as part of your upgrade to ensure you continue to collect data at the
required interval:

22 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 1. Prior to bringing any upgraded agents online, install the latest IBM Z OMEGAMON for CICS application
support onto a distributed machine which has a Tivoli Enterprise Portal Server installed.
2. Either log on to a connected Tivoli Enterprise Portal client and switch to the CICS SLA view or use
the SLA Batch utility, to update the collection interval to 1 minute (0001, if using the SLA Batch
utility). See “Configuring Service Level Analysis definitions using the Tivoli Enterprise Portal” on page
66 and “Configuring Service Level Analysis definitions using the batch utility” on page 82 for more
configuration information.
3. Bring your new or upgraded agents online. Any agents running at a previous version will continue to
use the override parameter while the new agents will use the updated collection interval value applied
across the entire runtime environment.
Note: No agent running at a previous release will contribute any data to CICSplex based workspaces,
including the CICSplex SLA Summary.

Runtime environment load processing consideration

Prior to running the runtime environment load job (KCIJPLOD for PARMGEN), the IBM Z OMEGAMON
for CICS monitoring agent and the Tivoli Enterprise Monitoring Server started tasks associated with the
runtime environment that are being loaded must be shutdown. Runtime environment load processing
must be allowed to delete the KC5ATR file in RKANDATV before the agent and Tivoli Enterprise Monitoring
Server are restarted. Otherwise, the new KCPATR file might not be correctly loaded during the agent
restart process.

New feature upgrade consideration introduced with this release

If you are upgrading an existing runtime environment from a previous release of IBM Z OMEGAMON for
CICS, CICSplex reporting through the OMEGAMON enhanced 3270 user interface, does not start until
after the load runtime environment processing and product configuration has been completed and the
product address spaces have been recycled. This reconfiguration is not required for a general upgrade,
but needs to be done before you can use CICSplex reporting and the OMEGAMON enhanced 3270 user
interface.
Using the PARMGEN configuration method for your runtime environment configuration, load the runtime
environment, and run &hilev.&rtename.WKANSAMU(KCIJPLOD).

Preparing customized OMEGAMON WLM definitions and CICSplex classification

rules for an upgrade
The OMEGAMON for CICS on z/OS CICS service level analysis OMEGAMON WLM definitions and CICSplex
classification rules (in V5.1.0 or later) are stored in the RKCPDEFW file allocated to the hub Tivoli
Enterprise Monitoring Server.
If you are upgrading to IBM Z OMEGAMON for CICS V5.5.0 or performing a maintenance upgrade only,
save a back up copy of the RKCPDEFW file prior to starting your upgrade. You should use a standard
system file backup utility to back up your RKCPDEFW file. If you are upgrading to V5.5.0, you can also use
the SLA batch utility (kcp_slabatch) to back up your RKCPDEFW file. The SLA batch utility does not include
support for backing up the CICSplex classification rules, so it can not be used for RKCPDEFW file backup
when performing a maintenance upgrade.

IBM Z OMEGAMON for CICS TG considerations

The following data sets, which were allocated and used by previous releases of IBM Z OMEGAMON for
CICS TG, are no longer used after version 5.1.
You can delete these obsolete data sets after you delete the previous release from your system:

#dsthlq.DKGWJAR

Chapter 3. Upgrading to the new release 23

 The following file system paths, which were created and used by OMEGAMON for CICS TG on z/OS
V.4.2.0, are no longer used after version 5.1. After updating OMEGAMON for CICS TG, update the
CLASSPATH environment variable. You can delete this obsolete file system path after you delete the
previous release from your system:

#hfsdir/usr/lpp/kgw

Using the default directory location, here is an example of the directory statement which should be added
to the CLASSPATH environment entry:

/usr/lpp/kan/bin/IBM/kgw_monitor.jar

OMEGAMON for CICS TG on z/OS-specific PARMGEN updates

The following PARMGEN updates specific to OMEGAMON for CICS TG on z/OS have been made.
• A new KGW_SAnn_CTG_DAEMON_HOST parameter has been added which specifies the IP address or
name of the host to which the CICS TG region is bound.

24 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Chapter 4. Configuring IBM Z OMEGAMON for CICS
The information in the sections that follow will take you through the process of configuring OMEGAMON
for CICS on z/OS and its components.
You set the values for the configuration parameters using PARMGEN or Configuration manager.
With either configuration method, you edit a comprehensive list of parameters, configure installed
products and components, and submit a batch job or a series of jobs to create a complete runtime
environment with the parameter values you specified. See the OMEGAMON shared documentation, under
Configuring and Reference, for more information about Configuration Manager and PARMGEN.
When you complete the configuration steps with PARMGEN or Configuration manager, there are some
additional steps that you must perform to complete the configuration; see “Completing the configuration”
on page 32.

Configuration roadmap
The configuration roadmap guides you through the steps to configure the IBM Z OMEGAMON for CICS
monitoring agent, OMEGAMON for CICS component, and IBM Z OMEGAMON for CICS TG component. As
product installer, you might find the roadmap helpful before you configure the IBM Z OMEGAMON for
CICS product.
In general, to complete the configuration tasks for the product, you go through the following configuration
stages:
• Completing PARMGEN prerequisite configuration tasks
• Completing the configuration tasks
• Completing the post-configuration tasks
Each configuration stage contains several configuration tasks that you might need to finish based on your
actual business needs.
“Configuring IBM Z OMEGAMON for CICS using the PARMGEN method” on page 26
“Configuring the OMEGAMON for CICS (3270) component” on page 28
“Configuring the IBM Z OMEGAMON for CICS monitoring agent” on page 30
“Configuring the IBM Z OMEGAMON for CICS TG component using the PARMGEN method” on page 31
“Copying started task procedures and VTAM definitions to your procedure library and VTAMLST system”
on page 33
“Varying the VTAM major node active” on page 34
“Granting APF authorization for the runtime load libraries” on page 34
“Modifying the CICS tables” on page 36
“Defining the OMEGAMON for CICS (3270) program and transaction” on page 40
“Enabling warehouse agents on a z/OS hub monitoring server” on page 43
“Adding application support to a non self-describing agent enabled hub monitoring server” on page 43
“Post installation configuration for transaction monitoring support” on page 44
“Monitoring CICS TG daemons bound to a TCPIP stack other than the one OMEGAMON for CICS TG Agent
is bound to” on page 47
“Defining a policy to periodically sweep away any orphaned transactions (optional)” on page 47
“Verifying the configuration” on page 49

© Copyright IBM Corp. 2004, 2022 25

 “Enabling security” on page 54
“Installing language support” on page 54

Configuring IBM Z OMEGAMON for CICS using the PARMGEN

method
You configure IBM Z OMEGAMON for CICS by accepting or customizing the values of parameters that
begin with KC2 (OMEGAMON for CICS (3270)) and KC5 (OMEGAMON XE component).
For guidance on setting parameter values, see the following sources of information:
• Comments in the configuration profiles
• Online help for the configuration profile
• OMEGAMON shared documentation
• IBM OMEGAMON for CICS on z/OS: Parameter Reference
Before you configure the OMEGAMON for CICS on z/OS agent, you must complete the tasks listed in the
following table.

Table 7. Tasks to complete before configuring IBM Z OMEGAMON for CICS

Configuration task Location of instructions
Set up PARMGEN work libraries for your runtime OMEGAMON shared documentation
environment
Set up the PARMGEN configuration profile for your OMEGAMON shared documentation
runtime environment
(Optional) Configure a Tivoli Enterprise Monitoring OMEGAMON shared documentation. In addition
Server to Configuring, see the Scenarios and how-
tos section, and "Common parameters" in the
Note: If IBM Z OMEGAMON for CICS is the only
Reference section.
product in this runtime environment, then this
step is not required. Review the documentation for
your other products in this runtime environment to
determine if this step is required.

(Optional) Configure an OMEGAMON Subsystem OMEGAMON shared documentation

Note: If IBM Z OMEGAMON for CICS is the only Note: Configure only one OMEGAMON Subsystem
product in this runtime environment, then this for each LPAR.
step is not required. Review the documentation for
your other products in this runtime environment to
determine if this step is required.

(Optional) Configure the OMEGAMON enhanced OMEGAMON shared documentation

3270 user interface address space
Note: You only need to configure one OMEGAMON
enhanced 3270 user interface address space in a
Sysplex.

Configuration prerequisites
Identify where your hub Tivoli Enterprise Monitoring Server is to reside. Then, determine which Tivoli
Enterprise Monitoring Server your IBM Z OMEGAMON for CICS and IBM Z OMEGAMON for CICS TG agents
will report to and where your monitored subsystems will run. See the OMEGAMON shared documentation
for additional information regarding Tivoli Enterprise Monitoring Server planning and configuration.
Each IBM Z OMEGAMON for CICS and IBM Z OMEGAMON for CICS TG agent must report to a Tivoli
Enterprise Monitoring Server. The Tivoli Enterprise Monitoring Server, that these agents report to, can

26 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

either be installed on a z/OS system or on a distributed platform. IBM Z OMEGAMON for CICS and IBM
Z OMEGAMON for CICS TG can report to a Tivoli Enterprise Monitoring Server configured with any of the
supported IBM Tivoli Monitoring protocols.
Review your system environment to determine where the CICS regions and CICS TG daemons will run for
your monitoring. You will need to run one IBM Z OMEGAMON for CICS agent and OMEGAMON for CICS
collection address space on each LPAR where the CICS regions that you wish to monitor. You will need to
run one IBM Z OMEGAMON for CICS TG agent on each LPAR where the CICS TS daemon that you wish to
monitor.
Review your runtime environment configuration default settings to determine whether or not they can
be used for your IBM Z OMEGAMON for CICS product configuration. See "Common parameters" in the
Reference section of OMEGAMON shared documentation for additional information regarding runtime
environment and Global configuration parameters.
Review the PARMGEN configuration profiles required for user customization:
• WCONFIG($GBL$USR) global configuration profile
If you want to configure the full IBM Z OMEGAMON for CICS product into a runtime environment, you
must specify Y for the following parameter values:

** IBM Z OMEGAMON for CICS: KC5 flag

CONFIGURE_CICS_KC5 "Y"
** IBM OMEGAMON for CICS TG on z/OS: KGW flag
CONFIGURE_CICS_TG_KGW "Y"

• WCONFIG(RTENAME) LPAR-specific runtime environment configuration profile

The first time you create a runtime environment for the IBM Z OMEGAMON for CICS product, complete
the configuration using runtime environment and product or configuration default values where ever
possible. There are some parameter default values that are typically overridden due to installation
requirements.
These are the IBM Z OMEGAMON for CICS product defaults you might want to override:
• Started tasks names, which might be generated as part of your runtime environment configuration, use
these default configuration values:
IBMDS
Tivoli Enterprise Monitoring Server; you can optionally define a Tivoli Enterprise Monitoring Server
on a distributed platform.
IBMCN
OMEGAMON Subsystem; this is an optionally started task.
IBMTOM
OMEGAMON enhanced 3270 user interface; this started task is recommended, but you only need
to create one started task. You do not need one in every runtime environment, because it can
communicate with multiple hub Tivoli Enterprise Monitoring Servers and agents across multiple
runtime environment configurations.
IBMOC0
OMEGAMON for CICS (3270)
IBMC5
IBM Z OMEGAMON for CICS agent; by default, the agent is configured in its own address space, but
during configuration, you can to configure the agent to run in a Tivoli Enterprise Monitoring Server
address space.)
IBM is the default started task prefix. You can either override this default during the product
configuration or you can change it by modifying the runtime environment configuration parameter. For
example, the PARMGEN parameter is: RTE_STC_PREFIX.
• VTAM Node and application definitions

Chapter 4. Configuring IBM Z OMEGAMON for CICS 27

 Many of the components configured to run with OMEGAMON products require VTAM application
definitions. CTD is the VTAM node and applid prefix generated by default. For each component that
you configure that requires VTAM, you might want to specify a default other than the configuration
default. See the following sections to see a list of the applicable product parameters which you might
want to modify depending on your site's installation requirements.
For more information on PARMGEN, see OMEGAMON shared documentation.

Excluding products from the PARMGEN customization list

After installing IBM Z OMEGAMON for CICS V5.6.0 into the CSI, PARMGEN presents the following
products in the PARMGEN customization list:

KC5 IBM Z OMEGAMON for CICS V560

KDS Tivoli Enterprise Monitoring Server V623
KGW IBM OMEGAMON for CICS TG on z/OS V560

Exclude any components that you do not want to configure in this runtime environment.
If you plan to monitor CICS regions from the LPAR associated with this runtime environment, then IBM
Z OMEGAMON for CICS is required. If you are connecting your OMEGAMON for CICS agent to a Tivoli
Enterprise Monitoring Server on a distributed platform or a Tivoli Enterprise Monitoring Server that is
configured in another runtime environment, then you can exclude Tivoli Enterprise Monitoring Server
V6.3.0 from this runtime configuration.
If you plan to monitor CICS TG daemons or daemons on the LPAR associated with this runtime
environment, then IBM Z OMEGAMON for CICS is required.
During the PARMGEN runtime environment configuration process for all of the previously mentioned
products, the following component parameters are generated:
• OMEGAMON Subsystem (Optional)
The default STC: IBMCN and the parameter prefix: RTE.
• Tivoli Enterprise Monitoring Server
The default STC: IBMDS and the parameter prefix: KDS

Customizing component parameters with PARMGEN

During the PARMGEN configuration process for IBM Z OMEGAMON for CICS, the following component
parameters will also be generated and configured:
• OMEGAMON enhanced 3270 user interface (default STC): IBMTOM)
• OMEGAMON for CICS (3270) (default STC): IBMOC0)
• OMEGAMON for CICS (default STC): IBMC5)
While all of these components are configured, they do not all need to be started in your runtime
environment.
OMEGAMON for CICS (3270) is the only required started task.

Configuring the OMEGAMON for CICS (3270) component

You configure the OMEGAMON for CICS component to specify parameter values used in common with the
Tivoli Enterprise Monitoring Server.
In addition, you configure the address spaces for optional common components such as OMEGAMON
System and End-to-End Response Time feature, which provides services for both OMEGAMON XE and
OMEGAMON for CICS.
If you do intend to use one of the interfaces, you can optionally specify customize values for the following:

28 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Security
Configuring security for OMEGAMON for CICS (3270) provides authorization of user IDs and password
used for logon. In addition, security can be configured for OMEGAMON for CICS commands. Most of
the configuration is performed outside of the configuration profile. However, if you intend to configure
logon security, you must indicate in the configuration profile what security authorization facility (SAF)
you intend to use. After you complete the configuration profile for the runtime environment and
submit the configuration jobs, complete configuration of logon and command security using the
information in “Securing the OMEGAMON for CICS (3270)” on page 99.
VTAM information
If your agent is using SNA protocol, modify the OMEGAMON for CICS VTAM node and application
definitions.
Historical data collection
The Online Historical Data viewing feature of OMEGAMON for CICS (3270) contains optional
generation of the JCL to allocate online historical data sets for OMEGAMON for CICS (3270).
OMEGAMON for CICS (3270) address space pairs
Monitoring OMEGAMON for CICS (3270) address spaces

Using the KOCSUPDI member in the TKANSAM library

The KOCSUPDI member in the TKANSAM library is a sample default command security table. It is
used by the PARMGEN RTE batch configuration jobstreams, $PARSE/$PARSESV, to build the runtime
environment's default command security table in the RKANMODU library. It can also be used in the
TKANSAM library for sample job KC2JSEC to update an runtime environment's command security table.
WARNING: If you want to make changes to the command security table for a runtime environment, then
the KOCSUPDI member can be copied from TKANSAM library to the runtime environment's RKANSAMU
library and edited there. The KOCSUPDI member in the RKANSAMU library can then be the source input
for updating the runtime environment's command security table in the RKANMODU library.
For more information about this configuration task, see the "How to: Use KOBSUPDT security exits with
PARMGEN" in the Scenarios and how-tos section of OMEGAMON shared documentation Version 6.3.0 Fix
Pack 2.

Modifying VTAM node and application definitions

If your agent will be configured to use the SNA protocol, modify the following OMEGAMON for CICS
(3270) VTAM node and application definitions to meet your installation standards:

IBMOC0 (OMEGAMON for CICS): VTAM is required.

KC2_CC01_CLASSIC_VTAM_APPL_LOGON CTDOC0

For more information on these KC2 parameters, see the IBM OMEGAMON for CICS on z/OS: Parameter
Reference.

Configuring historical data collection

This section will cover the parameters needed for configuration of the optional historical data collection.
Use the KC2_CLA_RTEN_IN_HIST_DSN parameter to generate the ONDV historical data set. Include the
runtime environment name in the RKC2HIST VSAM region task history data set name.
See the KC2_HS* parameters in the IBM OMEGAMON for CICS on z/OS: Parameter Reference for more
information on configuring the parameters for historical collection.

** OMEGAMON for CICS (3270) Optionally generate the JCL to allocate

online historical data sets
KC2_CLA_RTEN_IN_HIST_DSN Y

Chapter 4. Configuring IBM Z OMEGAMON for CICS 29

 Configuring address space pairs
By default there is one OMEGAMON for CICS (3270) address space pair generated, but you can have up to
16 address space pair tables.
One address space can support approximately 40 to 80 concurrent sessions. This number varies,
depending on the region size and other environmental factors. If you experience virtual storage
constraints in OMEGAMON for CICS (3270) due to the number of concurrent sessions, you can generate
multiple address pairs for a z/OS operating system.
This parameter value is stored in the IBMC2x and IBMOCx, started task, where x =0-16 (up to 16 address
space pairs) of the rhilev.rtename.xKANPARU library, where x can be R, W, or I.
You can use $PARSE job processing by running the library-specific $PARSESM IKANCMDU->WKANCMDU
file-tailoring job, to regenerate only the WKANSAMU members that need to be reprocessed. To limit
the update to only members relevant to this component, in the USER SECTION: CONFIG/SELECT
MEMBER section, of the $PARSESM member, update the SELECT MEMBER=(*) statement to SELECT
MEMBER=KC2*.

Configuring the IBM Z OMEGAMON for CICS monitoring agent

You configure the OMEGAMON XE component of the monitoring product to define Sysplex-level entities,
assign the current runtime environment to a Sysplex, install product-specific data on the Tivoli Enterprise
Monitoring Server, and register the IBM Z OMEGAMON for CICS monitoring agent in the Tivoli Enterprise
Monitoring Server address space.
You also configure the persistent data store for the product historical data and allocate the data sets
to store the system-level data. These parameters are specified in the KC5 section of the PARMGEN
configuration profile.
Default values are provided for all required parameters and some optional ones. If you do not want to
customize these parameters, and you do not want to enable optional features, you can complete the
configuration by accepting these defaults.
The first time you configure IBM Z OMEGAMON for CICS into an runtime environment, you should accept
the configuration default values where ever possible. You should consider enabling the self-describing
agent feature prior to connecting the IBM Z OMEGAMON for CICS and IBM Z OMEGAMON for CICS TG
agents to the Tivoli Enterprise Monitoring Server. See the IBM Tivoli Monitoring Administration Guide
Version 6.3.0 for additional information about the self-describing agent.
After you complete the runtime environment configuration and run the product Installation Verification
Program (IVP), then you should consider reviewing the various product features that are available and
adjusting configuration parameters to meet your site's installation requirements.

Modifying VTAM node and application definitions

The IBM Z OMEGAMON for CICS agent (IBMC5) has optional VTAM configuration; review the following
common agent parameter configuration default parameters:

** (Optional) Agent's local VTAM and logon information:

KC5_AGT_VTAM_APPL_PREFIX CTDC5
KC5_AGT_VTAM_NODE CTDC5N
KC5_AGT_VTAM_APPL_OPERATOR CTDC5OR
KC5_AGT_VTAM_APPL_KC5INVPO CTDC5VP
KC5_AGT_VTAM_APPL_NCS CTDC5NC
KC5_AGT_VTAM_APPL_AA CTDC5AA

For more information on these common agent parameters see "Common parameters" in the Reference
section in OMEGAMON shared documentation.
If your agent is configured to communicate to the Tivoli Enterprise Monitoring Server through SNA, then
the following primary Tivoli Enterprise Monitoring Server VTAM configuration values must be supplied:

** Agent's Primary TEMS VTAM information:

KC5_TEMS_VTAM_LU62_DLOGMOD CANCTDCS

30 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 KC5_TEMS_VTAM_LU62_MODETAB KDSMTAB1
KC5_TEMS_VTAM_NETID USCACO01
KC5_TEMS_VTAM_APPL_LLB_BROKER CTDDSLB

For more information on optional local agent VTAM and logon information and primary Tivoli Enterprise
Monitoring Server VTAM configuration values, see OMEGAMON shared documentation and the IBM IBM Z
OMEGAMON for CICS: Parameter Reference.

Updating agent and Tivoli Enterprise Monitoring Server protocols

If you are configuring the agent with the default protocols of IP and IP.PIPE and you modified the
Tivoli Enterprise Monitoring Server port number, you must update the agent parameters. Change all
occurrences of 1918 to your installation assigned Tivoli Enterprise Monitoring Server port number. The
hub, the Tivoli Enterprise Monitoring Server and the connecting agent(s) must all use the same port
number:

KC5_TEMS_TCP_PIPE_PORT_NUM 1918 * IP.PIPE

KC5_TEMS_TCP_UDP_PORT_NUM 1918 * IP.UDP

If you are configuring the agent and Tivoli Enterprise Monitoring Server with a TCP/IP protocol, you will
need to specify the hostname of the Tivoli Enterprise Monitoring Server and the hostname where the
agent is running:

KC5_TEMS_TCP_HOST "hostname"

where hostname is the hostname of the Tivoli Enterprise Monitoring Server that the agent is connecting
to.

KC5_AGT_TCP_HOST "hostname"

Where hostname is the hostname of the system that the agent will be running.

Configuring the IBM Z OMEGAMON for CICS TG component using

the PARMGEN method
The parameters for IBM Z OMEGAMON for CICS TG are specified in the KGW section of the PARMGEN
configuration profile.
Default values are provided for all required parameters and some optional ones. If you do not want to
customize these parameters, and you do not want to enable optional features, you can complete the
configuration by accepting these defaults. Alternatively, you can specify custom values. You can also
specify custom values for optional parameters that have no defaults.
During the PARMGEN configuration process for IBM Z OMEGAMON for CICS TG, the following component
parameter will be generated and configured:
• OMEGAMON for CICS TG (default STC: IBMGW)
The IBM Z OMEGAMON for CICS TG started task (IBMGW) is only required to be started in the runtime
environment, if you are planning to monitor CICS TG daemons.

Modifying VTAM node and application definitions

If your agent will be configured to use the SNA protocol, modify the following OMEGAMON for CICS TG on
z/OS TG VTAM node and application definitions to meet your installation standards:

** Agent's Primary TEMS VTAM information:

KGW_TEMS_VTAM_LU62_DLOGMOD CANCTDCS
KGW_TEMS_VTAM_LU62_MODETAB KDSMTAB1
KGW_TEMS_VTAM_NETID USCACO01
KGW_TEMS_VTAM_APPL_LLB_BROKER CTDDSLB

Chapter 4. Configuring IBM Z OMEGAMON for CICS 31

 ** (Optional) Agent's local VTAM and logon informa
KGW_AGT_VTAM_APPL_PREFIX CTDGW
KGW_AGT_VTAM_NODE CTDGWN
KGW_AGT_VTAM_APPL_OPERATOR CTDGWOR
KGW_AGT_VTAM_APPL_KGWINVPO CTDGWVP
KGW_AGT_VTAM_APPL_NCS CTDGWNC
KGW_AGT_VTAM_APPL_AA CTDGWAA

For more information on optional local agent VTAM and logon information and primary Tivoli Enterprise
Monitoring Server VTAM configuration values, see OMEGAMON shared documentation and the IBM Z
OMEGAMON for CICS: Parameter Reference.

Updating agent and Tivoli Enterprise Monitoring Server protocols

If you are configuring the agent with the default protocols of IP and IP.PIPE and you modified the
Tivoli Enterprise Monitoring Server port number, you must update the agent parameters. Change all
occurrences of 1918 to your installation assigned Tivoli Enterprise Monitoring Server port number. The
hub, the Tivoli Enterprise Monitoring Server and the connecting agent(s) must all use the same port
number:

KGW_TEMS_TCP_PIPE_PORT_NUM 1918 * IP.PIPE

KGW_TEMS_TCP_UDP_PORT_NUM 1918 * IP.UDP

If you are configuring the agent and Tivoli Enterprise Monitoring Server with a TCP/IP protocol, you will
need to specify the hostname of the Tivoli Enterprise Monitoring Server and the hostname where the
agent is running:

KGW_TEMS_TCP_HOST "hostname"

where hostname is the hostname of the Tivoli Enterprise Monitoring Server that the agent is connecting
to.

KGW_AGT_TCP_HOST "hostname"

where hostname is the hostname of the system that the agent will be running.
When you are done modifying the VTAM node and application definitions, complete the manual
configuration steps outlined in Completing the configuration.

Completing the configuration

After you configure IBM Z OMEGAMON for CICS using your preferred configuration method, you must
complete several post-configuration steps. The post-configuration steps that you must complete are
a combination of required steps and optional steps that depend on your particular configuration and
monitoring objectives.

Table 8. Steps to complete the configuration

Step Requirement / Context
“Copying started task procedures and VTAM Required for all configurations
definitions to your procedure library and VTAMLST
system” on page 33
“Varying the VTAM major node active” on page 34 Required for all configurations
“Granting APF authorization for the runtime load Required for all configurations
libraries” on page 34
“Completing the configuration for OMEGAMON for Required only for the OMEGAMON for CICS Classic
CICS” on page 34 interface

32 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 Table 8. Steps to complete the configuration (continued)
Step Requirement / Context
“Completing the configuration for OMEGAMON for Required for all configurations
CICS TG” on page 43
“Completing the configuration for IBM Z Required only for OMEGAMON for CICS Transaction
OMEGAMON for CICS TG” on page 43 Gateway on z/OS

If you run the WKANSAMU(KCIJcSYS) job (where c = P if SYSV is not enabled; V if SYSV is enabled),
all the started tasks and VTAM major nodes are copied to the system libraries specified for the
GBL_DSN_SYS1_* parameter in the configuration profile. If you are using the global VTAM node
(RTE_VTAM_GBL_MAJOR_NODE parameter), you can use the WKANSAMU(ccccAPF) imbed member to
VARY the node and APF authorize the load libraries. To use ccccAPF, uncomment the placeholder INAPF
INCLUDE statement in each started task:

//******************************************************************
//* Uncomment out the INAPF statement if are using this composite
//* member to APF-authorize the libraries concatenated in the
//* STEPLIB and RKANMODL DDNAMEs.
//*INAPF INCLUDE MEMBER=IBMAPF

If you are using a local node, you must VARY the node active and authorize the libraries yourself.
Running the WKANSAMU(KCIJcSYS) job means you do not have to do the tasks that can be completed for
every product, above.
Finally, perform the following tasks:

Table 9. Post-configuration steps

Step Requirement / Context
“Verifying the configuration” on page 49 Required for all configurations
“Enabling security” on page 54 Required for all configurations
“Installing language support” on page 54 Required for all configurations

Copying started task procedures and VTAM definitions to your procedure

library and VTAMLST system
During the configuration, a number of started task procedures and VTAM definitions were created in the
&rhilev.&rte.RKANSAMU data set.
Note: If you are using Configuration Manager, this task is made simpler than it is with PARMGEN,
because Configuration Manager isolates all STC members and VTAM definitions created in a specific
data set (<RTE_PLIB_HILEV>.SYS1.PROCLIB / <RTE_PLIB_HILEV>.SYS1.VTAMLST/LIB, via the
GENERATE action, so that you can copy them from there to the PROCLIB/VTAMLST.
If you have not already done so, you must copy the started task procedures to your procedure library and
the VTAM major node (C5B0C20N) to your system VTAMLST using the JCL job.
To copy the procedures using the JCL job, do the following:
Submit the KCIJPSYS JCL job, to copy runtime members to system libraries. Edit the JCL if required
and submit the job. Expect a return code of zero. This action generates a member called KCISYPJB in
&rhilev.&rte.RKANSAMU library.
The composite KCIJPSYS system-related set-up job copies the started tasks, VTAM major node members,
and health check elements for the products and components into system libraries. Next, the job
assembles and links product modules into system libraries.

Chapter 4. Configuring IBM Z OMEGAMON for CICS 33

 Issue the KCISYPJB JCL from a user that has authority to the PROCLIB data set. Be careful not to
overwrite any members in the data set that have already been modified. If necessary, copy the started
task procedures manually.
In the code, you can see the names of the started tasks created during the configuration. These are
started tasks for the components in OMEGAMON for CICS on z/OS:
• OMEGAMON for CICS (3270) - IBMOC0
• OMEGAMON for CICS on z/OS - IBMC5
• OMEGAMON for CICS TG on z/OS - IBMGW
• OMEGAMON Subsystem - IBMCN

Varying the VTAM major node active

The VTAM major node is created in the RKANSAMU library and copied to your system VTAMLST.
To vary the VTAM major node in VTAMLST active, enter the following entry:

V NET,ACT,ID=nodeid

Granting APF authorization for the runtime load libraries

The runtime load libraries created during configuration must be added to the list of APF-authorized
libraries.
If you have not already done so, add the following runtime load libraries to your list of APF-authorized
libraries:
• &rhilev.RKANMOD
• &rhilev.RKANMODU
If you are only running from a runtime environment data set you need to also add these libraries:
• &rhilev.RKANMOD
• &rhilev.RKANMODU
• &rhilev.RKANMODL
If the runtime environment shares with SMP/E targets, you will also need to add:
• &thilev.TKANMOD
• &thilev.TKANMODL
• &thilev.TKANMODP
All runtime libraries concatenated in the STEPLIB DDNAME and in the RKANMODL DDNAME of any started
tasks must be APF-authorized.

Completing the configuration for OMEGAMON for CICS

These are additional tasks required to complete the configuration.

Using INITPARM instead of CICS JCL changes

IBM Z OMEGAMON for CICS lets you minimize the JCL changes to monitored CICS regions.
Add a LIBRARY definition for the hilev.xKANMODR load library. Member hilev.TKANSAM(KOCCSD)
contains an example. During initialization processing OMEGAMON dynamically allocates the
hilev.xKANMOD equivalents of the load libraries that are allocated to the new LIBRARY. hilev.xKANMOD
must be APF authorized.

34 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Modify the CICS region INITPARM data to provide the new definitions. In the example that follows, the
INITPARM data used in OMEGAMON for CICS is shown here:

INITPARM=(DFHDBCON='CC,IC1C',
KOCOME00='RETRY(tt,cc),KC2_XMIT=nn,KCP_XMIT=nn,KC2_GLOBAL=cc')

The parameters passed to KOCOME00 in this example are as follows:

Table 10. Parameters that can be passed on the INITPARM

Parameter Meaning
RETRY(tt,cc) Specifies the behavior of OMEGAMON when the common interface is
not available. OMEGAMON will attempt to connect to the common
interface every tt seconds, for a maximum of cc times. Specifying
RETRY(tt) means that the retries occur on the specified interval, with
no limit. This parameter is optional and can be used to replace the
OCCIREQ DD function.
KC2_XMIT=nn The equivalent of the RKC2XMnn DD card, previously specified as a
DUMMY DD. The value of nn must be between 00 and 15. The default
is 00. This card controls the common interface region that this CICS will
establish a monitoring session with
KCP_XMIT=nn The equivalent of the RKCPXMnn DD card, previously specified as a
DUMMY DD. The value of nn must be between 00 and 15. The default
is 00. This card controls which IBM Z OMEGAMON for CICS agent this
CICS will establish a monitoring session with.
KC2_GLOBAL=cc The equivalent of the KC2GLBcc DD card that was previously specified
as a DUMMY DD. The card specifies a global data area that is used to
specify the monitoring options for your CICS region or regions.
LIST The LIST parameter is used to control the display of diagnostic
messages. Typically these messages will only be requested by IBM
Software Support.

The parameters are used to generate DD cards which are dynamically allocated, thus removing the
requirement for JCL changes in your CICS regions.
An additional benefit of the new feature is that it offers the ability to dynamically change your definitions
while CICS is running. If you started OMEGAMON in CICS with a KC2_GLOBAL=51 and realized later that
you meant to use KC2_GLOBAL=52 you can now make the change dynamically. You would need to ensure
that all sessions which are monitoring the target CICS region are ended, and then recycle OMEGAMON
from a terminal or console by entering the following commands:

OMEG REMOVE

To stop OMEGAMON, followed by an INIT request which specifies the new global parameter:

OMEG INIT,KC2_GLOBAL=52

Alternatively you can use the OMEG RECYCLE command which is a combination of a REMOVE followed by
a RECYCLE:

OMEG RECYCLE,KC2_GLOBAL=52

You could also, if necessary, add the LIST option:

OMEG INIT,KC2_GLOBAL=52,LIST

Since the REMOVE step dynamically deallocates the existing DD cards, as well as the RKANMOD load
library concatenation you can also dynamically add maintenance to your regions.

Chapter 4. Configuring IBM Z OMEGAMON for CICS 35

 If you performed the following steps:
1. OMEG REMOVE
2. Disable the OMEGAMON LIBRARY definition, and DISCARD it.
3. Make any required changes to the LIBRARY definition.
4. INSTALL the modified LIBRARY definition
5. OMEG INIT
Then you would be able to execute OMEGAMON for CICS from a new set of load libraries, so that you
would be able to implement maintenance without recycling CICS.

Modifying the JCL for the CICS region

Important: You do not need to perform this step if you plan to use INITPARM, which minimizes the JCL
changes that are required.
The JCL for the CICS region being monitored by IBM Z OMEGAMON for CICS must be modified.
Add the KOCOME00 program and the OMEG transaction to the CICS region and add the OMEGAMON
libraries to the JCL for the CICS region you are monitoring.
Add a DD statement for the RKANMOD data set and concatenate the &thilev.TKANMODR load library, to
the CICS DFHRPL DD statement as shown in the following example:
Note: These examples are based on runtime environments that are running from SMP/E libraries.
From:

//DFHRPL DD
DISP=SHR,DSN=cics.hilev.SDFHLOAD

To:

//DFHRPL DD DISP=SHR,DSN=cics.hilev.SDFHLOAD
// DD DISP=SHR,DSN=&thilev.TKANMODR

Add a DD statement for the RKANMOD library:

//RKANMOD DD DISP=SHR,DSN=&thilev.TKANMOD

If any data set in the RKANMOD DD allocation is not APF authorized, the OC1036 message is issued and
OMEGAMON fails to initialize in the CICS region. If the RKANMOD DD is not found in the CICS region JCL,
the standard z/OS system library search order is used and LINKLST is searched.
Any runtime libraries concatenated in the STEPLIB DDNAME of the IBMOC0 started task must be APF
authorized. Add the KOCOME00 program and the OMEG transaction.
If your security system restricts data set access, your security administrator must give the OMEGAMON
for CICS (3270) started task (default IBMOC0) and the CICS regions read access to the &RHILEV or
&THILEV high-level qualifier.

Modifying the CICS tables

To use all the facilities of OMEGAMON for CICS, you must install OMEGAMON for CICS in the CICS address
space. This section explains how to modify the CICS tables.

System Initialization Table

Verify that your System Initialization Table (SIT) specifies one of the following parameters:
• BMS=STANDARD
• BMS=FULL (The CICS default)

36 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Note: The OMEG SHUT command does not run with the BMS=MINIMUM parameter.
Specify one of the following parameters:
• MCT=YES
• MCT=NO (The CICS default)
• MCT=cc, where cc is the suffix of your Monitoring Control Table (MCT)
• INITPARM data can be added if you want to minimize the JCL changes that are required.
The following is an example of a system initialization (INITPARM) statement:

INITPARM=(KOCOME00='RETRY(tt,cc),KC2_XMIT=nn,KCP_XMIT=nn,KC2_GLOBAL=cc')

Where:
RETRY(tt,cc)
Specifies an interval in seconds (tt) and the maximum counts (cc) at which OMEGMON II for CICS
attempts to connect to the common interface in the event that CICS is initialized before the common
interface (KOCCI). For example, RETRY(30,20), would result in an attempt to reconnect every 30
seconds, up to 20 times. The parameter is optional.
KC2_XMIT=nn
Is the equivalent of the RKC2XMnn DD statement. nn is a value between 00-15 inclusive.
KCP_XMIT=nn
Is the equivalent of the RKCPXMnn DD statement. nn is a value between 00-15 inclusive.
KC2_GLOBAL=cc
Is the equivalent of the KC2GLBcc DD statement (or the older KOCGLBcc DD statement). cc can be
any valid character used to designate a member of a partitioned data set.

Program List Table

The following example shows the Program List Table (PLT) additions for an installation:

DFHPLT TYPE=ENTRY,PROGRAM=KOCOME00

Specify the PLT additions, as shown, in the following tables:

• PLTPI (initialization) immediately after the DFHDELIM entry for the CICS Transaction Server systems
• PLTSD (shutdown) before the DFHDELIM entry.

Monitoring Control Table

In prior releases of OMEGAMON for CICS, individual event monitoring points (EMP) for OMEGAMON
basic data, DB2®, DLI, MQ, Workload manager and User Defined Events were required to make the data
available, both to the OMEGAMON features listed previously, and for system management facility (SMF)
processing. With OMEGAMON for CICS V5.3.0 and higher, the OMEGAMON EMPs are required only if you
want to write this data to SMF.
The data required for ONDV, RTA, and Service Level Analysis is available even when the Monitoring
Control Table (MCT) entries are not defined.
For the CICS Transaction Server, you must define user event monitoring points in your MCT, if you want to
create user reports from SMF data for the following instances:
• Details about one or more of the following items:
– Umbrella program names when you are using umbrella transaction services
– Certain fourth generation language products
– File and database I/O detail statistics (only if you want this data written to SMF)
• DL/I usage per transaction

Chapter 4. Configuring IBM Z OMEGAMON for CICS 37

 • DB2 usage per transaction
• z/OS Workload Manager data
• Task history data
• Message queueing (MQ) file-level statistics
The OMEGBSC segment is supplied, which you define in the MCT to collect resource information. Use
the OMEGBSC segment, if you want to collect resource information, and you are not concerned about
the additional overhead caused by collecting data your site might not need. You only need OMEGBSC in
the MCT, if you want this data sent to SMF. It is sent to ONDV and the other sub tasks regardless of the
presence of the EMPs in the MCT.
Define the OMEGBSC segment, if you want this data in the SMF 110 record and available for post-process.
Use the sample MCT entry shown in Figure 3 on page 39. You must be careful not to exclude fields that
OMEGAMON for CICS might need. Sample MCTs are shipped in the rhilev.TKANSAM(KOCMCTxx) data set.
These are the sample MCTs:
• DFHMCT64
• DFHMCT65
• DFHMCT66
• DFHMCT67
These are the CICSPA equivalent samples:
• DFHMCTP4
• DFHMCTP5
• DFHMCTP6
• DFHMCTP7
For instructions on excluding records, see the CICS Transaction Server Resource Definition Guide, and look
for information on the DFHMCT TYPE=RECORD definition, and the EXCLUDE and INCLUDE operands.
An example of MCT additions for installation:

38 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 DFHMCT TYPE=INITIAL
* User-Event Monitoring Point for the basic section
*
* Required for file level statistics and GMT offset time in
* each transaction record.
*
* The value you specify for the ID parameter excluding the ‘.1' must match
* the BASIC parameter for the STARTUP_CONTROL in the Global Data Area.
*
DFHMCT TYPE=EMP,
CLASS=PERFORM,
ID=(OMEGBSC.1),
FIELD=(1,OMEGBSC),
PERFORM=(MOVE(0,132)) Note: The first number is zero.
*
* User-Event Monitoring Point for the DL/I section
*
* Required for task level DL/I statistics
*
* The value you specify for the ID parameter excluding the ‘.1' must match
* the DLI parameter for the STARTUP_CONTROL in the Global Data.
*
DFHMCT TYPE=EMP,
CLASS=PERFORM,
ID=(OMEGDLI.1),
FIELD=(1,OMEGDLI),
PERFORM=(MOVE(0,92)) Note: The first number is zero.
*
* User-Event Monitoring Point for the DB2 section
*
* Required for task level DB2 statistics
*
* The value you specify for the ID parameter excluding the ‘.1' must match
* the DB2 parameter for the STARTUP_CONTROL in the Global Data..
*
DFHMCT TYPE=EMP,
CLASS=PERFORM,
ID=(OMEGDB2.1),
FIELD=(1,OMEGDB2),
PERFORM=(MOVE(0,100)) Note: The first number is zero.
* and the last number is one hundred.
*
* User-Event Monitoring Point for z/OS workload manager values
*
* Required to hold the service class name and token for WLM
* collection.
*
DFHMCT TYPE=EMP,
CLASS=PERFORM,
ID=(CANWLMSC.1),
FIELD=(1,CANWLMSC),
PERFORM=(MOVE(0,16)) Note: The first number is 0
* User-Event Monitoring Point for MQ file-level statistics
*
* Required to implement MQ file-level statistics
*
DFHMCT TYPE=EMP,
CLASS=PERFORM,
ID=(CANMQ.1)
FIELD=(1,CANMQ),
PERFORM=(MOVE(0,76))
*

Figure 3. MCT additions for installation

You can change the entry name specified on the ID operand, but you must define each entry name in the
<USER_EVENT_MONITORING> section of the Global Data Area. For example, BASIC_SECTION=youremp.
Define only those event monitoring points that you require to reduce the overhead in CICS during
monitoring.

Reducing data collection overhead

At the end of each performance record, there is a single entry for each of the following types of data:
• Basic (OMEGBSC)

Chapter 4. Configuring IBM Z OMEGAMON for CICS 39

 • DL/I (OMEGDLI)
• DB2 (OMEGDB2)
• z/OS Workload Manager (CANWLMSC)
• Message queueing (CANMQ)
• User Defined Events (CANUE1)
The OMEGBSC segment consists of 132 bytes. Because no site uses all fields, excess disk space is
required to store the unneeded data, which causes excess overhead, especially for sites that generate
very large quantities of CICS transactions.
The OMEGAMON MCT entries are not required unless the customer specifically wants the data available
for post processing.

Tailoring OMEGBSC data

You can tailor OMEGBSC data by modifying the KOCBSC member in the thilev.TKANSAM library.
This member contains the field definitions for all the individual fields in the OMEGBSC segment. When
assembling the MCT, use this member to specify the types of performance data to be collected.

Including all fields

If you want to tailor your data collection, copy the KOCBSC data set member to your MCT and delete the
unneeded fields.
Take the following usage points into account:
• Do not define the OMEGBSC EMP in the MCT and choose some of the individual fields. (If you do both,
you will collect duplicate data.)
• If you use the KOCBSC data set member in your MCT, do not change the BASIC_SECTION=entry in the
USER_EVENT_MONITORING section of the Global Data Area.
• If you do not use the entire OMEGBSC segment, and, if you use non-IBM programs (for example, SAS) to
read and report on SMF records, these non-IBM programs might require modification.

Limiting the CICS regions being monitored

Attention: This step is not required if you supplied these values using a DD card and the INITPARM
parameter. See “System Initialization Table” on page 36 for information about INITPARM.
After completing the required CICS JCL changes, you can limit the CICS regions being monitored by
adding the following DD statement to the CICS region JCL and the OMEGAMON for CICS (3270) started
task JCL:

//RKC2XMnn DD DUMMY

where:
nn is a number between 00 and 15.

Defining the OMEGAMON for CICS (3270) program and transaction

This section contains information about using the CICS-supplied CEDA transaction to define the program
and transaction. The program and transaction manage the interface between OMEGAMON for CICS
(3270) and CICS.
The OMEGAMON definitions are contained in the hilev.TKANSAM library, and the KOCCSDJ member
contains the sample JCL to run DFHCSDUP, the CICS system definition utility program in batch mode to
add those definitions to your CICS system definition (CSD) files.
An alternative to using the provided JCL would be to add the definitions with the CEDA transaction as
defined in the following section.

40 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

OMEGAMON for CICS (3270) program
Follow these steps in customizing the CEDA definition for the OMEGAMON for CICS (3270) program:
1. Specify KOCOME00 as the program name.
2. Specify Assembler as the language.
3. Specify CMDSEC=NO and RESSEC=NO on the CEDA definition for the OMEG transaction.
4. In addition, if you have XPPT=YES in your system initialization table (SIT), you must also define the
KOCOME00 program as a resource to your external security manager.
5. In addition, if you have STGPROT=YES in your SIT, you must also specify EXECKEY(CICS) on the
CEDA definition for the KOCOME00 program.
6. Verify that you have CONCURRENCY(THREADSAFE) specified on the CEDA definition of the KOCOME00
program.
7. All other values can be allowed to use the default settings.

OMEGAMON for CICS (3270) transaction

Follow these steps in customizing the CEDA definition for the OMEGAMON for CICS (3270) transaction:
1. For the transaction ID, specify OMEG or another 1 - 4 character ID.
2. Specify TRANCLASS(NO).
3. In addition, if you have STGPROT=YES in your SIT, you must also specify TASKDATAKEY(CICS) on the
CEDA definition for the OMEG transaction.
4. Specify SPURGE(NO) and DTIMOUT(NO) to prevent AEXY abend code.
5. All other values can be allowed to use the default settings.
You can use OMEG as the OMEGAMON for CICS (3270) transaction ID to help make problem
determination/diagnosis and maintenance simpler. You can, however, choose a different ID, if necessary
for business or administrative reasons. If you use another transaction ID, substitute that ID wherever the
OMEG transaction is mentioned in this guide.
If you do not define TCLASS as NO, the transaction might not run, and many OMEGAMON for CICS (3270)
functions will be unavailable.
To avoid confusion, use only one transaction ID to run the KOCOME00 program.
If initialization fails, OMEGAMON for CICS (3270) initialization within CICS stops, and message OC1029
is issued, only if a valid transaction ID associated with the KOCOME00 program cannot be found. If this
is the case, you have either failed to define the OMEGAMON for CICS (3270) transaction or defined the
transaction incorrectly.

Ensuring the OMEGAMON for CICS (3270) address space is started before CICS
attempts to initialize OMEGAMON in the CICS region
If the OMEGAMON for CICS (3270) address space is not started before CICS is started and initialized,
some features of the product will be unavailable.
To ensure that the OMEG transaction successfully connects to the OMEGAMON for CICS (3270) address
space regardless of the order in which the CICS and OMEGAMON for CICS (3270) address spaces are
started, use the following features:
• OMEGAMON RETRY parameter
Add the KOCOME00='RETRY(hhmmss)' parameter to the CICS System Initialization Parameter,
INITPARM, so that the OMEG transaction attempts to connect to the OMEGAMON for CICS (3270)
address space at the specified interval.
To cancel the RETRY processing, use the OMEG CANCEL command.

Chapter 4. Configuring IBM Z OMEGAMON for CICS 41

 The RETRY parameter has the format KOCOME00='RETRY(hhmmss,nnnnnn)', where hhmmss is the
RETRY interval, in the range 1 second to 23 hours, 59 minutes, 59 seconds and nnnnnn is a RETRY
count. The nnnnnn RETRY count value can be specified between 1 and 999999; there is no default retry
interval. If an error is detected during processing of the RETRY parameter, error messages are issued.
In this event, an attempt to connect to the OMEGAMON for CICS (3270) address space is made, but no
further RETRY attempts are made.
If you specify a time with no count, the connection to the OMEGAMON for CICS (3270) address
space is retried indefinitely at the specified interval. For example, KOCOME00='RETRY(30)' will
retry the connection to the OMEGAMON for CICS (3270) address space every 30 seconds, and
KOCOME00='RETRY(001000,100) will retry the connection to the OMEGAMON for CICS (3270)
address space 100 times every 10 minutes.
For example:

INITPARM=(DFHDBCON='9I,I91C',KOCOME00='RETRY(30)')

Messages are issued when a RETRY attempt is made, and, if a limit is placed on these attempts based
on using a RETRY count value. If you use the OMEG CANCEL command to stop the RETRY process, a
message is issued. The OMEG CANCEL command messages include a successful cancel message, and
a no retry process message. A message is also issued if the START request fails for any reason. See
the Troubleshooting Guide for the complete list of messages for the RETRY parameter starting with the
KCP1040I message.
It is now possible to enable the CICS address space to finish initialization and connect to the KOCCI
STC whenever it becomes available. This approach, developed in response to customer requests and
introduced in V4.2.0, uses the RETRY parameter and is specified in the CICS INITPARM data. Using this
parameter, you can specify an interval and a retry count. When OMEGAMON is initialized in the CICS
address space, the agents attempts to establish a connection to the KOCCI STC. If the KOCCI STC is not
available at that time and the RETRY parameter is specified, the OMEGAMON initialization code waits
for the specified interval and, optionally, makes the specified number of retry attempts to establish the
connection. This new processing allows CICS initialization to proceed, regardless of whether the code is
executed during PLT processing or as a result of operator input from a CICS terminal session.
In this example:

INITPARM=(DFHDBCON='CC,IC1C',KOCOME00='RETRY(30,20)')

The RETRY parameter specifies that the connection will be retried every 30 seconds, for a maximum of
20 attempts. The parameter is defined as RETRY (tt,cc) where tt is an interval in seconds and cc is the
maximum attempts that will be made.
This parameter can also be specified as RETRY(tt), in which case the initialization attempts continue
indefinitely or until you cancel the process.
The RETRY parameter can generate these messages to the MVS™ console that indicate the progress of
the RETRY processing. If the OMEG INIT command is entered from a CICS terminal, the messages are
displayed there also. The sample command shown earlier results in this message:

KCP1040I OCOMEG OMEGAMON FOR CICS WILL RETRY: INTERVAL 000030 COUNT 000020

If the RETRY count is reached, this message is issued:

KCP1042I OCOMEG OMEGAMON FOR CICS RETRY LIMIT REACHED

You can use the CANCEL option of the OMEG command to cancel the RETRY process. Entering OMEG
CANCEL results in the following message:

KCP1047E OCOMEG OMEGAMON FOR CICS RETRY PROCESSING HAS TERMINATED

Messages are also issued if the INITPARM data is specified incorrectly

• OCCIREQ DD statement

42 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 If you include the KOCOME00 program in your PLTPI, you can ensure that the OMEGAMON for CICS
(3270) address space is active before your CICS region completes initializing by adding the following DD
statement to the CICS startup JCL:

//OCCIREQ DD DUMMY

After you add the DD statement, the KOCOME00 program validates that the OMEGAMON for CICS
(3270) address space is active and initialization continues. If OMEGAMON for CICS (3270) is not active,
the following WTOR message is displayed, stopping CICS initialization, pending an operator response:
OC0806:XMCR OCCIREQ SPECIFIED IN THE STARTUP JCL BUT RKC2XMnn
NOT ACTIVE. REPLY ABEND, IGNORE, OR RETRY.

In this message, nn is replaced by the suffix specified in the //RKC2XMnn DD DUMMY statement in the
CICS startup JCL, or, if no suffix was specified, by the default setting (00).

Completing the configuration for OMEGAMON for CICS TG

These are additional tasks to complete the configuration of IBM Z OMEGAMON for CICS TG.

Enabling warehouse agents on a z/OS hub monitoring server

If you want to store long-term history data in the Tivoli Data Warehouse and your hub monitoring server
is on a z/OS system, and have not enabled the self-describing agent feature, then you must manually
transfer the catalog and attribute files for the Warehouse Proxy agent and the Summarization and Pruning
agent to the hub using Manage Tivoli Monitoring Services.
For more information on transferring catalog and attribute files and historical data store see the IBM Tivoli
Monitoring: Installation and Setup Guide and the OMEGAMON shared documentation.

Adding application support to a non self-describing agent enabled hub

monitoring server
This section describes how to add application support to a non self-describing agent enabled hub
monitoring server on the z/OS operating system. This section does not apply if you have the self-
describing agent feature enabled.
If have you enabled self-description at the hub Tivoli Enterprise Monitoring Server, when you start the an
self-describing enabled agent, then self-description processing will start when the agent comes online to
the Tivoli Enterprise Monitoring Server. See the IBM Tivoli Monitoring Administrator's Guide for additional
information regarding self-description processing.
Before you manually add application support to the Tivoli Enterprise Monitoring Server, verify that the
support for the z/OS-based products is installed and available with Tivoli Enterprise Portal Server (the
same versions of the z/OS-based products are installed and available with Tivoli Enterprise Portal Server.
When you install support for the products on Tivoli Enterprise Portal Server, you install the files that the
Tivoli Enterprise Portal Server requires for presenting data and well as the files required to seed the hub
Tivoli Enterprise Monitoring Server on your computer.
For more information, see the section on adding application support to a monitoring server on z/OS in the
OMEGAMON shared documentation.

Completing the configuration for IBM Z OMEGAMON for CICS TG

These are additional tasks required to complete the configuration of IBM Z OMEGAMON for CICS TG.

Chapter 4. Configuring IBM Z OMEGAMON for CICS 43

 Post installation configuration for transaction monitoring support
Depending on whether you are monitoring transactions through a Gateway daemon or through a
WebSphere Application Server with OMEGAMON for CICS TG on z/OS, you must take specific steps to
complete the configuration after installation.
Use the following steps to complete the post-installation configuration, when monitoring transactions
through a Gateway daemon:
1. Add TxnMonitor to the list of registered request exits. You can add the TxnMonitor by directly editing
the CTG.ini configuration file in a text editor.
Use the following text to successfully add TxnMonitor to list of registered exits:

requestexits=com.ibm.omegamon.kgw.rmexit.TxnMonitor

2. Update the CLASSPATH environment variable and STEPLIB concatenation. If you are running CICS TG
in batch mode, edit the STDENV file. If you are starting CICS TG from UNIX System Services (USS), edit
the ctgenvvar script.
Edit either mode to include the following entries:

CLASSPATH=existing_statements:install_path/kan/bin/IBM/kgw_monitor.jar

STEPLIB=existing_statements:&thilev.TKANMODP

For example:

CLASSPATH=&hfsdir/usr/lpp/kan/bin/IBM/kgw_monitor.jar

or

STEPLIB=DFH.V5R1M0.CICS.SDFHEXCI:&thilev.TKANMODP

Note: If your runtime environment is running from SMP target libraries, specify &thilev.TKANMODP.
Otherwise, specify the &rhilev.RKANMODP runtime library.
When monitoring transactions through a WebSphere Application Server:
1. Update the CLASSPATH environment variable used by the CICS resource adapter. In the administrative
console, click Resource Adapters, and then click the CICS resource adapter that was deployed.
Under General Properties for the configuration of the resource adapter, add the following statement for
the CLASSPATH variable:

install_path/kan/bin/IBM/kgw_monitor.jar

2. Give WebSphere Application Server access to the OMEGAMON modules (KGWMONnn). The
WebSphere Application Server that uses the CICS resource adapter needs to load the modules from
KANMODP library.
To perform this action, add the KANMODP library to either the system link concatenation or to the
STEPLIB concatenation of the WebSphere Application Server servant region.
Note: If your runtime environment is running from SMP target libraries, specify &thilev.TKANMODP.
Otherwise, specify the &rhilev.RKANMODP runtime library.
To do this, add the KANMODP library to either the system link concatenation or to the STEPLIB
concatenation of the WebSphere Application Server servant region.
3. Add the TxnMonitor to each J2C connection factory you want to monitor.
a. Select Resource Adapters > J2C connection factories > connection_factory_name > Custom
properties.
b. Modify the RequestExits property to include the following entry:

44 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 Value=com.ibm.omegamon.kgw.rmexit.TxnMonitor

Finding the OMEGAMON TxnMonitor exit (kgw_monitor.jar) after product install

If you need to determine the UNIX System Services (USS) path to the SMP/e installed TxnMonitor exit in
CICS TG (file kgw_monitor.jar), you can use the following instructions to find the exit.
1. Logon to OMVS with your TSO User ID.
2. At the prompt, change directory to the root. For example:

SNEZA:/u/sneza>cd /
SNEZA:/>

3. Issue the following command at the root. Note that there is a space between find and the period, and
a space after the period and before -name. There is also a space between -name and the file name or
kgw_monitor.jar:

SNEZA:/>find . -name kgw_monitor.jar

The above command should find the file and return the path to the file name. For example:

./TDCICST/gw510/dev/usr/lpp/kan/bin/IBM/kgw_monitor.jar

4. Finding the File system name and Mount point:

To find the File system name and Mount point, you can use the ISPF shell (ISHELL) or the z/OS system
console.
• To find the File system name and Mount point using ISHELL, do the following:
a. Exit the OMVS session and while in ISPF issue

TSO ISHELL

b. Once in ISHELL, cut and paste the path that you found in step 3 to the ISHELL panel. This
examples shows a display of the USS ISPF Shell:

File Directory Special_file Tools File_systems Options Setup Help

--------------------------------------------------------------------------
UNIX System Services ISPF Shell

Enter a pathname and do one of these:

- Press Enter.
- Select an action bar choice.
- Specify an action code or command on the command line.

Return to this panel to work with a different pathname.

More: +
/TDCICST/gw510/dev/usr/lpp/kan/bin/IBM/kgw_monitor.jar
________________________________________________________________
________________________________________________________________
________________________________________________________________

c. Select the File option from the pull-down menu. This pop-up window is displayed:

Chapter 4. Configuring IBM Z OMEGAMON for CICS 45

 File Directory Special_file
-------------------------------------
1. New(N)...
2. Attributes(A)...
3. Delete(D)...
4. Rename(R)...
5. Edit(E)...
6. Browse text(B)...
7. Browse records(V)...
8. Copy to(C)...
9. Replace from(I)...
10. Print(P)
11. Compare(M)...
12. Find strings(F)...
13. Run(X)...
14. Link...
15. File system(U)...
16. Edit records(G)...
-------------------------------------

d. Select 15 (File system). This action causes the File System Attributes pop-up window to be
displayed. This window shows the File system name and Mount point:

-------------------------------------------------------------
File System Attributes

File system name:

OMVS.TDCICST.GW510.HFS
Mount point:
/TDCICST/gw510
More: +

Status . . . . . . . . : Available
File system type . . . : ZFS
Mount mode . . . . . . : R/W
Device number . . . . : 54
Type number . . . . . : 1
DD name . . . . . . . :
Block size . . . . . . : 1024
Total blocks . . . . . : 21600
Available blocks . . . : 20961
Blocks in use . . . . : 639

-------------------------------------------------------------

• To find the File system name and Mount point using the z/OS console Display command, do the
following:
a. Go to the z/OS console and enter the following z/OS console command:

D OMVS,F

In the resulting output, find the path that was discovered in step 3. For example:

FIND /TDCICST/gw510

b. If you already know the File system name, then you can use the following z/OS console Display
command instead of D OMVS,F to display the information:

D OMVS,F,N=OMVS.TDCICST.GW510.HFS

The resulting output should be similar to this:

RESPONSE=SYSG
BPXO045I 12.59.48 DISPLAY OMVS 904
OMVS 000F ACTIVE OMVS=(00)
TYPENAME DEVICE ----------STATUS----------- MODE MOUNTED LATCHES
ZFS 54 ACTIVE RDWR 07/29/2012 L=67
NAME=OMVS.TDCICST.GW510.HFS 06.14.36 Q=0
PATH=/TDCICST/gw510
OWNER=SYSA AUTOMOVE=Y CLIENT=N

46 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Monitoring CICS TG daemons bound to a TCPIP stack other than the one
OMEGAMON for CICS TG Agent is bound to
On the same z/OS LPAR, when the OMEGAMON for CICS TG Agent is not bound to the same TCPIP stack
as is the monitored Gateway daemon, the agent must be provided with the IP address or hostname where
the Gateway daemon is active, so that a successful remote connection can be established and statistical
information can be collected.
Define the hostname or IP address of your Gateway daemon using the KGW_SAnn_CTG_DAEMON_HOST
parameter during configuration.
Note: The value for this parameter should be equivalent to the value for the Bind= parameter, as
specified in CICS TG configuration file (ctg.ini).
After successful completion of the reconfiguration, review the KGWSAPIP member in the
&rhilev .RKANPARU data set. Verify that your newly defined INCLUDE statement has been added:

INCLUDE=(jobname,statsport,bindaddress)

Defining a policy to periodically sweep away any orphaned transactions

(optional)
The transaction monitoring component of OMEGAMON for CICS TG keeps a table of all currently active
transactions to calculate average response times and identify long-running transactions.
Occasionally, the CICS TG may not inform OMEGAMON that a transaction has completed, and the agent
is unaware that it should remove the transaction record from the active transactions table. We refer
to this as an orphaned transaction record. The likely cause of an orphaned transaction is an abnormal
termination of a flow, such as a client application disconnecting from the CICS TG when CICS resources
are pending changes and no commit or roll-back call is made.
An orphaned transaction record can affect accurate calculations of response times and give a misleading
impression that there is a problem with slow transactions within a CICS TG. To avoid reporting orphaned
transactions, the OMEGAMON CICS TG transaction monitoring exit performs a periodic "sweep" of the
active transaction table to remove orphaned transaction records (those where the last known flow
through the CICS TG is longer than X minutes). A policy can be defined for each monitored CICS TG
to indicate a running time to test all active transactions against and how often OMEGAMON should
perform this check. Any active transaction records whose last known flow exceeds the defined time are
considered orphaned and removed.
You can use the procedure defined below to set the interval and timeout values and avoid the
problems described in the troubleshooting guide in the "Orphaned CICS TG transactions remain in active
transaction workspaces" scenario.
The default policy can be changed through the setting of the following JVM properties:

Chapter 4. Configuring IBM Z OMEGAMON for CICS 47

 Table 11. Properties for defining com.ibm.omegamon.kgw.rmexit.sweepTimeout and
com.ibm.omegamon.kgw.rmexit.sweepInterval
Property Definition Default Range
com.ibm.omegamon.kgw.rmexit.sweepTimeout Length of time in minutes 10 Value
a transaction record is minutes must be
permitted to wait between greater
flows to be considered than 0
active. If this difference and no
between the last known greater
flow of this transaction and than 1440
the current time at sweep minutes
check is exceeded then the (24 hours)
transaction is considered
orphaned and removed from
the active transaction table.
An orphaned transaction
is no longer displayed in
active transactions views
and subpanels.
com.ibm.omegamon.kgw.rmexit.sweepInterval Length of time in minutes 1 minute Value
indicating how often must be
the active transaction between
tables are checked 0 and
for potential orphaned 1440
transaction record. minutes
(24
hours). A
value of 0
indicates
never
check for
orphaned
transactio
n records.

The JVM properties must be set before the CICS TG or WAS region is started and must be set on a per
region basis, meaning that you can have a different sweep policy on each monitored region. Consider the
type and running time of transactions in your environment when defining a policy. If you wish switch off
the sweep process, set the value of the sweepInterval property to 0.
For a Gateway daemon, you set the properties in the CICS TG environment file (called CTGENV) as part of
the CTGSTART_OPS parameter, for example:

CTGSTART_OPTS=-j-Dcom.ibm.omegamon.kgw.rmexit.sweepTimeout=25
-j-Dcom.ibm.omegamon.kgw.rmexit.sweepInterval=5

For a WebSphere Application Server region, use the Administration Console and navigate to the JVM
settings for the servant region to be monitored and add the arguments to the Generic JVM arguments
field. The WebSphere server will need to be restarted to read in the new properties The exact instructions
may vary according to the version of WebSphere Application Server. Check with the appropriate
Information center for precise instructions for setting JVM properties.
On startup, you should see messages in the CICS TG or WebSphere log indicating the defined policy:

KGWRM1028I - Orphaned transaction sweep timeout set to 10 minutes

KGWRM1029I - Orphaned transaction sweep interval set to 1 minutes

48 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 On Gateway daemons, an option exists for sending a command to the Request Exit, enabling the value
to be updated dynamically for the region. Use the following steps to reset the values for the sweep
properties, when monitoring transactions through a Gateway daemon:
1. Issue the following MVS command to change the sweep interval time:

/F jobname,APPL=RMEXIT,cmd=KGWSWEEPINTERVAL_n

where:
jobname
Is the name of the CICS TG system against which the command is being executed.
n
Is a value between 0 and 1440 minutes (24 hours). A value of 0 indicates never check for
orphaned transaction records.
If this command is successful, you should see a message in the CICS TG log indicating the new value:

KGWRM1029I - Orphaned transaction sweep interval set to 1 minutes

2. Issue the following command to change the sweep timeout value:

/F jobname,APPL=RMEXIT,cmd=KGWSWEEPTIMEOUT_n

where:
jobname
Is the name of the CICS TG system against which the command is being executed.
n
Is a value greater than 0 and no greater than 1440 minutes (24 hours). The shipped default is 10
minutes.
If successful, you should see a message in the CICS TG log indicating the new value:

KGWRM1028I - Orphaned transaction sweep timeout set to 10 minutes.

Note: The dynamic update of the sweep interval and sweep timeout applies to the current instance of the
Gateway daemon job. If the Gateway daemon is restarted, the sweep policy will revert to the values set as
JVM properties in the CICS TG configuration file, if set or the default values.
When monitoring transactions through a WebSphere Application Server, there is no equivalent
mechanism for sending requests to WAS regions. They may only be configured at startup time.

Verifying the configuration

After you have completed any required configuration, verify the configuration to ensure that you have
correctly configured the product and its components.
Before you can verify your configuration, the following tasks must be completed:
• If you have not enabled the self describing agent feature, the Tivoli Enterprise Portal must be installed
and configured, and application support for OMEGAMON for CICS on z/OS must be installed on the
portal server and any desktop clients installed from the media rather than downloaded using WebStart.
• The hub Tivoli Enterprise Monitoring Server must be installed and configured, and application support
for OMEGAMON for CICS on z/OS must be installed on it.
• The remote monitoring server to which an OMEGAMON for CICS on z/OS agent reports must be installed
and configured.
To verify the configuration, complete the following steps:
1. If the Tivoli Enterprise Monitoring Server in this runtime environment is not already running, vary the
monitoring server VTAM major node active and start the monitoring server started task. The monitoring
agent starts when the monitoring server starts.

Chapter 4. Configuring IBM Z OMEGAMON for CICS 49

 2. If the hub Tivoli Enterprise Monitoring Server is not already running, start it.
3. Start the started tasks for OMEGAMON for CICS.

Verifying the configuration of OMEGAMON for CICS (3270)

The following sections enable you to verify that OMEGAMON for CICS has been installed and configured
correctly:
• “Verifying OMEGAMON for CICS (3270)” on page 50
• “Verifying OMEGAMON for CICS (3270) initialization” on page 50

Verifying OMEGAMON for CICS (3270)

To verify the installation and configuration of OMEGAMON for CICS (3270), perform the following
procedure:
1. Before a VTAM-based application, for example, the IBMOC0 or OMEGAMON for CICS (3270) can be
used, you must activate the corresponding node in VTAM. When the VTAM node is available, you can
access the IBMOC0 or OMEGAMON for CICS (3270). Start OMEGAMON for CICS (3270) by activating
the VTAM node by issuing the following command:

V NET,ACT,ID=CTDC20N

Where CTDC20N is the major node name specified during configuration.

2. Start OMEGAMON for CICS (3270) by issuing the following command:

S IBMOC0

Where IBMOC0 is the started task name you specified for OMEGAMON for CICS (3270) during
configuration.
3. Test OMEGAMON for CICS (3270) by issuing the command:

LOGON APPLID(CTDOC0) DATA(‘CICS=aaaaaaaa')

Where CTDOC0is the applid you configured for the OMEGAMON for CICS (3270) and aaaaaaaa is the
jobname of the CICS region you want to monitor. This command logs you on to the OMEGAMON for
CICS (3270), which is running in that address space. (The DATA keyword is unnecessary, if a default
CICS region is named in the KOCVTMnn member of the rhilev.RKANPAR library.)
4. Stop the OMEGAMON for CICS (3270) interface address space by issuing the following command:

P IBMOC0

Verifying OMEGAMON for CICS (3270) initialization

This is an example of messages written to the JESYSMSG CICS region when OMEGAMON for CICS (3270)
is initialized:

OC1023 OCOMEG RKANMOD IS IN USE FOR PROGRAM LOADING

OC0033: XMCR CICS IS USING 'RKC2XM07' DD NAME
OC1034 EXEN MODULE KOCOME00 WILL RUN IN THREADSAFE MODE
OC2020I EXEN VSAM GLUE CODE HAS BEEN ENABLED
OC1147 EXEN CICS MONITORING IS BEING TURNED ON
OC1148 EXEN PERFORMANCE CLASS IS BEING TURNED ON
OC1149 EXEN EXIT INITIALIZATION COMPLETED
KCP1120I UMEX EXTRACTION ROUTINE PROCESSING DFHMCTAC
KCP1128I UMEX OMEGAMON CICS DATA FOR THE FOLLOWING EMPS IS AVAILABLE
KCP1129I UMEX OMEGAMON CICS DATA FOR CICS PA (OMEGCICS)
KCP1133I UMEX MCT PROCESSING HAS COMPLETED
OC1170 OCSETI STARTING OMEGAMON FOR CICS OCEXEC PROCESSING
OC1164 OCSETI KOCEXE INTERFACE IS NOW INSTALLED IN CICS
OC1213 OCSRI SERVICE TASK INITIALIZATION COMPLETED
OC1019 OCOMEG OMEGAMON FOR CICS INITIALIZATION IS COMPLETE

50 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 OC1242 OCSR2 SECONDARY SERVICE TASK WAITING FOR WORK
OC1231 OCSRV SERVICE TASK WAITING FOR WORK

Verifying the configuration for OMEGAMON for CICS on z/OS

Now that you have completed the configuration you can verify that it has been successful.
Initially you can check that the logs generated from the jobs are clean and contain no error messages.
Verification involves:
• Start these started tasks on your z/OS system:
– Tivoli Enterprise Monitoring Server
– OMEGAMON for CICS
– OMEGAMON for CICS on z/OS monitoring agent
Successful startup is indicated by the messages found in the RKLVLOG output.
• Start your CICS regions.
• Start the Tivoli Enterprise Monitoring Server that you want your agent to connect to. In the Tivoli
Enterprise Monitoring Server, that the agent is connecting to, validate that the agent is online by looking
for the following message in the monitoring server RKLVLOG output:

Remote node <agentid:sysid:CPIRA> is ON-LINE

• Start the OMEGAMON for CICS on z/OS monitoring agent started task using the following z/OS operating
system command:

/S IBMC5

The following messages indicate that the OMEGAMON XE attach controller has successfully started:

KCP9000: ATC INITIALIZATION HAS STARTED

KCP9950: ATC HAS LOADED MODULE: KCPATT0A
KCP9950: ATC HAS LOADED MODULE: KCPATI0A
KCP9950: ATC HAS LOADED MODULE: KCPTDA0A
KCP9009: ATC INITIALIZATION HAS ENDED

This message indicates that the CPIRA agent thread is registered:

KCP9002: IRA REGISTRATION THREAD IS ACTIVE

When the CPIRA agent is starting its heartbeat and attempting to connect to the Tivoli Enterprise
Monitoring Server, you see the following messages:

KRAIRA000, Starting Enterprise situation HEARTBEAT...

KRAREG000, Connecting to CMS <tems_name>:CMS
Successfully connected to CMS C5B0LNXR:CMS using ....
KCPFH0002I The CICS agent will connect to its managing TEMS using <protocol> at
<port_num> from CT_CMSLIST
KCPFH0003I The CICS agent will connect to the hub TEMS using <protocol> at
<host_name> <port_num>
KCPPA7080I The CICSplex agent has been initialized

When the near-term history persistent datastore is active, the following messages are issued:

KPDEIMN: Persistent Datastore initialization completed successfully

The following message indicates the historical situations are starting. However, you only see these
messages, if you have configured historical collection for this agent:

KRAIRA000, Starting UADVISOR_

After you have confirmed the jobs have started successfully, check that the monitored systems can be
viewed within the Tivoli Enterprise Portal by doing these tasks:

Chapter 4. Configuring IBM Z OMEGAMON for CICS 51

 • Start the Tivoli Enterprise Portal Server.
• Start the OMEGAMON enhanced 3270 user interface to see if you can view a CICSplex and to see the
CICS regions you want to monitor within the CICSplex.
• Start the Tivoli Enterprise Portal verify that you see the list of CICS regions that are associated with the
agent in the Physical Navigator view at the top left side of the workspace.

Verifying the configuration for OMEGAMON for CICS TG on z/OS

Now that you have completed the configuration you can verify that it has been successful. Initially, you
can verify that the logs generated from the jobs are clean and contain no error messages. You can also
check for messages to ensure your agent is correctly monitoring your CICS TG jobs.
The verification involves the following items:
• Start the Tivoli Enterprise Monitoring Server that you want your agent to connect to. In the Tivoli
Enterprise Monitoring Server, that the agent is connecting to, validate that the agent is online by looking
for the following message in the monitoring server RKLVLOG output:

Remote node <CICSTG:sysid:GWIRA> is ON-LINE

• Start your CICS TG and/or WebSphere Application Server regions.

• Start the OMEGAMON for CICS TG on z/OS monitoring agent started task using the following z/OS
operating system command:

/S IBMGW

Successful startup is indicated by the messages found in the RKLVLOG output.

When the near-term history Persistent Datastore is active, the following messages are issued:

KPDEIMN: Persistent Datastore initialization completed successfully

The following messages indicate that the OMEGAMON XE attach controller has successfully started:

KGW9000I: ATC INITIALIZATION HAS STARTED

KGW9950I: ATC HAS LOADED MODULE: KGWATT0A
KGW9950I: ATC HAS LOADED MODULE: KGWATI0A
KGW9950I: ATC HAS LOADED MODULE: KGWTDA0A
KGW9009I: ATC INITIALIZATION HAS ENDED

This message indicates that the GWIRA agent thread is registered:

KGW9002I: IRA REGISTRATION THREAD IS ACTIVE

When the GWIRA agent is starting its heartbeat and attempting to connect to the Tivoli Enterprise
Monitoring Server, you see the following messages:

"ctira_insert_log") KRAIRA000, Starting Enterprise situation

"ctira_insert_log") KRAREG000, Connecting to CMS sysid:CMS
"ConnectToProxy") Successfully connected to sysid:protocol address:CMS using

The following message indicates the historical situations are starting. However, you only see these
messages, if you have configured historical collection for this agent:

ctira_insert_log") KRAIRA000, Starting UADVISOR_

You see one, of each of the following messages, in the RKGWSLOG for each of the Gateway daemons
that your are monitoring:

KGWSPI09I session_name=CTG001 Port=02981 Sysname=SYSID

job_name=CTG001 Token=x"308D94A8" Status=Active

KGWSPI09I session name=CTG002 Port=02984 Sysname=SYSID

job_name=CTG002 Token=x"307CA4A8" Status=Active

52 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 Start your CICS TG and WebSphere Application Server regions.
If you have enabled transaction monitoring support for CICS TG jobs, check the log of each CICS TG job
for the following message:
KGWRM1000I: OMEGAMON for CICS TG monitoring exit initialization complete.

If you have enabled statistical collection support, check the log of your agent job for the following
message:

KGWSPI09I Session Name=ssssssss PortNumber=pppp

Sysname=yyyy jobname=jjjjjjjj Token=x"tttttttt"
Status=Active

where ssssssss is the name of your CICS TG and pppp is the statistics port number the connection to the
CICS TG is made to.
If you have enabled monitoring support for CICS TG running locally within WebSphere Application Server,
the monitoring exit does not register until a suitable workload is sent through the configured connection
factory. When this occurs, check the log of each job for the following message:
KGWRM1000I: OMEGAMON for CICS TG monitoring exit initialization complete.

Once you verify your configuration, verify your runtime environment.

From the Runtime Environment menu, select the runtime environment you want to verify by placing a Z in
the Action column next to your runtime environment.
From the RTE Utility Menu/ RTE: rte_name menu, specify 11. Verify configuration and generate parameter
map.
From the Verify Configuration and Generate Parameter Map/ RTE: rte_name, select option 1. Verify the
batch configuration and submit the generated job. Review the job output.
After you have confirmed the jobs have started successfully, check that the monitored systems can be
viewed within the Tivoli Enterprise Portal by doing these tasks:
• Start the Tivoli Enterprise Portal Server.
• Start the Tivoli Enterprise Portal.
When Tivoli Enterprise Portal opens, verify that you see the list of CICS TG regions that are associated
with the agent in the Physical Navigator view at the beginning of the workspace.

Verifying self-describing agent enablement

If you using the self-describing agent feature for adding application support seeding, use the Installation
Verification Program (IVP) to see the following messages that indicate successful processing for the
OMEGAMON for CICS on z/OS and OMEGAMON for CICS TG on z/OS application support file seeding.
When an agent comes on line for the first time with the self-describing agent enabled, it adds the catalog
entries to the hub Tivoli Enterprise Monitoring Server, then it does the seeding process (assuming the
self-describing agent installation records are still set to the default). If the agent is connected to a remote
Tivoli Enterprise Monitoring Server, when it comes on line, the hub application support and seeding is
processed first, followed by the remote Tivoli Enterprise Monitoring Server. The OMEGAMON for CICS on
z/OS and OMEGAMON for CICS TG on z/OS agents only provide application support seeding for the hub
Tivoli Enterprise Monitoring Server, they do not seed the remote Tivoli Enterprise Monitoring Server.
To validate successful self-describing agent application support seeding, look for the KRAA0002 message
in the agent RKLVLOG output and message KFASD101 in the hub Tivoli Enterprise Monitoring Server
RKLVLOG.
The OMEGAMON for CICS on z/OS agent RKLVLOG:

(0001-D944CB53:kraaulog.cpp,543,"ctira_insert_log") KRAA0002, Self-Describing Agent

Installation completed successfully for PRODUCT "CP", with TEMS "C5B0HUB:CMS",
VERSION_INFO "product_vrmf=05100000;tms_package_vrmf=05100000;
tps_package_vrmf=05100000;tpw_package_vrmf=05100000;".,
Producer(SDA_Install)

Chapter 4. Configuring IBM Z OMEGAMON for CICS 53

 The OMEGAMON for CICS TG on z/OS agent RKLVLOG:

(0001-D9898383:kraaulog.cpp,543,"ctira_insert_log") KRAA0002, Self-Describing Agent

Installation completed successfully for PRODUCT "GW", with TEMS "C5B0HUB:CMS",
VERSION_INFO "product_vrmf=05100000;tms_package_vrmf=05100000;
tps_package_vrmf=05100000;tpw_package_vrmf=05100000;".,
Producer(SDA_Install)

In the hub Tivoli Enterprise Monitoring Server RKLVLOG, look for the following messages for OMEGAMON
for CICS on z/OS (CP) and OMEGAMON for CICS TG on z/OS (GW):

KFASD101 Self-Describing Install Completed Successfully for PRODUCT <CP>,

VER <05100000>, ID <TMS>, IDVER <05100000>.

KFASD101 Self-Describing Install Completed Successfully for PRODUCT <GW>,

VER <05100000>, ID <TMS>, IDVER
<05100000>.

Enabling security
After you have established that OMEGAMON for CICS on z/OS is configured correctly, you can safely
enable security.
To enable security for the Tivoli Enterprise Portal through either the hub monitoring server or the Tivoli
Enterprise Portal Server, see Tivoli Enterprise Portal security.
To enable logon security for OMEGAMON XE, and OMEGAMON for CICS (3270), and security for
OMEGAMON commands, see “Enabling security for OMEGAMON XE and OMEGAMON for CICS” on page
95

Installing language support

If you want application data, online help, and expert advice to be displayed in a language other than
English, you must also install language support.
You install language support from the IBM OMEGAMON for CICS on z/OS Language Pack DVD on the same
system where you install application support. Install the language packs on any system where you have
installed the Tivoli Enterprise Portal or where you have installed a desktop client. (If you download and
run a desktop client using Web Start, you do not need to install the language packs on the local system.
They are downloaded from the Tivoli Enterprise Portal Server.) Before you can install a language pack, you
must install the component in English.

Reporting on groups of CICS Regions: CICSplexes

In the enhanced 3270 user interface, you can group CICS regions into reporting groups or CICSplexes and
view data summarized at the CICSplex level.
Data for the CICS regions within a CICSplex, which can span multiple LPARs, is summarized and provides
quick isolation of problems. For example, you might want to view all your payroll CICS regions as a single
entity. You could separate these payroll CICS regions not only by department but also by geography.
The CICSplex Rules and Agent Preferences panel lets you configure the way CICSplexes are handled. It
has three subpanels:
• The Default CICSplex Processing subpanel lets you specify the order for CICSplex processing.
• The Rule Definitions for All CICSplexes subpanel lets you create and change rule definitions.
• The Preferences For All CICSplex Agents subpanel lets you enter the parameters that determine
which agent becomes the CICSplex managing agent.

54 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Accessing the CICSplex Rules and Agent Preferences panel
Before you can access the CICSplex Rules and Agent Preferences panel and begin defining your site’s
CICSplex environment and agent preferences, you must be an OMEGAMON enhanced 3270 user interface
user with the necessary security authority.
To access the CICSplex Rules and Agent Preferences panel:
• Enter C next to any CICS region in the CICS Region Name column of the CICSplex Regions Summary
panel; then, at the CICS Control Functions panel, enter P CICSplex Rules and Agent Preferences to
view the CICSplex Rules and Agent Preferences panel.
• Enter / next to any CICS region name in the CICS Region Name column of the CICSplex Regions
Summary panel to access the Action Command Menu.
1. From the Action Command Menu, select C CICS Control Functions.
2. From the CICS Control Functions panel, select P CICSPlex Rules and Agent Preferences to reach
the CICSplex Rules and Agent Preferences panel

Viewing the CICSplex Rules and Agent Preferences panel

You can use the CICSplex Rules and Agent Preferences panel to add or delete CICSplex classification
rules and add preferences for a CICSPlex agent. You normally access the CICSplex Rules and Agent
Preferences panel from the CICSplex Regions Summary panel.

The CICSplex Rules and Agent Preferences panel includes three subpanels:
• The Default CICSplex Processing subpanel is used to define which CICSplex a CICS region will be
reported against.
• The Rule Definitions for All CICSPlexes subpanel displays all the classification rules that OMEGAMON
for CICS on z/OS currently uses to group CICS regions into CICSplexes. The rules are listed in
descending priority order with the default OMEGPLEX rule definition displayed as the last row in the
panel.
• The Preferences For All CICSplex Agents subpanel contains the values that you specify to control
which IBM Z OMEGAMON for CICS agent will monitor a CICSplex, and it enables all history information
for a CICSplex to be available at one agent.
These three subpanels are shipped with the default OMEGPLEX CICSplex definition and the *DFLT
preference provided. You can modify these defaults, but you cannot delete them.

Figure 4. CICSplex Rules and Agent Preferences panel

Chapter 4. Configuring IBM Z OMEGAMON for CICS 55

 Using the Default CICSplex Processing subpanel
The Default CICSplex Processing subpanel is used to define which CICSplex a CICS region will be
reported against.
If there is nothing defined, OMEGAMON will look to see if the region is assigned a CP/SM CICSplex and
use that. If no CP/SM CICSplex is defined then the value OMEGPLEX is used as the CICSplex name. This is
also the behavior if the rules the user creates classifies the region into a CICSplex named OMEGPLEX. The
choices are as follows:
• CPSM then LPAR. This is the default option. The CICS region will be added to the CICSplex name used
by CP/SM. If the region is not CP/SM-managed, the SMF ID of the LPAR will be used to generate the
CICSplex name.
• CPSM then SYSPLEX. The CICS region will be added to the CICSplex name used by CP/SM. If the region
is not CP/SM managed, the name of the SYSPLEX will be used to generate the CICSplex name.
• CPSM then OMEGPLEX. The CICS region will be added to the CICSplex name used by CP/SM. If the
region is not CP/SM managed the CICSplex name will be OMEGPLEX.
• LPAR. The CICS region will use the SMF ID of the LPAR to generate the CICSplex name.
• SYSPLEX. The CICS region will use the name of the SYSPLEX to generate the CICSplex name

Using the Rule Definitions for All CICSplexes subpanel

The Rule Definitions for All CICSplexes subpanel displays classification rules that OMEGAMON for CICS
on z/OS uses to group CICS regions into CICSplexes.
You can use the subpanel to define the rules for a new CICSplex and to update or delete an existing
set of rules. The rules are listed in descending priority order with the default OMEGPLEX rule definition
displayed last.

Working with the subpanel

When you use the Rule Definitions for All CICSPlexes subpanel to define a new rule definition, you are
automatically presented with a new panel (KCPPLXA) on which the name of the new CICSplex and the
rules that will determine membership to it can be entered. You can also add, delete, or update agent
preferences outside of the rule definition process.
A CICS region is classified into a CICSplex using definitions in OMEGAMON for CICS on z/OS or can
be derived from CICSPlex Systems Manager (CPSM). If the definitions in OMEGAMON for CICS on z/OS
indicate that a CICS region is to be classified into the default OMEGPLEX CICSplex, and there is a CPSM
CICSplex name associated with the CICS region, it is used to classify the region in OMEGAMON. The
default CICSplex definition, OMEGPLEX, is provided by OMEGAMON for CICS on z/OS; this allows the
CPSM rules to be leveraged without any further action. The enhanced 3270UI cannot be used to modify or
establish CPSM definitions.
CICS regions become part of a CICSplex based on classification rules that specify the value of region
attributes, for example, job name or VTAM APPLID. The CICS region is assigned to a CICSplex when the
attributes match the rules definition. When you create your classification rules they are assigned an order
of evaluation. CICS regions are compared to the existing classification rules and assigned to the first
CICSplex with a matching rule. Multiple rules can be defined for one CICSplex. The default rule assigns
regions to the CICSplex OMEGPLEX; it has the lowest order of evaluation and is assigned to CICS regions
that do not match any preexisting rules.
The CICSplexes that have CICS regions assigned are displayed in the enhanced 3270UI and in the
Tivoli Enterprise Portal. The CICSplexes are displayed as nodes on the Physical Navigator of the Tivoli
Enterprise Portal and the CICSplex information is displayed on the CICSplex Summary workspace. The
enhanced 3270UI provides CICSplex summary panels and detail panels for various problem solving
scenarios.
Note: You must use the OMEGAMON enhanced 3270 user interface to view or enter CICSplex rules or
agent preferences.

56 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Attributes used to assign a CICS region to a CICSplex
The following attributes of a CICS region are used to assign the region to a CICSplex on the Rule
Definitions for All CICSplexes subpanel:
Job Name
The name of the CICS region being monitored.
SYSplex Name
The name of the z/OS Sysplex where the CICS region is running.
SMF Identifier
The identifier of the z/OS image where the CICS region is running.
VTAM Applid
The unique VTAM Applid of the CICS region.
VTAM Generic Applid
The unique generic VTAM Applid of the CICS region.
XCF Group
The XCF group where the CICS region belongs.
The following requirements are used in CICSplex classification rules:
• The default OMEGPLEX classification rule cannot be deleted; it must be the final rule in the CICSplex
Rule Definitions table.
• All attributes used in the classifying rules for Job name, SYSplex name, SMF Identifier, VTAM applid,
VTAM Generic applid, and XCF group must conform to z/OS naming conventions, A-Z, 0-9, $, #, @.
• The asterisk (*) character can be used in any of the attributes to denote a wild card.

Adding and editing CICSplex classification rules

You can add a new CICSplex classification rule and related agent preferences from the Rule Definitions
for All CICSplexes subpanel on the CICSplex Rules and Agent Preferences panel in the OMEGAMON
enhanced 3270 user interface.
To add a new CICSplex classification rule, use these steps:
1. From the CICSplex Rules and Agent Preferences panel (Rule Definitions for All CICSplexes subpanel),
either enter an A or a / next to a CICSplex Name.
Note: The new rule will be inserted before the row the cursor is in, and its priority will be higher than
the rule where the cursor is. A new rule added with this process takes precedence over the existing
rulesbelow where the A or / was entered.
The A takes you directly to the Add a new CICSplex Classification Rule panel while the / displays the
Action Command Menu.
a. On the Action Command Menu, type an A next to 1. A Add new CICSplex rule and press Enter.
2. On the Add a new CICSplex Classification Rule panel, use the input fields to enter your new CICSplex
classification rule.

Chapter 4. Configuring IBM Z OMEGAMON for CICS 57

 Figure 5. Add a new CICSplex Classification Rule panel

All input fields must obey the z/OS naming conventions for the appropriate field. The SMF Identifier
can consist of the characters A-Z, 0-9, #, @ and $. The CICSplex Name field can consist of the
characters A-Z, 0-9, #, @ and $ but cannot start with 0-9 or the hash (#) character. For the remaining
fields, the first character must be A-Z, #, @ or $.
3. Once you have completed all the fields, press Enter.
If you enter a rule that is not valid, the Add a new CICSplex Rules and Agent Preferences panel is
displayed again with an error message. For example:

KCPPR0001E Invalid characters in CICSplex Name value: xxxxxxxxx

Correct the input field and press Enter again to continue.

4. The xxxxxxxx CICSplex Agent Preferences (KCPPLXAA) panel that corresponds to the CICSplex whose
rules you just defined is displayed.

Figure 6. xxxxxxxx CICSplex Agent Preferences (KCPPLXAA) panel

58 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 The xxxxxxxx CICSplex Agent Preferences panel shows the items used to decide which agent will be
the CICSplex agent. You can define or change the following fields:
Agent SMF Identifier
The system ID where the agent will run. This value is four characters long, a mixture of 0-9, A-Z,
$, #, @ or numbers only. A single asterisk (the default) means that any CICS agent running in
any system can become the CICSplex agent. If more than one CICS agent is available per SMF
Identifier, then the Agent XM Number should also be provided. This value restricts which agent will
be used as the CICSplex agent.
Agent XM Number
The number in the RKCPXMnn DD card to be used, if there are multiple agent address spaces
started at the LPAR indicated by the CICSplex Agent Preferences SMF Identifier. Valid input is
00-15.
CICSplex Agent Timeout
Represents the number of minutes that a CICS agent will wait for the preferred CICSplex agent to
initialize at the indicated LPAR. If the CICSplex agent does not start up in that period of time, any
other OMEGAMON for CICS address space will initialize it.
Review the default values generated by information already entered or provide new values. Then press
Enter.
If you enter a preference that is not valid, the xxxxxxxx CICSplex Agent Preferences panel is displayed
again with an error message. For example:

KCPPR0012E: There are invalid characters in the CICSplex Agent SMF

Identifier, value: xxxx.

Correct the input field and press Enter again to continue.

5. A message is displayed in the Take Action Results panel indicating that the rule for the CICSplex was
successfully added.

Editing a CICSplex classification rule

To edit an existing CICSplex classification rule, type U next to the rule you wish to change on the Rule
Definitions for All CICSplexes subpanel and press Enter. Overtype the fields you wish to change and press
Enter.

Deleting a CICSplex classification rule

You can delete a CICSplex classification rule in your CICSplex environment from the CICSplex Rules and
Agent Preferences panel in the OMEGAMON enhanced 3270 user interface.
To delete a CICSplex classification rule, use these steps:
1. From the CICSplex Rules and Agent Preferences panel (Rule Definitions for All CICSplexes subpanel),
either enter a D or a / next to the CICSplex Name for the rule that you want to delete.
The D takes you directly to the Delete this CICSplex Classification Rule panel, while the / displays the
Action Command Menu.
a. On the Action Command Menu, type a 2 or a D to select Delete this CICSplex Classification Rule and
press Enter.
The Delete this CICSplex Classification Rule panel is displayed, where the CICSplex Name field is the
name of the classification rule.

Chapter 4. Configuring IBM Z OMEGAMON for CICS 59

 Figure 7. The Delete this CICSplex Classification Rule panel
2. On the Delete this CICSplex Classification Rule panel , enter Y (Yes) to confirm the deletion of the
classification rule and press Enter.
3. A message is displayed in the Take Action Results panel indicating that the rule for the CICSplex was
successfully deleted.

Using the Preferences For All CICSplex Agents subpanel

The Preferences For All CICSplex Agents subpanel contains the values that you specify to control which
OMEGAMON for CICS on z/OS agent will monitor a CICSplex, and it enables all history information for a
CICSplex to be available at one agent.

Attributes used to assign a CICSplex agent

The following CICSplex Agent Preferences attributes are used to control which OMEGAMON for CICS on
z/OS agent will monitor a CICSplex:
CICSplex Agent Preferred SMF Identifier
The SMF Identifier where the CICSplex agent is to be initialized. Valid input is up to four characters, a
mixture of 0-9, A-Z, $, #, @. It can consist solely of numbers. It might be a single asterisk but not have
asterisks otherwise (no generic specification allowed).
CICSplex Agent Preferred XM Number
The number in the RKCPXMnn DD card to be used, if there are multiple agent address spaces started
at the LPAR indicated by CICSplex Agent Preferred SMF Identifier. Valid input is 00-15 or a single
asterisk.
CICSplex Agent Timeout Tolerance
The number of minutes that a CICS agent will wait for the CICSplex agent to initialize at the indicated
LPAR. If the CICSplex agent does not start up in that period of time, any other OMEGAMON for CICS
address space will initialize it. Valid input is 0-30.
CICSplex Name
The name of the CICSplex whose agent preferences are being displayed.
The following requirements are used in CICSplex agent preferences:
• The default *DFLT agent preference cannot be deleted.
• The CICSplex Name attribute must conform to z/OS conventions, A-Z, $, #, @, 0-9. The first character
cannot be 0-9 or the hash (#) character.
• A single asterisk (wild card) can be used in the SMF Identifier and XM Number attributes.

60 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Adding agent preferences for a CICSplex
It is possible to add agent preferences for a CICSplex that has already been defined or one that is not
defined to OMEGAMON, but is derived from CICSPlex System Manager (CPSM). Follow this procedure to
add agent preferences for an existing CICSplex or a CICSplex derived from CPSM.
To add new preferences for a CICSplex agent, use these steps:
1. From the Preferences For All CICSplex Agents subpanel of the CICSplex Rules and Agent Preferences
panel, enter either an A or a / next to a CICSplex Name.
The A takes you directly to the Add Preferences for a CICSplex Agent panel, while the / displays the
Action Command Menu.
a. On the Action Command Menu, type an A or 1next to 1. A Add Preferences for a CICSplex Agent
and press Enter.
2. On the Add Preferences for a CICSPlex agent panel, use the input fields to enter your new agent
preferences.

Figure 8. Add Preferences for a CICSplex Agent panel

3. Once you have completed the fields, press Enter to add the agent preferences for your CICSplex.
If you see an error message, correct the input field and press Enter again to continue.
4. A message is displayed in the Take Action Results panel indicating that the agent preferences for the
CICSplex were successfully added. For example:

KCPPR1399I: The agent preferences for CICSplex cicsplex_name were successfully added.

Updating agent preferences for a CICSplex

You can update agent preferences for a CICSplex from the CICSplex Rules and Agent Preferences panel in
the OMEGAMON enhanced 3270 user interface.
To update agent preferences for a CICSplex, use these steps:
1. From the CICSplex Rules and Agent Preferences panel (Preferences For All CICSplex Agents
subpanel), type a U or a / next to the CICSplex Name whose agent preferences you want to update.
The U takes you directly to the Update this CICSplex Agent's Preferences panel, while the / displays
the Action Command Menu.

Chapter 4. Configuring IBM Z OMEGAMON for CICS 61

 a. On the Action Command Menu, type a 3 or a U to select Update this CICSplex Agent's Preferences
and press Enter.
The Update this CICSplex Agent's Preferences panel (KCPPLAU) is displayed showing the values for
the CICSplex whose preferences you are updating.

Figure 9. Update this CICSplex Agent's Preferences panel

2. On the Update this CICSplex Agent's Preferences panel, overtype any of the preferences you want to
change for the named CICSplex and press Enter.
If you see an error message, correct the input field and press Enter again to continue.
3. A message is displayed in the Take Action Results panel indicating that the agent preferences for the
CICSplex were successfully updated.

KCPPR1399I The agent preferences for CICSplex cicsplex_name were successfully updated.

Deleting agent preferences for a CICSplex

You can delete agent preferences for a CICSplex from the CICSplex Rules and Agent Preferences panel in
the OMEGAMON enhanced 3270 user interface.
To delete agent preferences for a CICSplex, use these steps:
1. From the CICSplex Rules and Agent Preferences panel (Preferences For All CICSplex Agents
subpanel), enter a D or a / next to the CICSplex Name whose agent preferences you want to delete.
The D takes you directly to the Delete this CICSplex Agent's Preferences panel, while the / displays the
Action Command Menu.
a. On the Action Command Menu, type a 2 or a D to select Delete this CICSplex Agent's Preferences
and press Enter.
The Delete this CICSplex Agent's Preferences panel (KCPPLADR) is displayed showing the values for
the CICSplex whose preferences you are deleting.

62 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 Figure 10. Delete this CICSplex Agent's Preferences panel

If classification rules also exist for the CICSplex, you see this warning message:

Warning: classification rules exist for this CICSplex.

2. On the Delete this CICSplex’s Agent Preferences panel, enter Y (Yes) to confirm the deletion of the
agent preferences and press Enter.
3. A message is displayed in the Take Action Results panel indicating that the agent preferences for the
CICSplex were successfully deleted.

KCPPR1399I The agent preferences for CICSplex cicsplex_name were successfully deleted.

Creating complex CICSplex classification rule definitions using wild card

characters
The asterisk wild card character (*) can be used in classification rule definitions.
The CICS regions are assigned to CICSplexes based on the value of their Job Name. For example, if you
had CICSplex classification rules established for PRODPLEX , DEVPLEX and XCFR01 and so on; PRODPLEX
would be evaluated first, followed by DEVPLEX, then XCFR01 and so on with the default OMEGPLEX
evaluated last on the list. Note, OMEGPLEX uses wild card characters for all attributes, so it is assigned to
any CICS region that has failed to match an earlier rule. The default OMEGPLEX CICSplex name cannot be
modified nor deleted. You can add additional rules with the OMEGPLEX name and delete them, but not the
default classification rule that contains the asterisk wildcard character (*) for all the fields.
Classification rules can further restrict CICSplex membership to CICS regions that match multiple
attributes.
The following example assigns CICS regions to PRODPLEX if the first six characters of the CICS job name
are CICSDE, or, if the CICS region runs in the SYSPLXA Sysplex:

Chapter 4. Configuring IBM Z OMEGAMON for CICS 63

 Figure 11. CICSplex Classification Rule Definitions panel example of wild card characters (1 of 2)

Here is another example of multiple rules:

Figure 12. CICSplex Classification Rule Definitions panel example of wild card characters (2 of 2)

This example assigns to PRODPLEX all CICS regions that have names starting with CICSDE or all CICS
regions whose names start with MYCICS.

Controlling application trace using the enhanced 3270 user

interface
You can now set application trace levels for the OMEGAMON Application Trace facility using the
OMEGAMON enhanced 3270 user interface (enhanced 3270UI). Use this facility to define trace filters
and view application traces.
The Application Trace facility enables you to see the CICS requests made by an application program.
Many application errors are often not discovered until an application is running in a production
environment.
You can define a trace filter which repeats either Hourly, Daily or Weekly, as described in the procedure
below. You can also define a repeating trace in the OMEGAMON CICS Global data area. Creating a

64 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

repeating trace saves you the trouble of having to create a new trace filter each time you want to trace the
requests made by an application.
Application trace filters can have a maximum size, specified in 32K-size blocks with the Size parameter.
Follow this procedure to define application trace filtering and start and stop trace operations using the
enhanced 3270UI. In the Classic interface, this is specified from the TRACE FILTERS MANAGEMENT
panel, which you can access by entering O.V from the Main Menu.
1. Type C next to any CICS region in the CICS Region Name column of the CICSplex Regions Summary
panel and press Enter to display the CICS Control Functions popup panel.
2. On the CICS Control Functions popup panel, type A and press Enter to select CICS Application Trace
Information.
3. The CICS Application Trace Information panel is displayed.
To activate application trace and add a filter, do the following:
a. Move your cursor to the Application Trace Status line and press Enter to display the Change
Application Trace Status prompt.
b. Overtype Inactive with Active and press Enter.
c. The trace is activated. Press PF3 to return to the CICS Application Trace Information panel.
d. Type an A by any of the filters and press Enter to display the Add an ATF filter panel.
e. Specify filter criteria using the following information, then press Enter:
Tran ID
The transaction ID mask that this filter applies to. The format is a four-character string.
Owner
The user ID of the person who created the trace filter. The format is an eight-character string.
Duration time
The length of time that this filter is active. The format is a five-digit number.
Userid
The user ID mask that this filter applies to. The format is an eight-character string.
Term ID
The terminal ID mask that this filter applies to. The format is a two-digit integer.
Size
The size of the trace filter. The default value is the value in the Global member. You can specify
any multiple of 32K blocks. Entries in-between multiples of 32 will be rounded up.
Call type
The types of calls or events to be traced. Valid values are:
• ALL: All call types will be traced
• EXEC: Entry to and exit from an EXEC CICS command
• PCABEND: Entry to the CICS abend exit XPCABND
• RMI: Entry to and exit from the CICS Resource Manager Interface (RMI)
• MQ: Entry to and exit from the Message Queue (MQ) service request
• UMBRELLA: completion of an OMEGAMON umbrella service request
• TPPS: Entry to and exit from OMEGAMON third party product support (TPPS) services
Exec call
Specifies which EXEC CICS calls are traced. Valid values are:
• ALL: All CICS exec calls executed by the CICS transaction are traced
• NONE: No CICS Exec calls will be traced
• FILE: File control EXEC CICS commands traced
• PROGRAM: Program control EXEC CICS commands traced

Chapter 4. Configuring IBM Z OMEGAMON for CICS 65

 • STORAGE: Storage control EXEC CICS commands traced
• TERM: Terminal control EXEC CICS commands traced
• TS: Temporary storage EXEC CICS commands traced.
Note: You can enter more than one exec call type, separated by commas.
Start date
The date on which the filter will become or became enabled.
Start time
The time at which the filter will become or became enabled.
Repeat
The trace repeat option. Choices are N (no repeat), H (hourly), D (daily), and W (weekly)
followed by the day of the week (SUN, MON, TUE, WED, THU, FRI, or SAT).
f. The filter is added. Any transactions that match the mask specified for Tran ID will have trace
enabled. Press PF3 to return to the CICS Application Trace Information panel.
4. If application trace filters exist, including those created in the Classic user interface, also called
OMEGAMON for CICS (3270), they display in the Application Trace Filters defined subpanel on the
CICS Application Trace Information panel. You can add additional filters and delete filters. To remove
(delete) a filter, type D next to the filter that is to be deleted, and press Enter. To copy an existing filter,
type C next to the filter you want to copy, and press Enter. To modify a filter, type M next to the filter
you want to modify, and press Enter.

Specifying repeating trace in the Global Data Area

You can specify a repeating application trace by adding the Repeat, Start Time, and Duration values in the
Global Data Area.
In this example, the filter starts every Wednesday at 3:00am and runs for 1439 minutes, as specified by
the START_TIME, DURATION, and REPEAT settings in the Global Data Area:

<APPLICATION_TRACE_FILTERS>
*
*
<<TRACE>>
TRAN=STRS
SIZE=64
OWNER=TS5864
REPEAT=WEEKLY,WEDNESDAY
DURATION=1439
START_TIME=0300

For more information on the Global Data Area, see “Overview of the Global Data Area” on page 127 or
Global Data Area.

Configuring Service Level Analysis definitions using the Tivoli

Enterprise Portal
OMEGAMON for CICS on z/OS provides the CICS SLA view, a different view from the Tivoli Enterprise
Portal Navigator Physical view. This alternative view allows you to set workload performance thresholds
with which you can monitor your CICS transactions to ensure they comply with your site's service level
agreements.
These Tivoli Enterprise Portal objects support the Service Level Analysis feature within OMEGAMON for
CICS on z/OS:
service classes
This object identifies the transactions that share common response time goals, grouped together by
transaction IDs, user IDs, VTAM terminal ID (that is, LU names), and or CICS region APPLIDs. A service
class is associated with exactly one workload.

66 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 workloads
This object groups one or more service classes that you must monitor as a unit; a workload reflects
the status of all the service classes within it.
service policies
This object includes all workloads and all service classes defined for the enterprise. Service class
goals can vary by service policy; that is, with service policies, you can change a service class's
response-time goals as dictated by your site's varying requirements. For example, you can define one
service policy for prime-shift operation, another for evening operation, and yet a third for weekend
operation.
Your monitored environment can only have one active service policy at any given time.
Use the CICS SLA view within Tivoli Enterprise Portal, to define and activate each of these objects.
Complete these tasks, in the following order:
• “Opening the CICS SLA view” on page 68
• “Adding or editing a workload” on page 68
• “Adding or editing a service class” on page 69
• “Editing service class rules in the Tivoli Enterprise Portal” on page 70
• “Adding or editing a service policy and activating a service policy” on page 71
• “Overriding a service class goal” on page 72
• “Verifying the CICSplex control settings and saving the updated service level analysis definitions” on
page 72
• “Returning to the Navigator Physical view” on page 73
Note: Before your Tivoli Enterprise Portal user ID can access the CICS SLA view and begin modeling your
site's SLA requirements, a user ID with administrator authority must give it that access; see “Accessing
the CICS SLA view” on page 67.
If your installation chooses to monitor its service-level compliance using only z/OS's native, ISPF-based
workload manager, the service policies, workloads, and service classes you create using this view are
ignored. OMEGAMON for CICS on z/OS instead uses the service classes and goals defined by the z/OS
workload manager. In this case, the only procedure you need complete to activate CICS SLA monitoring is
“Verifying the CICSplex control settings and saving the updated service level analysis definitions” on page
72.

Accessing the CICS SLA view

Before you can access the CICS SLA view and begin defining your site's service level agreement
environment, your Tivoli Enterprise Portal user ID must be given that access.
Note: A user with Tivoli Enterprise Portal administrator authority must complete this step.
1. From the primary Tivoli Enterprise Portal toolbar, click the Administer Users icon.
By clicking the Administer Users icon, the Administer Users window is displayed . This is a two-paned
window with Users and User Group tabs at the beginning of frame and several tabs at the end of the
frame.
2. Within the Users tab, scroll down to the user ID for which you want to make the CICS SLA view
accessible, and select it.
3. Within the notebook at the end of the window, select the Navigator Views tab. The Navigator Views
tab of the Administer Users screen is displayed.
4. Within the list of available views, select CICS SLA, and click the arrow to move the view to the list of
assigned views for the selected user ID and click OK.
When you have given a particular user ID authority to access the CICS SLA view, you do not need to
complete this step again unless you need to remove that authority.

Chapter 4. Configuring IBM Z OMEGAMON for CICS 67

 Note: If the user ID to which you just gave access is currently logged on to Tivoli Enterprise Portal,
that person must log off and log back on before the CICS SLA view is accessible. Then continue with
“Opening the CICS SLA view” on page 68.

Opening the CICS SLA view

To open the CICS SLA view within Tivoli Enterprise Portal, click the View list, and select CICS SLA.
Note: If CICS SLA view is not listed in the View menu, your user ID has not been authorized to access this
view; see “Accessing the CICS SLA view” on page 67.
The CICS SLA view has these windows:
• You use the Service Classes window to create, edit, assign rules to, and delete service classes.
• You use the Workloads window to create, edit, and delete workloads.
• You use the CICSplex SLA window to create, edit, and delete service policies, to override the default
goals for service classes, and to activate a service policy. You also have the option to modify the
Collection Interval, which controls how often data is summarized for historical Service Level Analysis
reporting.
When you are in the CICS SLA view, your first step is to create a workload; see “Adding or editing a
workload” on page 68.

Adding or editing a workload

A workload groups one or more service classes that you to monitor as a unit; with it, you can monitor
related service classes, highlighting the worst performing class within the group. Defining one or more
workloads is usually the first step in implementing the SLA support within IBM Z OMEGAMON for CICS.
Note: OMEGAMON for CICS on z/OS does not support workload balancing; the workload objects defined
using the CICS SLA view are for displaying purposes only.
To define a new workload, use these steps:
1. Within the Workloads window, click Create.
The Create new Workload window is displayed.
2. Within the workload editor, define a name for your new workload, and give it a description. The name
you supply is converted to uppercase.
A workload name is a maximum of eight characters in length. These are the valid characters for the
workload name: A-Z, a-z, 0-9 and any of the following, $ @ # . / - _ % & ¢ ? ! : | = ¬ ; < >. Note, the
comma (,) and double quote (") characters are not valid.
A workload description is a maximum of 24 characters in length. The valid characters are any basic
Latin ASCII characters.
3. To save your new workload, click OK.
A default workload named DFLTWORK is provided with IBM Z OMEGAMON for CICS.

Editing an existing workload

You can also change the description of an existing workload:
1. Within the Workloads window, select the workload you want to edit, and click Edit.
The Edit Workload window opens and shows the name of the selected workload and the current
description.
2. Edit the Description field as needed.
3. Click OK .
After you have defined the appropriate workload, your next step is to create the service classes; see
“Adding or editing a service class” on page 69.

68 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Adding or editing a service class
A service class identifies a block of related transactions that share common response time goals for a
single workload; the transactions must be related by transaction name, the user ID that invoked them,
the VTAM terminal ID (LU name) that submitted them, the CICS region running them, or any combination
thereof. Defining new service classes, associating them with a workload, and setting their response time
goals usually compose the second step when implementing the Service Level Analysis support within IBM
Z OMEGAMON for CICS.
To define a new service class complete the following tasks:
1. Within the Service Classes window, click Create.
The Define new Service Class window is displayed.
2. Within the Define new Service Class window, define a name for your new service class. The name you
supply is converted to uppercase.
These are the valid characters for the Service Class name: A-Z, a-z, 0-9, and any of the following
characters, $ @ # . / - _ % & ¢ ? ! : | = ¬ ; < >. Note, the comma (,) and double-quote (") characters are
not valid.
3. From the list of available workloads, select the existing workload you want to associate this service
class with.
4. Within the Response Time area, specify the response time you expect for the CICS transactions
associated with this service class.
5. Within the Goal area, select one of these options:
Average
The average response time for all matching transactions must at least meet the Response Time
specified.
% of Goal
Specifying a percentage means that the given percentage of matching transactions must at least
meet the Response Time specified.
6. Click OK.
IBM Z OMEGAMON for CICS provides 31 default service classes (ATRANS through ZTRANS, CSM1, CSM2,
CSM3, CSM5, and CSMI). Service classes ATRANS through ZTRANS cover transactions based on the
first character of the transaction name. Service classes CSM1, CSM2, CSM3, CSM5, and CSMI cover the
transactions with those names.

Changing an existing service class workload or the response time settings

You can also change an existing service class's associated workload or its response time settings:
1. Within the Service Classes window, select the service class you want to edit, and click Edit.
The Edit Service Class Base Goal window opens again, and shows the name of the selected service
class, the workload it is currently associated with, and its Response Time and Goal areas.
2. Here you can redefine this subset of the service class's current parameters:
• The workload it is associated with
• Its response time goal: either increasing or decreasing it
• The type of goal for this service class, either average or percentage, and the percentage itself
3. When you have correctly redefined the service class, click OK.
After you have created a service class, you must identify the CICS transactions, user IDs, LU names, and
CICS regions associated with it; continue with “Editing service class rules in the Tivoli Enterprise Portal”
on page 70.

Chapter 4. Configuring IBM Z OMEGAMON for CICS 69

 Editing service class rules in the Tivoli Enterprise Portal
The classification rules for a service class identify the CICS transactions associated with a particular
service class.
To add classification rules to a new service class, complete these steps:
1. Within the Service Classes window, select the service class whose classification rules you want to
define, and click Edit Rule.
The Rule Editor window is displayed.
2. Right-click the Rule entry, and select one of the following transaction-selection criteria from the menu:
TranID
Transactions in this service class are based on their transaction names.
LUname
Transactions in this service class are based on the VTAM terminal that invoked them.
UserID
Transactions in this service class are based on the user ID associated with them.
CICSname
Transactions in this service class are based on the CICS region that is running them. The
CICSname refers to the APPLID of the region, not the JOBNAME.
3. Within the input window, enter an initial CICS transaction, VTAM terminal ID (LU name value), user ID,
or the CICS region APPLID you want to assign to this service class rule. You enter only one value in this
field; additional criteria can be added later.
4. When you are finished specifying the value to assign to this criterion, click OK.
5. To add an additional criterion to your rule, right-click the Rule entry or the existing selection criterion
you want to apply it to, and select the new criterion type.
a. If you right-click Rule, the new criterion is added to the existing criterion as an OR condition. It is
appended to the Rule Editor's tree view at the same level as the existing criteria.
b. If you right-click an existing criterion, the new criterion is appended to the existing criterion as an
AND condition. It is added to the Rule Editor's tree view subsidiary to the criterion you selected.
6. When you have finished defining the rules for this service class, click Save.
Note: A service class is not completely defined until you assign its classification rules. The Save button
remains grayed out until you complete this step.

Editing a service class existing classification rule

To edit a service class's existing classification rules, complete these steps:
1. Within the Service Classes window, select the service class whose classification rules you want to
update, and click Edit Rule.
The Rule Editor window is displayed and shows the service class's existing classification rules.
2. In the Rule Editor window, you can add a new criterion, update the test strings assigned to an existing
criterion, or delete a criterion.
• To add a new criterion to the existing rule, right-click the Rule entry or the existing selection criterion
you want to apply it to, and select the new criterion type. Within the new value window, list the CICS
transactions, VTAM terminal IDs (LU name value), user IDs, or CICS region APPLIDs you want this
criterion tested against. Specify the test strings as previously noted.
• As before, if you add the new criterion at the same level as other criteria, it is an OR condition,
whereas if you add it at the subsidiary level, it is an AND condition.
• To edit an existing criterion, select it in the left pane of the Edit Rule window. Using the pane in the
Edit rule window, you can either append a new test string to those already present, edit an existing
test string, or delete an existing test string:

70 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 – To add a new test string, click Add in the pane.
The new value window is displayed. Enter one or more additional test strings, including the
wildcard character "*" if needed and separated by commas and click OK.
– To edit one of the criterion's existing test strings, select it in the pane, and click Edit.
The edit window is displayed. Edit the test string as appropriate. You can also append additional
test strings by inserting a comma at the end of the current string and then keying it in. Click OK.
– To delete one of the criterion's test strings, select it in the edit pane, and click Delete.
• To delete a criterion, right-click it, and select Delete. Deleting a criterion also deletes all criteria
subsidiary to it (in other words, those appended to it as AND conditions).
3. When you have finished updating the rule for this service class, click Save in the Rule Editor window.
After you have defined the appropriate classification rules for your service classes, your next step is
usually to define one or more service policies for your CICS environment and to activate one of them; see
“Adding or editing a service policy and activating a service policy” on page 71.

Adding or editing a service policy and activating a service policy

A service policy applies to all service classes defined for your enterprise. Service class goals vary by
service policy. Service policies let you override the base response time goals of the service class as
dictated by your site's varying requirements. For example, you could have one service policy for prime
shift operation, another for nighttime operation, and a third for weekend operation.
Your site's monitored environment can have only one service policy active at a time.
To add a new service policy, complete these steps:
1. Within the CICSplex SLA window's pane, right-click the CICSplex icon.
2. From the menu, select Create Service Policy.
The Create new Service Policy window is displayed.
3. Supply the new policy's name and description, and click OK.
The Service Policy name is a maximum of eight characters in length.
These are the valid characters for the Service Policy name: A-Z, a-z, 0-9 and any of the following
characters, $ @ # . / - _ % & ¢ ? ! : | = ¬ ; < >. Note, the comma (,) and double quote (") characters are not
valid.
The Service Policy description is a maximum of 24 characters in length. The valid characters are any basic
Latin ASCII characters.
A new service policy icon is added to CICSplex tree view. The icon added shows the new policy is inactive.
A default workload named DFLTSPOL is provided with IBM Z OMEGAMON for CICS.

Editing a service policy description or activating a service policy

To edit an existing service policy's description or to activate it, complete these steps:
1. Within the CICSplex SLA window's pane, select the service policy you want to edit or activate.
The accompanying pane changes to show the Service Policy parameters for the selected service policy.
Edit the Description field as needed.
2. If the selected service policy's Status field is inactive and you need to activate it (while simultaneously
deactivating the currently active policy), click Activate.
The service-policy icons shown in the CICSplex tree view illustrate which policy is active.
After you have defined the service policies for your installation and activated one of them, your next step
is to customize as necessary the predefined goals for the service classes within them; see “Overriding a
service class goal” on page 72.

Chapter 4. Configuring IBM Z OMEGAMON for CICS 71

 Overriding a service class goal
A service policy allows you to override a service class default goal without changing the goal for all
other service policies. This is important when, for example, setting different service requirements for
transactions running during the prime time shift than for those running at night.
To override a service class's default goal for a particular service policy:
1. Within the CICSplex SLA window, ensure you have expanded the service classes for the service policy
whose service class goals you want to override; if it is collapsed, select the plus sign, "+", to expand it.
2. Within the service policy's list of constituent service classes, select the class whose goal you want to
override.
The accompanying pane changes to show the Service Class parameters for the selected class.
Note: The workload name and description shown are only for your information; you cannot assign this
service class to a different workload or override the workload description using this pane.
3. Override the class's default Response Time and Goal area settings (for information on these
parameters, see “Adding or editing a service class” on page 69.
The service class icons shown in the expanded CICSplex tree view illustrate which classes have had
their goals overridden and which have not.
After you have assigned the appropriate overrides to this service policy's service class goals, you are
ready to set your site's CICSplex control values and to pass the updated SLA definitions to the Tivoli
Enterprise Portal Server and the Tivoli Enterprise Monitoring Server; continue with “Verifying the CICSplex
control settings and saving the updated service level analysis definitions” on page 72.

Verifying the CICSplex control settings and saving the updated service level
analysis definitions
The CICSplex control settings determine the workload management system your site is using to monitor
its service level analysis compliance and also how often the IBM Z OMEGAMON for CICS agent
accumulates the service level analysis data and sends it to the Tivoli Enterprise Monitoring Server for
processing and display by the Tivoli Enterprise Portal. When you have set the control parameters as
appropriate, you are ready to activate your monitored environment's service level analysis settings.
To set these values and activate your current service level analysis definitions, complete these steps:
1. If not already selected, select the CICSplex icon within the CICSplex SLA window.
The accompanying pane changes to show your installation's current CICSplex Control settings.
2. Within the CICSplex Control pane, in the Rules area, select the source of the workload management
rules you want to use, either z/OS's native z/OS workload manager or the workload manager provided
with IBM Z OMEGAMON for CICS or both.
z/OS WLM
Enables you to monitor your service level analysis environment using the workload manager native
to the z/OS operating system. The z/OS workload manager balances workloads across all z/OS
computing resources, including CICS regions, to prevent bottlenecks.
Note: If you select the z/OS WLM, the service policies, workloads, and service classes you create
using the CICS SLA view are ignored. IBM Z OMEGAMON for CICS instead uses the rules defined
for the z/OS workload manager.
If your site chooses the z/OS workload manager when monitoring its CICS service-level
compliance, this is the only procedure you need complete to activate it.
OMEGAMON WLM
IBM Z OMEGAMON for CICS offers its own service-level analysis based on workload definitions
similar to those provided by the z/OS workload manager. Using the CICS SLA view, you can
define your own service policies, workloads, and service classes and activate a service policy to

72 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 workspace on the performance of CICS transactions. These are the benefits of the OMEGAMON
WLM:
• It provides similar function in collecting service level data when your installation is not running
the z/OS workload manager in goal mode.
• It provides service-level data collected by IBM Z OMEGAMON for CICS in a manner similar to the
z/OS workload manager.
The service level analysis capabilities native to IBM Z OMEGAMON for CICS help you ensure
service level compliance without requiring the assistance of the system programmer who
configures and maintains your site's z/OS workload manager, nor does it require that the
z/OS workload manager even be active. The OMEGAMON workload manager ensures CICS SLA
compliance independent of the z/OS workload manager and its WLM definitions.
Unlike the z/OS workload manager, the native OMEGAMON workload manager does not perform
workload balancing. These are the other differences:
• The OMEGAMON workload manager does not support velocity goal definitions. Velocity goals do
not apply to CICS transactions.
• The OMEGAMON workload manager does not support definition of different periods.
Auto
Provides service level analysis using first the z/OS and then the native OMEGAMON workload
managers. IBM Z OMEGAMON for CICS's workload summarizer component ensures it can
communicate with the z/OS WLM and get a copy of its service classes and goals. If for any LPAR
the z/OS definitions cannot be obtained, OMEGAMON for CICS on z/OS uses the OMEGAMON
service classes and goals.
3. In the Collection Interval area, set the collection interval from the list. These are the values:
• 1 minute
• 5 minutes
• 15 minutes
• 30 minutes
• 1 hour
This value determines how often service level analysis data is summarized and made available for
historical data collection.
4. Click Save.
Your updated service level analysis objects and monitoring settings are written to the Tivoli Enterprise
Portal Server, and the monitoring settings are then passed to the Tivoli Enterprise Monitoring Server.
The IBM Z OMEGAMON for CICS monitoring agent picks them up within the next 60 seconds.
After you have set the CICSplex SLA monitoring values and activated them, you are ready to close the
CICS SLA view and return to the Tivoli Enterprise Portal Navigator Physical view; see “Returning to the
Navigator Physical view” on page 73.

Returning to the Navigator Physical view

When you have finished defining and activating the SLA environment for your monitored envirnment, you
are ready to return to the Tivoli Enterprise Portal Navigator Physical view.
To return to the Tivoli Enterprise Navigator Physical view, use these steps:
1. If you have closed the Tivoli Enterprise Portal view-selection window, select the down arrow to restore
it.
2. Either click the View list and select Physical, or select the Physical tab:
If you have made changes within the CICS SLA view and have not saved them, the Save workspace
window is displayed.

Chapter 4. Configuring IBM Z OMEGAMON for CICS 73

 3. To save your CICS SLA updates, click Yes.
The Navigator Physical view opens again.

Reverting changes to the CICSplex Control pane

If you make changes to the Rules or Collection Interval sections and want to put them back as they
were, click Revert to restore them. Note that the Revert function is only available before you click Save.

Deleting a service class

To delete a service class and dissociate it from its current workload, complete these steps:
1. Within the Service Classes window, select the service class you want to delete, and click Delete.
The Confirm delete of Service Class window is displayed and shows the service class that you want to
delete.
2. To confirm the deletion of the service class, click Yes.

Deleting a workload

To delete a workload, complete these steps:

1. Within the Workloads window, select the workload you want to delete, and click Delete.
If it is safe to delete the selected workload, the Confirm delete of Workload window is displayed and
shows the workload for deletion.
If the workload is still associated with one or more service classes and thus cannot be deleted, this
window shows the service class that references it; all you can do is click OK.
2. To confirm the deletion of the workload, click Yes.

Deleting a service policy

To delete a service policy, complete these steps:
1. Within the CICSplex SLA window, right-click the inactive service policy you want to delete.
You cannot delete the active service policy. You must first activate another; see “Adding or editing a
service policy and activating a service policy” on page 71.
2. From the menu, select Delete Service Policy.
The Confirm delete window is displayed and shows the service policy that you want to delete.
3. To confirm the deletion of the service policy shown, click Yes.

Configuring Service Level Analysis definitions using the enhanced

3270 user interface
Since version 5.5.0, you are able to configure Service Level Analysis definitions using the OMEGAMON
enhanced 3270 user interface (enhanced 3270UI). Service classes, workloads, and service policies
support the SLA feature within OMEGAMON for CICS on z/OS.
The Service Level Analysis facility enables you to set workload performance thresholds with which you
can monitor your CICS transactions to ensure they comply with your site's service level agreements. All
the SLA definitions that you configure using the enhanced 3270UI also take effect for your TEP session.

74 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Accessing the Service Level Configuration panel
Before you can access the Service Level Configuration panel and begin defining service classes,
workloads, and service policies, you must be an OMEGAMON enhanced 3270 user interface user with
the necessary security authority.

Viewing the Service Level Configuration panel

The Service Level Configuration Main Panel consists of two subpanels and several tabbed panels for
service class, workload, service policy, and SLA options.
Subpanels:
• Choosing Service Policy to Activate. You can choose which inactive service policy you want to activate
from the Service Policy list. Then, you can press APPLY and press Enter to save your choice. The default
service policy is DFLTSPOL.
• Service Classes of the service policy that you select. You can see all the service classes of the service
policy that you select. If service class contains override goals, its name and goal are highlighted in green
color.
Tabbed panels:
• Service Class. Service Class identifies the transactions that share common response time goals,
grouped by transaction IDs, user IDs, VTAM® terminal ID (that is, LU names), or CICS region APPLIDs.
A service class is associated with exactly one workload. The Service Class panel displays all the service
classes with base goal.
• Workload. A workload groups one or more service classes that you must monitor as a unit; with it, you
can monitor related service classes. In this SLA Workload panel, you can create, update, and delete
current workload via take actions.
• Service Policy. A service policy applies to all service classes defined for your enterprise. Service class
goals vary by service policy. Service policies let you override the base response time goals of the service
class as dictated by your site's varying requirements. For example, you might have one service policy for
prime shift operation, another for nighttime operation, and a third for weekend operation. In the Service
Policy panel, you can view, create, activate, and delete service policy via take action commands. The
active service policy is highlighted in green color.
• SLA Options. On the SLA Options panel, you can choose which rule to use and the interval from the
rules drop-down box. Select the source of the workload management rules you want to use, either
z/OS's native z/OS workload manager or the workload manager provided with OMEGAMON for CICS on
z/OS or both.
Figure 13. Service Level Configuration panel

Chapter 4. Configuring IBM Z OMEGAMON for CICS 75

 In most situations, you access the Service Level Configuration panel from the CICSplex Regions Summary
panel.
These are the ways to access the Service Level Configuration panel:
• Enter C next to any CICS region in the CICS Region Name column of the CICSplex Regions Summary
panel, then, at the CICS Control Functions panel enter 2 or C CICSplex Service Level Configuration to
view the Service Level Configuration panel.
• Enter / next to any CICS region name in the CICS Region Name column of the CICSplex Regions
Summary panel to access the Action Command Menu.
1. From the Action Command Menu, select 2. C CICS Control Functions.
2. From the CICS Control Functions panel, select 2. C CICSPlex Service Level Configuration to reach
the Service Level Configuration panel.

Using the Service Classes of DFLTSPOL subpanel

The Service Classes of DFLTSPOL subpanel displays all the service classes of the service policy that you
select from the service policy list. If service class contains override goal, its name and goal are highlighted
in green color.

Attributes used to report on statistical information for a SLA interval

The following attributes of a CICS region are used to report on statistical information for a SLA interval :
Service Class Name
The name of all the service classes of the service policy that you select in the upper subpanel. The
name is a maximum of eight characters in length.
Workload Name
The name of the workload assigned to each service class. Workload name is a maximum of eight
characters in length. A default workload named DFLTWORK is provided with OMEGAMON for CICS on
z/OS.

76 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Goal
Is the CICSplex Service Level Analysis Goal, which provides a summary of response time goal.
Percent Of Goal
Indicates the percent of the goal associated with this service class, in the range 0 – 99, and 0 is
average.

Adding, updating, and deleting override goal

You can add, update and delete override goal from the Service Class of DFLTSPOL subpanel on the Service
Level Configuration panel in the OMEGAMON enhanced 3270 user interface.
To add override goal, use these steps:
1. From the Service Class Configuration panel (Service Class of DFLTSPOL subpanel), either enter an A or
a / next to a Service Class Name.
The A takes you directly to the Add Override Goal panel while the / displays the Action Command
Menu.
a. On the Options Menu, type an A next to 1. A Add Override Goal and press Enter.
2. On the Add Override Goal panel, use the input fields to enter your Response Time Goal and Type of
Goal.
In Response Time Area, specify the response time that you expect for the CICS transactions that are
associated with this service class. In Type of Goal area, specify a percentage of matching transactions,
which must at least meet the response time that you specify. The percentage value is in the range 0 -
99. If 0 is specified, it is converted to average.
3. Once you have completed all the fields, press APPLY.
4. A message is displayed in the Take Action Results panel indicating that the goal was successfully
added.
Only for the service classes with existing override goals (which are highlighted in green color), you can
choose to update or delete their override goals.
• Updating override goal
To update override goal, type E next to the Service Class Name you wish to update and press Enter.
Overtype the fields you wish to change and press Enter.
• Deleting override goal
If you want to delete the override goal that you added for a service class, type D next to the Service
Class Name you wish to delete and press Enter. Press Enter again to confirm the deletion.

Editing the classification rule for a service class

The classification rules for a service class identify the CICS transactions that are associated with a
particular service class. You can view and update the rule for a service class, and delete the transaction
selection criteria from the Service Class Rule panel in the OMEGAMON enhanced 3270 user interface.
To edit the classification rule, use these steps:
1. From the Service Class Configuration panel (Service Class of DFLTSPOL subpanel), either enter an S or
a / next to a Service Class Name.
The S takes you directly to the Service Class Rule panel while the / displays the Action Command
Menu.
a. On the Options Menu, type an S next to 5. S Service Class Rule and press Enter.
2. On the Service Class Rule panel, use the input fields to enter your transaction-selection criteria. Enter
C to add CICSname, L to add LUname, T to add TranID, and U to add UserID.
You select one option in panel to enter the value; more criteria can be added later. The following
transaction-selection criteria can be assigned to this service class rule:

Chapter 4. Configuring IBM Z OMEGAMON for CICS 77

 TranID
Transactions in this service class are based on their transaction names.
LUname
Transactions in this service class are based on the VTAM terminal that invoked them.
UserID
Transactions in this service class are based on the user ID associated with them.
CICSname
Transactions in this service class are based on the CICS region that is running them. The CICSname
refers to the APPLID of the region, not the JOBNAME.
Note: In the Enhanced 3270 User Interface (e3270UI), you can enter more than one each of the
TranID and other selection criteria (LUname, UserID, and CICSname) in a service class. The entries
should be separated by commas; for example, CEMB, CEDF. In the Tivoli Enterprise Portal (TEP), you
can create service class rules with more than one TranID, LUname, UserID, or CICSname, by using the
Add command multiple times, adding one value each time. See Editing service class rules in the Tivoli
Enterprise Portal for details on how to do this in TEP.
3. To add an additional criterion to your rule, press Enter next to the Rule entry or the existing selection
criterion you want to apply it to, and select the new criterion type.
• If you right-click Rule, the new criterion is added to the existing criterion as an OR condition. It is
appended to the Rule Editor's tree view at the same level as the existing criteria.
• If you right-click an existing criterion, the new criterion is appended to the existing criterion as an
AND condition. It is added to the Rule Editor's tree view subsidiary to the criterion you selected.
4. Follow the intuitive guide in each panel to finish the definition. Press APPLY when you finish defining
the classification rules. You can also press PF1 to view the help information for the current panel.

Deleting a service class existing classification rule

If you want to delete a criterion, enter D next to the criterion and press Enter. Deleting a criterion also
deletes all criteria subsidiary to it (in other words, those appended to it as AND conditions).
If you want to delete one of the criteria subsidiary to a criterion , enter D next to the specific subsidiary
criterion and press Enter.

Using the Service Class tabbed panel

Service Class identifies the transactions that share common response time goals, grouped by transaction
IDs, user IDs, VTAM® terminal ID (that is, LU names), or CICS region APPLIDs. A service class is
associated with exactly one workload. The Service Classes tabbed panel displays all the service classes
with base goal.

Attributes used to report on statistical information for a SLA interval

The following attributes of a CICS region are used to report on statistical information for a SLA interval:
Service Class Name
Indicates the user-defined name that identifies a service class. The name is a maximum of eight
characters in length.
Workload Name
The name of the workload that is assigned to each service class. Workload name is a maximum of
eight characters in length. A default workload that is named DFLTWORK is provided with OMEGAMON
for CICS on z/OS.
Goal
Is the CICSplex Service Level Analysis Goal, which provides a summary of response time goal.
Percent Of Goal
Indicates the percent of the goal that is associated with this service class, in the range 0 – 99, and 0 is
average.

78 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Adding, updating, and deleting a service class
A service class identifies a block of related transactions that share common response time goals for a
single workload; the transactions must be related by transaction name, the user ID that invoked them,
the VTAM terminal ID (LU name) that submitted them, the CICS region running them, or any combination
thereof.
To define a new service class, complete the following tasks:
1. On the Service Class tabbed panel, either enter an A or a / next to a Service Class Name.
The A takes you directly to the Service Class Rule panel while the / displays the Action Command
Menu.
a. On the Options Menu, type an A next to 1. A Add New Service Class and press Enter.
2. On the Input Service Class Name panel, use the input fields to define a name for your new service
class and press APPLY.
The name must be characters with no white space.
3. On the Add Service Class panel, specify:
• Within the Response Time Goal area, specify the response time you expect for the CICS transactions
associated with this service class.
• Within the Type of Goal area, specify a percentage of matching transactions, which must at least
meet the response time that you specify. The percentage value is in the range 0 - 99. If 0 is specified,
the type of goal is converted to Average.
• Within the Workload area, select the existing workload you want to associate this service class with
from the list of available workloads.
4. Press APPLY.
IBM Z OMEGAMON for CICS provides 31 default service classes (ATRANS through ZTRANS, CSM1, CSM2,
CSM3, CSM5, and CSMI). Service classes ATRANS through ZTRANS cover transactions based on the
first character of the transaction name. Service classes CSM1, CSM2, CSM3, CSM5, and CSMI cover the
transactions with those names.

Updating an existing service class

To update an existing service class's workload and the response time settings, complete these steps:
1. On the Service Class tabbed panel, enter an S to the Service Class that you want to update and press
Enter.
2. On the Update Service Class panel, specify:
• Within the Response Time Goal area, specify the response time you expect for the CICS transactions
associated with this service class.
• Within the Type of Goal area, specify a percentage of matching transactions, which must at least
meet the response time that you specify. The percentage value is in the range 0 - 99. If 0 is specified,
the type of goal is converted to Average.
• Within the Workload area, select the existing workload you want to associate this service class with
from the list of available workloads.
3. Press APPLY.

Updating the classification rule for a service class

To update a service class's classification rule, complete these steps:
1. On the Service Class tabbed panel, enter an S to the Service Class that you want to update and press
Enter.
2. On the lower subpanel, use the input fields to enter your transaction-selection criteria. Enter C to add
CICSname, L to add LUname, T to add TranID, and U to add UserID.

Chapter 4. Configuring IBM Z OMEGAMON for CICS 79

 You select one option in panel to enter the value; more criteria can be added later. The following
transaction-selection criteria can be assigned to this service class rule:
TranID
Transactions in this service class are based on their transaction names.
LUname
Transactions in this service class are based on the VTAM terminal that invoked them.
UserID
Transactions in this service class are based on the user ID associated with them.
CICSname
Transactions in this service class are based on the CICS region that is running them. The CICSname
refers to the APPLID of the region, not the JOBNAME.
3. To add an additional criterion to your rule, press Enter next to the Rule entry or the existing selection
criterion you want to apply it to, and select the new criterion type.
• If you right-click Rule, the new criterion is added to the existing criterion as an OR condition. It is
appended to the Rule Editor's tree view at the same level as the existing criteria.
• If you right-click an existing criterion, the new criterion is appended to the existing criterion as an
AND condition. It is added to the Rule Editor's tree view subsidiary to the criterion you selected.
4. Follow the intuitive guide in each panel to finish updating the classification rules and press APPLY. You
can also press PF1 to view the help information for each current panel.
5. Press APPLY.

Deleting a service class existing classification rule

To delete a service class's classification rule, complete these steps:
1. On the Service Class tabbed panel, enter an S to the Service Class that you want to update and press
Enter.
2. On the lower subpanel, if you want:
• to delete a criterion, enter D next to the criterion and press Enter.
Deleting a criterion also deletes all criteria subsidiary to it (in other words, those appended to it as
AND conditions).
• to delete one of the criteria subsidiary to a criterion , enter D next to the specific subsidiary criterion
and press Enter.
3. Press Enter to confirm your deletion.

Deleting a service class

To delete a service class and dissociate it from its current workload, complete these steps:
1. On the Service Class tabbed panel, enter an D to the Service Class that you want to delete and press
Enter.
2. Press Enter to Confirm the deletion.

Using the Service Policy tabbed panel

A service policy applies to all service classes defined for your enterprise. Service class goals vary by
service policy. Service policies let you override the base response time goals of the service class as
dictated by your site's varying requirements.
You can use the tabbed panel to view, create, activate, and delete service policy via take action
commands. The active service policy is highlighted in green color.

80 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 Creating, activating, and deleting a service policy
To create a service policy, complete these steps:
1. On the Service Policy tabbed panel, enter an S next to a service policy.
2. On the Add New Service Policy panel, use the input fields to define a name for your new service policy
and give it a description.
3. Press APPLY.

Activating a service policy

To activate an existing service policy, complete these steps:
1. On the Service Policy tabbed panel, enter an A next to a service policy.
2. Press Enter to confirm your activation.
Only one service policy can be active.
You can also activate service policy in the General tabbed panel:
1. Switch to the General panel and select an inactive service policy that you want to activate from the
service policy list.
2. Press APPLY to make the service policy active.

Deleting a service policy

To delete a service policy, complete these steps:
1. On the Service Policy tabbed panel, enter an D to the Service Policy that you want to delete and press
Enter.
Note: You can delete only inactive service policies.

Using the Workload tabbed panel

A workload groups one or more service classes that you to monitor as a unit; with it, you can monitor
related service classes, highlighting the worst performing class within the group.
You can use this tabbed panel to create, update, and delete workload.

Creating, updating, and deleting a workload

To define a new workload, use these steps:
1. On the Workload tabbed panel, either enter an C next to a workload.
2. On the Add New Workload panel, use the input fields to define a name for your new workload and give
it a description.
3. Press APPLY to save your new workload.
A default workload named DFLTWORK is provided with IBM Z OMEGAMON for CICS.

Editing an existing workload

You can also change the description of an existing workload:
1. On the Workload tabbed panel, enter an S to the Service Class that you want to update and press
Enter.
2. On the Update Workload panel, use the input fields to edit the description as needed.
3. Press APPLY.

Chapter 4. Configuring IBM Z OMEGAMON for CICS 81

 Deleting a workload
To delete a workload:
1. On the Workload tabbed panel, enter an D to the Service Class that you want to delete and press
Enter.
2. Press Enter to Confirm the deletion.

Using the SLA Options tabbed panel

On the SLA Options tabbed panel, you can choose which rule to use and the interval from the interval list.
Select the source of the workload management rules you want to use, either z/OS's native z/OS workload
manager or the workload manager provided with IBM Z OMEGAMON for CICS or both. The rule can be set
as AUTO, MVS WLM, or OMEGAMON WLM.
The interval can be set as 1, 5, 15, 30, or 60 (in minutes). This value determines how often service level
analysis data is summarized and made available for historical data collection.
After you set the options, place the cursor on APPLY and press Enter to save your options.
After you make any changes to the SLA definitions, the OMEGAMON agents need to be notified of the
change. Place the cursor on UPDATE AGENTS and press Enter for OMEGAMON agents to be notified to
refresh the SLA definitions.

Configuring Service Level Analysis definitions using the batch

utility
OMEGAMON for CICS on z/OS has the CICS SLA view, which is an alternative Tivoli Enterprise Portal
view that enables you to set workload-performance thresholds to monitor your CICS transactions. It also
provides a batch utility that you can use to manage the definitions.
The Tivoli Enterprise Portal extension is used to create, modify, or delete service level analysis entries
and to manage the service classes, workloads, service policies and goals stored at the Tivoli Enterprise
Monitoring Server. While this process provides a manual control for the service level analysis definitions,
the kcp_slabatch utility addresses the need to change a large number of service classes automatically or
update these definitions on a regular basis through a command line interface.
The batch utility enables you to supply an input file that contains service level analysis definitions,
which are run in a batch process, removing the need to manually update your settings within the Tivoli
Enterprise Portal.
The batch utility has the following functions:
• A command line interface that reads a batch file for service level analysis definitions, issues the update
commands to the Tivoli Enterprise Monitoring Server, and provides feed back results to you upon
completion in a summary log file.
• A standard format (XML) for structuring data as part of the input file and for the output files, if you want
to write out the currently stored definitions. Also, you can write tools to generate the input files based
on your changing business requirements or import the output files to other tools in order to reflect these
changes.

Accessing the batch utility

Before you can access and begin using the kcp_slabatch utility and begin defining your site's service level
analysis environment, you must install Tivoli Enterprise Portal support and your Tivoli Enterprise Portal
user ID must have permission to view the CICS SLA view.
For the steps to gain access to the batch utility, see “Accessing the CICS SLA view” on page 67.

82 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Batch utility commands
The kcp_slabatch utility commands run from any command line console (or programmatically within a
batch file or script).
The kcp_slabatch utility is installed into the same folder as the packaged kcp_resources.jar
file. A DTD file, kcp_slabatch.dtd, is provided and installed in this same folder. Also installed
in this folder are wrapper script files you run to start the batch utility input process, and the
kcp_slabatch_sample.xml input XML file, that contains the default definitions.
The default location varies according to the operating system. For example, the Windows operating
system:

C:\IBM\ITM\CNP

For example, the Linux on Intel (32 bit) operating system:

/opt/IBM/ITM/Is3263/cw/classes

For example, the AIX® (32 bit) operating system:

/opt/IBM/ITM/ax3263/cw/classes

The kcp_slabatch utility requires Java 6.0 or higher. This Java version should be installed as part of your
IBM Tivoli Monitoring installation process. If you have a lower version of Java installed as the system JRE,
the utility may fail to start. To fix the version level of Java for a specific release use these steps:
1. Open the kcp_slabatch.bat (Windows) or kcp_slabatch.sh (UNIX or Linux) file in a text editor.
2. Find the section near the top of the file where the environment variable TEP_JAVA_HOME is declared
and uncomment this line.
3. Specify the path to the bin folder of the Java runtime environment you want to use.
4. Save the file and retry it using the utility. Comment the line out again, if you wish to revert back to your
Java runtime environment.
This is the basic command line interface:

kcp_slabatch <command Name> [list of optional arguments specific to the command]

These are the kcp_slabatch utility commands:

Table 12. kcp_slabatch utility commands

Command Description
import Uses the supplied XML input file to update the
definitions at the hub Tivoli Enterprise Monitoring
Server.
export Writes all the current service level analysis
definitions to the output XML file.
validateserviceclass Identifies any service classes that do not have a
corresponding defined rule. Any service classes
that are found to be not valid are written out to
the log stream and can be deleted automatically, if
requested.
help The name of all the available CLI commands and a
short description of each command.

See:
• “Using the kcp_slabatch import command” on page 84

Chapter 4. Configuring IBM Z OMEGAMON for CICS 83

 • “Using the kcp_slabatch export command” on page 85
• “Using the kcp_slabatch validateserviceclass command” on page 86
• “Using the kcp_slabatch help command” on page 87

Using the kcp_slabatch import command

Use the import command to perform batch updates to the CICS SLA definitions stored at the hub Tivoli
Enterprise Monitoring Server.
You must supply details of the Tivoli Enterprise Portal Server user credentials, and the location of the
input XML document that contains your definition updates. By default, the command processes the whole
input file regardless of errors in processing individual commands; the Tivoli Enterprise Portal Server and
hub Tivoli Enterprise Monitoring Server must be online for this command to run successfully.
Note: If you want to restore the default settings, a sample XML file is provided that contains these
definitions.
CLI syntax

kcp_slabatch import [-s|--server] hostname

[-t|--port] port to connect to
{-u|--username} username
[-p|--password] password
{-i|--inputfile} path to input file
[-e|--failOnFirstError]
[-v|--verbose]
[-n|--noOutput]

Where:
[-s|--server] hostname
The hostname of the Tivoli Enterprise Portal Server that is used for the connection. If not specified, a
default setting of localhost is assumed. (Optional)
[-t|--port] port to connect to
The port number of the Tivoli Enterprise Portal Server that is used for the connection. If not specified,
a default setting of 1920 is assumed. (Optional)
{-u|--username} username
Specifies the existing name for user authentication. (Required)
[-p|--password] password
Specifies the password for user authentication. If there is no security enabled, then no password is
required and no information is sent. (Optional)
{-i|--inputFile} path to input file
Specifies the absolute path to the XML document that is used as input for your changes to the service
level analysis definitions. (Required)
[-e|--failOnFirstError]
The batch updates stop once when an update request fails, because later requests might be
dependent on earlier requests. Using this command allows further errors to be avoided. (Optional)
[-v|--verbose]
Provides the detailed output of the batch utility. The logging information is displayed to the standard
out console. By default, this is not enabled. (Optional)
[-n|--noOutput]
Suppresses the console output; no output is displayed to the interface and logging continues. Use this
option, if the command is called within an automated script or process. By default, this is not enabled.
(Optional)
CLI example
This command connects to the Tivoli Enterprise Portal Server on leighton.ibm.com using the
username, sysadmin, and password, passw0rd. The C:\temp\MyNewSLADefinitions.xml input

84 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 file is used to define what service level analysis definitions are changed. On the first error encountered
when processing this file, the processing stops.

kcp_slabatch import –s leighton.ibm.com –u sysadmin –p passw0rd –i

C:\temp\MyNewSLADefintions.xml -e

Using the kcp_slabatch export command

Use the export command to list the current definitions stored at the hub Tivoli Enterprise Monitoring
Server.
The output is returned as an XML document which you can use as a basis for future input files to update
your definitions. You must supply details of the Tivoli Enterprise Portal Server user credentials, and
the location for the output XML document. The Tivoli Enterprise Portal Server and hub Tivoli Enterprise
Monitoring Server must be online for this command to run successfully.
CLI syntax

kcp_slabatch export [-s|--server] hostname

[-t|--port] port to connect to
{-u|--username} username
[-p|--password] password
{-o|--outputFile} path to output file
[-v|--verbose]
[-n|--noOutput]
[-l|--listAsCreate]

Where:
[-s|--server] hostname
The hostname of the Tivoli Enterprise Portal Server that is used for the connection. If not specified, a
default setting of localhost is assumed. (Optional)
[-t|--port] port to connect to
The port number of the Tivoli Enterprise Portal Server that is used for the connection. If not specified,
a default setting of 1920 is assumed. (Optional)
{-u|--username} username
Specifies the existing name for user authentication. (Required)
[-p|--password] password
Specifies the password for user authentication. If there is no security enabled, then no password is
required and no information is sent. (Optional)
{-o|--outputFile} path to output file
Specifies the absolute path to the XML document that is used as the output for your current service
level analysis definitions. (Required)
[-v|--verbose]
Provides the detailed output of the batch utility. The logging information is displayed to the standard
out console. By default, this is not enabled. (Optional)
[-n|--noOutput]
Suppresses the console output; no output is displayed to the interface and logging continues. Use this
option, if the command is called within an automated script or process. By default, this is not enabled.
(Optional)
[-l|--listAsCreate]
Lists all component tags as output with action=create attributes. This allows the file to be read
into another system or can be used to restore a backup without modification. By default, this is not
enabled. (Optional)

Chapter 4. Configuring IBM Z OMEGAMON for CICS 85

 CLI example
This command connects to the Tivoli Enterprise Portal Server on leighton.ibm.com using the
username, sysadmin, and password, passw0rd. The current service level analysis definitions are
written to C:\temp\MyNewSLADefinitions.xml, but no output is written to the console.

kcp_slabatch export –s leighton.ibm.com –u sysadmin –p password –o

C:\temp\MyNewSLADefintions.xml -nooutput

Using the kcp_slabatch validateserviceclass command

Use the validateserviceclass command to identify and delete, if requested, any service classes that do
not have a corresponding defined classification rule.
Any definitions that fail the test are listed in the SLA batch log. The kcp_slabatch utility connects to the
Tivoli Enterprise Portal Server and performs the validation of all the currently defines service classes.
CLI syntax

kcp_slabatch validateserviceclass [-s|--server] hostname

[-t|--port] port to connect to
{-u|--username} username
[-p|--password] password
[-d|--deleteAll] delete all Service class definitions
[-v|--verbose]
[-n|--noOutput]

Where:
[-s|--server] hostname
The hostname of the Tivoli Enterprise Portal Server that is used for the connection. If not specified, a
default setting of localhost is assumed. (Optional)
[-t|--port] port to connect to
The port number of the Tivoli Enterprise Portal Server that is used for the connection. If not specified,
a default setting of 1920 is assumed. (Optional)
{-u|--username} username
Specifies the existing name for user authentication. (Required)
[-p|--password] password
Specifies the password for user authentication. If there is no security enabled, then no password is
required and no information is sent. (Optional)
[-d|--deleteAll] delete all Service class definitions
Automatically deletes all Service Class definitions that fail the validation test. By default, this is not
enabled. (Optional)
[-v|--verbose]
Provides the detailed output of the batch utility. The logging information is displayed to the standard
out console. By default, this is not enabled. (Optional)
[-n|--noOutput]
Suppresses the console output; no output is displayed to the interface and logging continues. Use this
option, if the command is called within an automated script or process. By default, this is not enabled.
(Optional)
CLI example
This command connects to the Tivoli Enterprise Portal Server on leighton.ibm.com using the
username, sysadmin, and password passw0rd, performs a validation test, and deletes, if necessary,
any service classes that do not have a defined rule.

kcp_slabatch validateserviceclass –s leighton.ibm.com –u sysadmin –p passw0rd -d

86 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Using the kcp_slabatch help command
Use the help command to display the name and short description of all the available CLI commands or to
display the complete help for a specified command.
CLI syntax

kcp_slabatch help [command name]

or

kcp_slabatch ? [command name]

Where:
[command]
Specifies the command for which you want detailed help.
CLI example
This command displays the name and short description of all the available CLI commands.

kcp_slabatch help
or
kcp_slabatch ?

This command displays the detailed help for the export command.

kcp_slabatch help export

or
kcp_slabatch ? export

Using XML to format definitions

XML is the standard format used for structuring data as input and output files for your stored definitions.
The contents of all your tags within the document, including tag names and elements, are not case
sensitive.
The Document Type Definition (DTD) (kcp_slabatch.dtd) defines what is the valid XML format for the
kcp_slabatch utility and verifies if you have created data that can be imported without any problems.
The top level of your XML document must have encoding. The default setting for encoding is ISO-8859-1
and this must be added on the first row of any exported file. Because ISO-8859-1 is the default setting, if
you do not supply this line, the processing will continue.
For example:

<?xml version='1.0 encoding='ISO-8859-1' ?>

The next line in your document must have a reference to the DTD file, which allows you to validate that
your XML format is correct. The kcp_slabatch utility uses the DTD file when importing a document. By
default, the DTD file is found in the same folder as your XML file. If this is not the case, you must perform
one of the following actions:
• Copy the DTD file into the same folder as the XML file.
• Edit this line in the XML file so the path to the DTD file (for example,
C:\IBM\ITM\CNP\kcp_slabatch.dtd) is correct:

<!DOCTYPE CicsSlaDefinitions SYSTEM "kcp_slabatch.dtd">

---
</CicsSlaDefinitions>

The<CicsSlaDefinitions> tag is the root element for the document and all subsequent elements are
nested within this tag. When you export definitions, the output has a timestamp and a description of the
log file location. The timestamp is displayed as a comment line in the file.

Chapter 4. Configuring IBM Z OMEGAMON for CICS 87

 The XML document can list the primary elements in any order, but the utility imports all elements of a
particular type in order. That is, all Workloads first, then Service Class, then Service Policy, then Control,
and ActivePolicy. Each instance represents a single row within the respective SLA table. The order in
which these tags are displayed is not enforced (for example, a Workload element could be defined first,
then a Service Class element, followed by a second Workload element), but when the file is processed
it is completed in order. For example, if a Service Class element refers to a Workload element, then that
Workload element must have already been defined in the file or existed previously in the SLA tables.
For example:

<Workload>
---
</Workload>
<ServiceClass>
---
</ServiceClass>
<ServicePolicy>
---
<ServicePolicy>

The tags on the next level of the document identify the elements for each component.
The structure of the Workload element contains a name and a description.
For example:

<Workload>
<Name>...</Name>
<Description>...</Description>
</Workload>

These are the tags for the Workload element and their values:

Table 13. Tags for the Workload element and their values
Element name Description
A maximum of eight characters in length.
<Name>...</Name>
These are the valid characters: A-Z, a-z, 0-9 and
any of the following, $ @ # . / - _ % & ¢ ? ! : | =
¬ ; < >. Note, the comma (,) and double quote (")
characters are not valid. Any lowercase characters
you supply are converted to uppercase.

A maximum of 24 characters in length.

<Description>...</Description>
The valid characters are any basic Latin ASCII
characters.

The structure of the ServiceClass element adds the first complexity by requiring a BaseGoal attribute to
be defined.
For example:

<ServiceClass>
<Name>...</Name>
<WorkloadName>...</WorkloadName>
<Rule>...</Rule>
<BaseGoal>
<ResponseTime>...</ResponseTime>
<PercentOfGoal>...</PercentOfGoal>
</BaseGoal>
</ServiceClass>

Note: The WorkloadName element referred to in this example must already exist in the WORKLOAD table
for the ServiceClass element to be created successfully.

88 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 14. The ServiceClass element and their values
Element name Description
A maximum of eight characters in length.
<Name>...</Name>
These are the valid characters: A-Z, a-z, 0-9 and
any of the following, $ @ # . / - _ % & ¢ ? ! : | =
¬ ; < >. Note, the comma (,) and double quote (")
characters are not valid. Any lowercase characters
you supply are converted to uppercase.

A maximum of eight characters in length.

<WorkloadName>...</WorkloadName>
These are the valid characters: A-Z, a-z, 0-9 and
any of the following, $ @ # . / - _ % & ¢ ? ! : | =
¬ ; < >. Note, the comma (,) and double quote (")
characters are not valid. Any lowercase characters
you supply are converted to uppercase.

A maximum length of 1000 characters and does

<Rule>...</Rule>
not convert the expression into another format
from the Reverse Polish Notation (RPN). Contains
the rule used to identify the transactions that are
applicable to this ServiceClass attribute in RPN.
These are the valid characters: A-Z, a-z, 0-9 and
any of the following, $ @ # . / - _ % & ¢ ? ! : | =
¬ ; < >. Note, the comma (,) and double quote (")
characters are not valid. Any lowercase characters
you supply are converted to uppercase.
Note: Ensure that your RPN is valid before
attempting to import definitions. Any lowercase
characters you supply for rule values are converted
to uppercase. The rule type labels (TranID, UserID,
CICSname, LUname) are case sensitive and must
be written in this form.

Identifies the data that appears within the GOAL

<BaseGoal>...</BaseGoal>
table.
A four byte integer that represents the time goal in
<ResponseTime>...</ResponseTime>
thousands of a second (0.001 seconds).
An integer running between 0 and 100. If the value
<PercentOfGoal>...</PercentOfGoal>
is 0, then the monitoring agent interprets this as an
average goal rather than a percentage.

The ServicePolicy element is similar to ServiceClass element in that goals can be defined; for example, an
OverrideGoal. Only BaseGoals that have been overridden are shown in this example:

<ServicePolicy>
<Name>...</Name>
<Description>...</Description>
<OverrideGoal>
<ServiceClassName>...</ServiceClassName>
<ResponseTime>...</ResponseTime>
<PercentOfGoal>...</PercentOfGoal>
</OverrideGoal>
</ServicePolicy>

Note, that unlike the Service Class description, which must have a single base goal, a ServicePolicy
element can have zero, one, or many override goals. At most there would be an override goal definition for

Chapter 4. Configuring IBM Z OMEGAMON for CICS 89

 each Service Class element that has been defined. The constraints on the various fields are the same as
for the Workload and Service Class elements. When you are defining an OverrideGoal element, the Service
Class element you are overriding, must specify the base goal.

Table 15. The ServicePolicy element and their values

Element name Description
A maximum of eight characters in length.
<Name>...</Name>
These are the valid characters: A-Z, a-z, 0-9 and
any of the following, $ @ # . / - _ % & ¢ ? ! : | =
¬ ; < >. Note, the comma (,) and double quote (")
characters are not valid. Any lowercase characters
you supply are converted to uppercase.

A maximum of 24 characters in length.

<Description>...</Description>
The valid characters are any basic Latin ASCII
characters.

The Control element represents the collection interval and workload management of SLA definitions. For
example:

<Control>
<CollectionInterval>...</CollectionInterval>
<WLMType>...</WLMType>
</Control>

The CollectionInterval value determines the summarization interval for historical collection.
The CollectionInterval value is the time of the format HHMM, where HH is 00 or 01 and MM (if HH is 00) is
01 or 05 or 15 or 30.
SLA collection allows only one of these values:
• 0001
• 0005
• 0015
• 0030
• 0100
If you want to change the collection interval from the default 15 minutes to 1 hour, define the value as
follows:

<CollectionInterval>0100</CollectionInterval>

If you want to change the collection interval to 1 minute, define the value in the following XML format:

<Control>
<CollectionInterval>0001</CollectionInterval>
</Control>

The WLMType is one of following values:

• OMEGAMON
• z/OS
• AUTO

90 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

These values are the different Workload Manager types; the same values that appear in the CICS SLA
view. If you want to switch to the OMEGAMON WLM type, you define the value in the following XML
format:

<Control>
<WLMType>OMEGAMON</WLMType>
</Control>

The value within the tags is not case sensitive.

The final tag for this level of the XML document represents the active service policy.
For example:

<ActivePolicy>
---
</ActivePolicy>

Defining actions in the XML document

If you make a request to export the current CICS SLA definitions to a file, your XML document contains the
tags previously discussed.
The other purpose for using an XML document is to import only the values that you want to change.
Use the action attribute tag to indicate what type of task is needed to perform with the current primary
component. These are the main action attribute tags:
• Create
• Edit
• Delete
In general, when you create a new definition most elements are required. When you edit a definition, the
name is required and any elements you want to update. When you want to delete an element only the
name is needed. In the following example, a new workload is created (WKLOAD1), an edit is performed
for the description of the workload element, and a delete action is performed on the workload element:

<Workload action="create">
<Name>WKLOAD1</Name>
<Description>Some description</Description>
</Workload>
</Workload action="edit">
<Name>WKLOAD1</Name>
<Description>An alternate description</Description>
</Workload>
<Workload action="delete">
<Name>WKLOAD1</Name>
</Workload>

These are the values that are needed for the Workload element:

Table 16. Values for the Workload element in a XML document

Action Required Values
Create The <Name> and <Description> values must be
specified.
Edit The <Name> value is needed. The <Description>
value is optional.
Delete The <Name> value is needed.

These are the values that are needed for the ServiceClass element:

Chapter 4. Configuring IBM Z OMEGAMON for CICS 91

 Table 17. Values for the ServiceClass element in a XML document
Action Required Values
Create The values for all the tags are needed. <Name>,
<WorkloadName>, <Rule>, and <BaseGoal>. For
the <BaseGoal> value, you need to specify the
<PercentOfGoal> and <ResponseTime> values.
Edit The <Name> value is needed. All other fields are
optional. For the <BaseGoal> value, you need to
specify the <PercentOfGoal> and <ResponseTime>
values; the fields not specified remain unchanged.
Delete The <Name> value is needed. When you delete the
<ServiceClass> value, you delete all the override
goals that you might have used. You cannot delete
the currently active service policy.

For example:

</ServiceClass action="create">
<Name>ABTRANS</Name>
</WorkloadName>WKLOAD</WorkloadName>
<Rule>TransID 'ABCD, I2*, A2*' =
CICSname 'CICS0001, CICSA*, CICSI*' =
UserID 'RG' = & & "</Rule>
UserID 'TERI' =
TranID 'T*' =
CICSname 'CICST*' =
LUname 'M2400000' = & & &
| </Rule>
<BaseGoal>
<ResponseTime>3723004</ResponseTime>
<PercentOfGoal>23</PercentOfGoal>
</BaseGoal>
</ServiceClass>
<ServiceClass action="edit">
<Name>ABTRANS</Name>
<Rule> TranID 'I2EX' =
CICSname 'CICS0001, CICSA*, CICSI*' =
UserID 'RG' = & & </Rule>
</ServiceClass>
<ServiceClass action="delete">
<Name>ABTRANS</Name>
</ServiceClass>

These are the values that are needed for the Service Policy element:

Table 18. Values for the Service Policy element in a XML document
Action Required Values
Create The values for the <Name> and <Description>
values are needed. The <OverrideGoal> value is
optional. For the <OverrideGoal> value, you need
to specify the <ServiceClass>, <PercentOfGoal>
and <ResponseTime> values.
Edit The <Name> value is needed. All other fields are
optional. See the Override Goal attribute table for
updating the <OverrideGoal> value.
Delete The <Name> value is needed. When you delete the
<ServicePolicy> value, you delete all override goals
that you might have used. You cannot delete the
<ServicePolicy> value that is currently active.

92 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

These are the values that are needed for the Override Goal element:

Table 19. Values for the Override Goal element in a XML document
Action Required Values
Create The values for the <ServiceClass>,
<PercentOfGoal> and <ResponseTime> values
must be specified.
Edit The <ServiceClassName> value is needed. The
<PercentOfGoal> and <ResponseTime> values are
optional.
Delete The <ServiceClassName> value is needed. By
deleting the Override Goal value, the Service Policy
value reverts back to using the Base Goal value for
the specified Service Class.

Only one policy can be active at any given time and that policy must already be defined. For example:

<ActivePolicy>NEWSPOL</ActivePolicy>

Exporting current SLA definitions

The current SLA definitions are exported in this precise order.
1. Workloads
2. Service Classes (including base goals)
3. Service Policies (including any override goals)
4. Collection interval and WLM that is used
5. Active Service Policy
These SLA definitions are also imported in the same order as the export mechanism.
OMEGAMON for CICS on z/OS supplies a kcp_slabatch_sample.xml file, that contains default SLA
definitions (the definitions that are populated in the table, when OMEGAMON for CICS on z/OS is initially
installed). You can use the file as a template for other edits or changes. All the tags in the sample file have
the action="create" attribute.

Using the summary log file for importing definitions

In addition to any command line output, a summary log file is produced that details the changes made as
part of the batch utility process.
Use the summary log file when you import SLA definitions to see each definition that was read,
what action was used (Edit, Create or Delete), and whether your change was successfully completed.
Once the processing is done, a summary table is produced and is located in <ITMHome>/logs/
kcp_slabatch_<timestamp>.log. The <timestamp> variable is the date and time that the
kcp_slabatch utility process started.
For example:

C:\IBM\ITM\logs\kcp_slabatch_200804031311.log

Here is a sample summary log file output:

IBM Z OMEGAMON for CICS – SLA Command Line Utility

© Copyright IBM Corporation 2011. All rights reserved
13/02/2008 12:00:01 – KCP1234I Starting update of SLA definitions
13/02/2008 12:00:01 – KCP1234I Using input file C:\temp\MyNewDefinitions.xml

Chapter 4. Configuring IBM Z OMEGAMON for CICS 93

 13/02/2008 12:00:01 – KCP1234I Connecting to TEPS hostname: localhost port: 1918
13/02/2008 12:00:01 – Request [00001] - Calling DELETE on WORKLOAD (Name: DFLTWLD)
13/02/2008 12:00:02 – Request [00001] - Action completed successfully
13/02/2008 12:00:02 – Request [00002] - Calling CREATE on SERVICE CLASS (Name: CTRANS)
13/02/2008 12:00:02 – Request [00002] - Action completed successfully
13/02/2008 12:00:02 – Request [00003] - Calling EDIT on WORKLOAD (Name: DFLTWLD)
13/02/2008 12:00:02 – Request [00003] - Action completed successfully
…
13/02/2008 12:00:10 – KCP1234I Disconnecting from TEPS
SUMMARY OF UPDATES
Total number of CREATE requests: 20
Total number of EDIT requests: 6
Total number of DELETE requests: 2
Total number of all requests: 28
Total number of successful requests: 20
Total number of errors: 8
KCP1234I The command completed successfully. Return code = 1

Return codes for the batch utility

These are the return codes for the kcp_slabatch utility.

Table 20. Return codes for the kcp_slabatch utility

Code Category Description
0 Success The command completed
successfully.
-1 Serious error A serious error has occurred and
a correct return code was not set.
1 Completed but with some errors The command completed, but
there was at least one error
generated when processing (for
example, one update was missing
some parameters)
2 Syntax error or help The help command was issued or
the syntax was not understood;
processing did not start.
3 No permission You do not have permission to
issue the command. You could
not log on to the Tivoli Enterprise
Portal Server or you do not
have authority to modify the SLA
definitions.
4 Version mismatch The version that was found on
the server does not match what
was expected for processing.
5 Communication error There was a communication error
when communicating with the
Tivoli Enterprise Portal Server.
For example, the Tivoli Enterprise
Portal Server is offline
6 File not found The input file for the command
was not found or the export file
cannot be written out.
7 Unknown error Any other error.

94 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Chapter 5. Reference
This section contains information you can refer to as you configure historical data collection or secure
the OMEGAMON for CICS on z/OS components. It also contains reference information that pertains to
features in the OMEGAMON for CICS component.

Enabling security for OMEGAMON XE and OMEGAMON for CICS

The security options you decide to employ can determine tasks you must complete in advance, such as
arrangements you must make with security administrators or accounts you must set up. Your security
decisions can also dictate certain choices during configuration, such as the selection of secure protocols
when configuring communication between components.
Tivoli Management Services and the OMEGAMON XE monitoring agents offer several security options:
• Secure communication between components
• Authorization and authentication of Tivoli Enterprise Portal users (including single sign on capability)
• Authentication of OMEGAMON enhanced 3270 user interface, OMEGAMON for CICS (3270) user
interface
• Authentication of SOAP server users
• Authentication of IBM Tivoli Monitoring Service Console users
• Authorization of z/OS Take Action commands by NetView®
For information about enabling security, see "Decision 9: Which security options to enable" which is in the
Planning section of OMEGAMON shared documentation Version 6.3.0 Fix Pack 2.

Securing OMEGAMON for CICS on z/OS Take Action commands

The OMEGAMON for CICS on z/OS has the capability to use Take Action commands against specific CICS
resources. These Take Action commands might be as a result of requests from an OMEGAMON enhanced
3270 user interface request, a Tivoli Enterprise Portal user request, or a defined situation using the Tivoli
Enterprise Portal.
These Take Action commands can be secured using the RTE_SECURITY_CLASS parameter, which is
defined for the OMEGAMON enhanced 3270 user interface. When you specify this class and it is not set to
the reserved name, OMEGDEMO, the OMEGAMON for CICS on z/OS agent uses this class to validate a users
authority to issue commands. The RTE_SECURITY_CLASS parameter is described in OMEGAMON shared
documentation Version 6.3.0 Fix Pack 2.

Resource names used for Take Action commands by the agent

The OMEGAMON enhanced 3270 user interface will validate against the following resource name for Take
Action commands directed at the CICS resource to see if users are authorized to issue the request:

KCP.smfid.cicsname.TAKEACTION

Where smfid and cicsname refer to the location and name of the CICS region that is being acted upon. The
OMEGAMON for CICS on z/OS agent builds upon this name to further qualify the request.
A Take Action command is automatically invoked when a situation becomes TRUE, and is run under the
userID that last created or modified it.
The resource names for the AIDK (KILL AIDS), ICEK (KILL ICES), RLIM, TRACE, and WTO Take Action
commands have no predictable values.
These are the resource names:
• KCP.smfid.cicsname.TAKEACTION.KILL.AIDS

© Copyright IBM Corp. 2004, 2022 95

 • KCP.smfid.cicsname.TAKEACTION.KILL.ICES
• KCP.smfid.cicsname.TAKEACTION.RLIM
• KCP.smfid.cicsname.TAKEACTION.TRACE
• KCP.smfid.cicsname.TAKEACTION.WTO
The CEMT SET Take Action command has many different options. You can define specific profiles to
provide finer granularity for selected options; specify a profile for each individual option.
For example:

KCP.smfid.cicsname.TAKEACTION.SET.CEMT.option

Where option is FILE or PROGRAM.

• KCP.smfid.cicsname.TAKEACTION.SET.CEMT.FILE
• KCP.smfid.cicsname.TAKEACTION.SET.CEMT.PROGRAM
This format forces users to always specify the full command syntax in the Take Action commands. (No
attempt is made to use the CICS abbreviation when building the resource name.)
To provide maximum flexibility in specifying the CEMT SET command and to prevent errors, use a profile
with the CICS abbreviation for these options:
• KCP.smfid.cicsname.TAKEACTION.SET.CEMT.FI*
• KCP.smfid.cicsname.TAKEACTION.SET.CEMT.PROG*
No attempt is made to use the CICS abbreviation for the option when building the resource name, and no
attempt is made to validate that the option you specify is valid for your version of CICS Transaction Server.
Use this generic profile to control all SET commands unless more specific profiles exist:

KCP.smfid.cicsname.TAKEACTION.SET.CEMT.*

When deleting transient data and temporary storage queues, the resource generated contains the name
of the queue being deleted.
The value is the queuename in character form, for the TDDL (TDQ DELETE) Take Action command:
• KCP.smfid.cicsname.TAKEACTION.DELETE.TDQ.queuename
• KCP.smfid.cicsname.TAKEACTION.DELETE.TDQ.*
However, for the TSQD (TSQ DELETE) Take Action command, the value is still the queuename, but it can
be specified in either hexadecimal or character form.
To prevent bypassing of your security environment, you should specify a profile for both forms as in the
following examples:
• KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.HEXhexqueuename
• KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.HEX.*
• KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.queuename
• KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.*
where hexqueuename is the name of the queue in hexadecimal form and queuename is in character form.
When you attempt to delete a temporary storage queue using the hexadecimal queue ID, the request is
first validated using the hex queue ID; if that is allowed or no security decision can be made, the request
is then validated again using the character form of the queue ID. If that is allowed or no decision can be
made, then access is allowed or denied in the following order:
• Hex Queue ID=permitted and Queue ID=permitted → delete request allowed
• Hex Queue ID=no decision and Queue ID=permitted → delete request allowed
• Hex Queue ID=permitted and Queue ID=no decision → delete request allowed

96 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

• Hex Queue ID=no decision and Queue ID=no decision → delete request not allowed
Note: If either access is denied or either access query returns an error, the delete request is not allowed.
You enter the following Take Action command:

CP:TSQD ID=D6D4C5C7C1D4D6D5F1F2F3F4F5F6F7F8 HEX

This command is first validated against the following resource:

KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.HEX.D6D4C5C7C1D4D6D5
F1F2F3F4F5F6F7F8

If that is allowed or no decision can be made, it would be validated against the following resource:

KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.OMEGAMON12345678

These are examples of profile or user permission combinations that allow the command:
• KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.OMEG* ACC(READ)
The first result is no decision and the second is allowed.
• KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.HEX.* ACC(READ)
The first result is allowed, and the second is no decision.
• KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.HEX.* ACC(READ)
KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.OMEG* ACC(READ)

The first and second results are allowed.

These are examples of profile or user permission combinations that would deny the command:

KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.HEX.* ACC(READ)
KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.OMEG* ACC(NONE)
KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.HEX* ACC(NONE)

In the first example, the first result is allowed and the second is not allowed.
In the second example, no profile and the first and second results are no decision.
In the third example, the first result is allowed and the second result is not validated.
If the character form of the queuename contains special characters (blank, ampersand, asterisk, percent),
these are changed to a question mark for profile comparisons.

Updating CICSplex rules

The resource name that is generated when you update a CICSplex rule is slightly different. The
OMEGAMON enhanced 3270 user interface validates your authority to issue a Take Action command
against a specific CICS region, however, the agent will validate your authority against the CICSplex name
as follows:

KCP.cicsplexname::CICSplex.TAKEACTION.RULES

where cicsplexname is the name of the CICSplex being monitored.

Using generic profiles to define resources

The verification of the resource names allows for the specification of generic profiles. For example:

KCP.smfid.*.TAKEACTION.** ACCESS(READ)

This example enables you to issue Take Action commands against all the CICS regions for a specific LPAR.
Conversely, you could specify:

Chapter 5. Reference 97
 KCP.*.CICSP*.** ACCESS(READ)

This example, you access to all CICS regions beginning with the letters CICSP on any LPAR.
If you want access to all CICS resources you would specify:

KCP.** ACCESS(READ)

Security defined in Version 4.2.0

If you specified FTA Security in Version 4.2.0, then OMEGAMON for CICS on z/OS allowed for the use of
Take Action security. If you have specified FTA security using the Configuration Tool in previous releases,
then FTA security would be active, and the parameters used are inherited for releases after V4.2.0. In
this case, however, the format of the resource name will match what was used for the prior version. The
resource names will be the same as described previously except that the format will change from:

KCP.smfid.cicsname.TAKEACTION....

to

cicsname.KCP...

To allow access for the OMEGAMON enhanced 3270 user interface, configure a resource profile as
follows:

KCP.smfid.cicsname.TAKEACTION ACC(READ)

Security considerations
The only consideration for security would be whether or not to continue using the OMEGAMON for CICS
on z/OS FTA security, if it was enabled, or to enable the new Global SAF security for CP: common Take
Action command processing. See “Securing OMEGAMON for CICS on z/OS Take Action commands” on
page 95.

Adding the NetView CNMLINK library to the Tivoli Enterprise Monitoring

Server or agent started task
The NetView for z/OS CNMLINK data set is required to connect to NetView for z/OS.
PARMGEN generates the applicable started task with the following lines commented out. Uncomment the
DD card in the RKANMODL that points to the NetView for z/OS CNMLINK data set:

//******************************************************************
//* RKANMODL DD: CNMLINK
//******************************************************************
//* Uncomment this DD card to specify the IBM Tivoli NetView for z/OS
//* CNMLINK dataset. This dataset is required for the "Forward Take
//* Action commands to NetView for z/OS" support which is enabled.
//* The CNMLINK library must be APF-authorized. Contact your NetView
//* for z/OS system programmer for the dataset name.
//* DD DISP=SHR,
//* DSN=NETVIEW.V5R2M0.CNMLINK
//*

If you are doing a reconfiguration and you did uncomment the DD card that points to the CNMLINK library,
refresh the Tivoli Enterprise Monitoring Server started task in PROCLIB from the RKANSAMU library. The
CNMLINK library must be APF-authorized.

98 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Securing the OMEGAMON for CICS (3270)
The OMEGAMON for CICS component provides an OMEGAMON for CICS (3270) interface security facility.
This section covers implementing security for OMEGAMON for CICS (3270).
To prevent unauthorized use of commands, the OMEGAMON for CICS (3270) is shipped with the internal
security feature as the default. For an added level of security, however, you can set up an interface
between OMEGAMON for CICS (3270) and an external security package, for example, RACF®, CA-ACF2, or
CA-TOP SECRET.
These are the ways to implement OMEGAMON for CICS (3270) security:
• External security for logon and internal security for commands
• External security for logon and external security for commands
• External security for logon and both internal security and external security for commands (using internal
security with the locking feature)
Note: Passphrase support for the OMEGAMON 3270 Classic interface was introduced with APAR
OA57133 (PTF UA98944). When passphrase support is enabled, OMEGAMON implements the
OMEGAMON 3270 Classic interface external security without the use of security exits. For more
information, see OMEGAMON 3270 Classic interface security and How to: Configure passphrase and MFA
support in the OMEGAMON 3270 Classic interface.
Whether you use internal security, external security, or a combination of the two, you can customize the
OMEGAMON for CICS (3270) security table to the needs of your installation.
This section describes the customization procedure and uses the following terms:
Control Statements
Locate and edit the KCIJPSEC job. The RTE_X_SECURITY_EXIT_LIB parameter in the LPAR
configuration profile is pointing to the location. The default is RKANSAMU. The needed control
statements are found in the KCIJPSEC job. Edit this job and change the defaults for internal security or
to specify external security. For more information about this job, see How to: Use KOBSUPDT security
exits with PARMGEN in the OMEGAMON shared documentation.
Update Program
When you have edited the control statements and pressed F3, you are presented with the JCL that
starts the KOBSUPDT program, which updates the OMEGAMON for CICS (3270) security table.
Exit Routine
At initialization, OMEGAMON for CICS (3270) accesses the user security exit routine, which provides
the interface to the external security package. The name of this routine must be specified by the user.
The following samples are provided:
• KOCARACF and KOCBRACF for RACF
• KOCAACF2 for CA-ACF2
• KOCATOPS for CA-TOPSECRET.
When OMEGAMON for CICS (3270) is initialized, it determines whether an exit routine has been installed
for an external security package.
If the exit routine exists, it gets control for those commands that have been marked for external security
and determines authorization through the external security package.
If external security allows the command, OMEGAMON for CICS (3270) does not check internal security.
If external security is not used for the command, internal security takes effect. The OMEGAMON for CICS
(3270) is shipped with certain authorized commands which require an internal security password for
execution.
Note: In this section, the term authorized means allowed to access; it does not refer to APF authorization.

Chapter 5. Reference 99
 Using internal security for commands
All OMEGAMON for CICS (3270) commands (major, minor, immediate, and INFO-line) have a security
level of 0, 1, 2, or 3. Level 3 provides the highest degree of protection. A setting of 0 means that any user
can run the command.
To activate internal security, you must run the KCIJPSEC JCL job.
Important: Until you run the KCIJPSEC JCL job, OMEGAMON for CICS (3270) commands are protected
only by the default command table security.
All authorized commands are shipped with a default security level of 3, and all others with a level of 0.
You can change the security level of any OMEGAMON for CICS (3270) command to suit the needs of your
installation. “Updating the security table” on page 108 describes how to do this.
Each security level can have its own password. The level 3 password accesses all levels; the level
2 password accesses levels 2 and 1; the level 1 password accesses only the lowest level. Level 0
commands run without a password.
If you enter a command that requires higher authority than yours, OMEGAMON for CICS (3270) responds
with this message:
OB0921 Security check failed (Internal)

To gain access to the authorized commands, use the /PWD command in this way:
1. Type /PWD on the INFO-line. When you press Enter, OMEGAMON for CICS (3270) responds with this
password prompt:

_ <=== Please enter password

2. Type your password on the INFO-line. The password does not display as you type it.
3. Press Enter. If the PASSWORD ACCEPTED message is displayed, press Enter again. You will then have
access to all authorized commands associated with that password, as well as the less command
levels.
If you are using OMEGAMON for CICS (3270) with an external security package, you can prevent the
use of the /PWD command. See “Using the locking feature” on page 100 for more information.
4. Type the /PWD command on the INFO-line and press Enter. The password prompt is displayed.
5. Do not enter a password; just press Enter; you will see the following text:

_________________ Password level reset

Access to authorized commands is restricted until the password is entered again.

Using the locking feature

The locking feature is a form of external security designed to prevent users from changing their internal
security level with the /PWD command. Their level of authority is set once and only at logon; it can be
fixed to one of four levels (level 0, 1, 2, or 3).
Consider the following when using the locking feature:
• Although the locking feature is implemented in the external security exit routine, it is designed to lock
the user's internal security level. Therefore, it affects only those commands marked as EXTERNAL=NO.
• You must define a user security level in CA-ACF2, RACF, or CA-TOP SECRET as an INITIALn resource,
where n is a number from 0–3, and assign corresponding values to commands in the security update
program (using the LEVEL keyword of the COMMAND control statement).
• The locking feature only disables the /PWD command for supplying internal passwords. You can still use
the /PWD command to logon again to a new external user ID.
• Users assigned INITIAL authority (no value of 0 to 3 attached) are allowed to change their internal
security level by using the /PWD command.

100 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

• The locking feature starts checking INITIALn resources at the highest level. If you define INITIAL3 and
INITIAL2, the user is locked to level 3.

RACF routine
To validate a user, the user exit routine checks on the RACF resource class that is defined by the
ICHERCDE macro.
The resources that allow OMEGAMON for CICS (3270) startup include INITIAL, INITIAL0, INITIAL1,
INITIAL2, and INITIAL3, as shown in the following example:

<Allows /PWD to work>

RDEFINE cccccccc INITIAL UACC(READ)

<Defines security level 0 as unaccessible>

RDEFINE cccccccc INITIAL0 UACC(NONE)

<Defines security level 1 as unaccessible>

RDEFINE cccccccc INITIAL1 UACC(NONE)

<Defines security level 2 as unaccessible>

RDEFINE cccccccc INITIAL2 UACC(NONE)

<Defines security level 3 as unaccessible>

RDEFINE cccccccc INITIAL3 UACC(NONE)

<Locks USER02 to level 2 power>

PERMIT INITIAL2 CLASS(classnme) ID(USER02) ACC(READ)

The variable classnme is the resource class name you defined in “Modifying RACF rules” on page 103.

CA-ACF2 routine
The user exit routine checks the CA-ACF2 resource class to validate a user.
The resources that allow OMEGAMON for CICS (3270) startup include INITIAL, INITIAL0, INITIAL1,
INITIAL2, and INITIAL3. To allow users to change their authorization level with the /PWD command, use
INITIAL. Here are sample definitions:

<Allows /PWD to work for USER01>

ACFNRULE KEY(INITIAL) TYPE(cls) ADD(UID(****************USER01) ALLO

<Locks USER02 to security level 0 commands>

ACFNRULE KEY(INITIAL0) TYPE(cls) ADD(UID(****************USER02) ALLO

<Locks USER03 to security level 1 commands>

ACFNRULE KEY(INITIAL1) TYPE(cls) ADD(UID(****************USER03) ALLO

<Locks USER04 to security level 2 commands>

ACFNRULE KEY(INITIAL2) TYPE(cls) ADD(UID(****************USER04) ALLO

<Locks USER05 to security level 3 commands>

ACFNRULE KEY(INITIAL3) TYPE(cls) ADD(UID(****************USER05) ALLO

The variable cls is the generalized resource class name you defined in “Modifying CA-TOP SECRET rules”
on page 105.
The UID operand is installation-specific in format and content. For information about UID, contact your
security administrator.

CA–TOP SECRET routine

Use the INITIAL n resource to define a internal security level if you are using CA–TOP SECRET.

Using external security

OMEGAMON for CICS (3270) supports external security for all modes of operation. For information on the
implementation, see “Using internal security for commands” on page 100.

Chapter 5. Reference 101

 External security is supported for both logon and command use. When using external security, you
can logon to OMEGAMON for CICS (3270) only if they are allowed to access the INITIAL resource
name. A resource name of INITIAL0, INITIAL1, INITIAL2, or INITIAL3 might be used to allow logon to
OMEGAMON for CICS and set the internal security level to 0, 1, 2, or 3, respectively.
When you issue a command, OMEGAMON for CICS (3270) performs an external security check if the
following conditions are met:
• The user exit module name is specified in the security table.
• An external security exit routine is located and loaded.
• External security is specified for the issued command in the security table (using the COMMAND control
statement with the keyword setting EXTERNAL=YES ).
• For VTAM, ISPF, or TSO modes, the library that contains the KOBVTAM load module is APF-authorized.
If any commands are specified for external security checking and an exit routine is not found,
OMEGAMON for CICS (3270) recognizes a possible security exposure and disables those commands
with an internal security level of 0 for the session. Those commands with a level of 1, 2, or 3 are allowed
to run after you enter the internal password, as described in “Using internal security for commands” on
page 100.

Logging on using external security

This section explains special considerations for logging on to OMEGAMON for CICS (3270) using external
security.

VTAM, TSO, or ISPF mode logon panels

When you logon through VTAM, OMEGAMON for CICS (3270) presents a logon panel for the OMEGAMON
VTAM application program, KOBVTAM. The VTAM logon panel also is displayed for ISPF and TSO modes,
because OMEGAMON for CICS (3270) uses the VTAM application program for these modes as well. The
copyright panel you normally see at logon time has additional fields for USERID, PASSWORD, GROUP, and
NEW PASSWORD.
These are the advantages of using the KOBVTAM logon panel:
• The exit routine can cause OMEGAMON for CICS (3270) to stop an unauthorized logon.
• The exit routine makes all security checks based on the user's logon ID and not on the OMEGAMON for
CICS (3270) address space's authority.
If you are in an active VTAM session and you want to alter the external security level of authorization, you
can use the relogon feature discussed in “Accessing security from an active session” on page 102.

Dedicated mode logon

Security in dedicated mode differs from the other modes because, at startup time, there is no user ID or
password associated with the session. Therefore, the only security available by default is internal security.
You must enter the /PWD command, using the re logon feature discussed in the following section in order
to access external security.

Accessing security from an active session

The re logon feature is a function of the /PWD command that enables you to enter your user ID and
password for the external security package from an active OMEGAMON for CICS (3270) session. It is the
facility used in dedicated mode to log on to external security. In VTAM mode, it enables you to alter the
security level without having to bring down a current VTAM session.
Type in the /PWD INFO-line command and your user ID as in this example:

/PWD user01_____OCINIT00;
DED CICSPROD; V300./C SYSA; 05/19/06; 1

102 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Press Enter and type in your external security password at the prompt.
Note these points regarding the re logon feature:
• Do not mark the /PWD command as EXTERNAL=YES in the security table because, in dedicated mode,
you must use /PWD to log on to external security.
• You can determine in your user exit what the default action will be when the user ID or logon password
supplied is not valid. For example, you can specify the disabling of all OMEGAMON for CICS (3270)
commands marked as EXTERNAL=YES, or you can specify that the session reverts to the previous user
ID. The available options are explained in the sample exit routines.
• If you use the re logon feature and your password has expired, you cannot enter a new one using
the /PWD command.

Implementing external security

To implement external security, follow these steps:
1. Modify the rules in the external security package to interface with OMEGAMON for CICS (3270). See
“Modifying RACF rules” on page 103, “Modifying CA-ACF2 rules” on page 104 or “Modifying CA-TOP
SECRET rules” on page 105.
2. Customize the sample exit routine provided in &rhilev.&rte.RKANSAMU according to the procedure
in “Using OMEGAMON for CICS (3270) security exit routines” on page 106. See “Optional external
security features” on page 117 for a description of the options you can use.
3. Modify and update the security table to specify the commands to be verified by RACF, CA-ACF2, or
CA-TOP SECRET and the name of the module that contains the exit routine. (No default setting is
supplied for the module name.) Follow the steps in “Updating the security table” on page 108.

Modifying RACF rules

This section explains the necessary steps for modifying the RACF rules to interface with OMEGAMON for
CICS (3270).
To modify the RACF rules to interface with OMEGAMON for CICS (3270), follow these steps:
1. Update the resource class description table to define a class name (for example, OC;TIVOLI) using the
ICHERCDE macro call. (Use the same name when you define the resource class in the security exit
routine.) Code the ICHERCDE macro in the following manner:

ICHERCDE CLASS=classnme,
ID=nnn,
MAXLNTH=24,
FIRST=ALPHANUM,
OTHER=ANY,
POSIT=nnn,
DFTUACC=NONE

Values for classnme and nnn are determined by your installation. Additional operands for this macro
might also be required at your installation.
2. Activate the newly defined resource class.
3. Define a resource profile for logging on to OMEGAMON for CICS (3270). Use the TSO RDEFINE
command with a resource of INITIAL. Here is an example of a definition that allows all users to sign
onto OMEGAMON for CICS (3270) and use the /PWD command for internal security (that is, it allows
access only to those commands marked EXTERNAL=NO):

RDEFINE classnme INITIAL UACC(READ)

This definition is the minimum required for logon.

4. Define resource profiles for the commands you want to protect using external security
(EXTERNAL=YES commands). If you want to restrict the use of the /PWD command, see “Using the
locking feature” on page 100.

Chapter 5. Reference 103

 a. Use the TSO RDEFINE command and specify the OMEGAMON for CICS (3270) command as
the resource. Be certain to specify that only specific users can run the command by setting
UACC(NONE).
b. Use the PERMIT command to define those users who can access the resource (run the command).
Give them READ access.
The following example shows how to authorize a user to run the PEEK command with RACF:

RDEFINE classnme PEEK UACC(NONE)

PERMIT PEEK CLASS(classnme) ID(USER01) ACCESS(READ)

Note: If the command you want to secure begins with a slash (/) or period (.), the RACF rule you
define must start with a dollar sign ($) instead of the slash (/), or an at sign (@) instead of the period
(.). For example, the command /LOGOUT requires a rule for $LOGOUT.
5. The class name in KOCARACF or KOCBRACF (default is OMCANDLE) is defined on this instruction:

MVC U#CHCLSD,=CL8'OMCANDLE' RESOURCE CLASS NAME

If you change it in the KOCARACF or KOCBRACF module, be sure to also use that name for classnme.
6. Include macro libraries in the assembly of the security exit routine. Use SYS1.MACLIB and
SYS1.AMODGEN as the macro libraries for RACF. In addition, you must include the thilev.TKANMAC
macro library.

TSO/ISPF APF authorization requirements

APF authorization is required for TSO and ISPF modes to initialize with RACF. If this is not done, then a
S282-10 abend code occurs.

Modifying CA-ACF2 rules

To modify the CA-ACF2 rules to interface with OMEGAMON for CICS (3270), follow these steps:
1. If you are running OMEGAMON for CICS (3270) in dedicated or VTAM mode, define the name of the
OMEGAMON for CICS (3270) started task to CA-ACF2.
The started task name you use to run OMEGAMON for CICS (3270) in VTAM mode can have the
MUSASS attribute assigned. This allows CA-ACF2 to verify the individual user authorization rather than
using the OMEGAMON for CICS (3270) address space ID. If STC(NO) is specified, you must run the
OMEGAMON for CICS (3270) in batch with a job name that has the MUSASS attribute.
2. After you install the exit, you must set up a resource class for CA-ACF2 to enable OMEGAMON for CICS
(3270) to make the security checks. Define a generalized resource class name, for example OMS. This
name will be three characters long for generalized resources, but will be prefixed with the letter R
within the security exit. (Use the same name when you define the resource class in the security exit
routine.)
The class name in KOCAACF2 (default is ROMS) is defined on this instruction:

A#ACFCLS DC CL4'ROMS' CHANGE CLASS IF NEEDED

3. Define a CA-ACF2 rule for the INITIAL resource to allow VTAM users to log on to OMEGAMON for CICS
(3270), as in the following example:

ACFNRULE KEY(INITIAL) TYPE(OMS) ADD(UID(****************uid)ALLOW)

The OMS must match the resource class name that you defined. The uid is a user ID or user ID mask. If
you want to restrict the use of the /PWD command, see “Using the locking feature” on page 100.
4. Use the CA-ACF2 rule compiler to define resource rules for the command you want to protect. Specify
the command with the KEY operand.
The following example shows how to authorize a user to run the PEEK command with CA-ACF2. See
your security administrator for information on the format of the string.

104 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 Note: If the command you want to secure begins with a slash (/) or period (.), the CA-ACF2 rule you
define must start with a dollar sign ($) instead of the slash (/), or an "at" sign (@) instead of the period
(.). For example, the command /LOGOUT requires a rule for $LOGOUT.
5. Include the CA-ACF2 macro library in the assembly of the routine. In addition, you must include the
thilev.TKANMAC macro library.

Modifying CA-TOP SECRET rules

The following section explains the procedure for modifying the CA-TOP SECRET rules to interface with
OMEGAMON for CICS (3270).
To modify CA-TOP SECRET rules use these steps:
1. Define the OMEGAMON for CICS (3270) address space as a started task in the CA-TOP SECRET STC
record, along with the related main facility ID:

TSS ADD(STC) PROC(cccccccc) ACID(MAIN FACILITY ACID)

Where cccccccc is the started task name you specified for OMEGAMON for CICS (3270) in PARMGEN.
2. Define the OMEGAMON for CICS (3270) a facility to CA-TOP SECRET in the facility matrix table:

FACILITY(USER3=NAME=cccccccc)
FACILITY(cccccccc=MODE=FAIL,ACTIVE.SHRPRF)
FACILITY(cccccccc=PGM=KOB,NOASUBM,NOABEND,NOXDEF)
FACILITY(cccccccc=ID=3,MULTIUSER,RES,WARNPW,SIGN(M))
FACILITY(cccccccc=NOINSTDATA,NORNDPW,AUTHINIT,NOPROMPT,NOAUDIT)
FACILITY(cccccccc=NOTSOC,NOMRO,LOG(INIT,SMF,MSG,SEC9))

Where cccccccc is the started task name you specified for OMEGAMON for CICS (3270) in PARMGEN.
3. Define the OMEGAMON for CICS (3270) facility:

TSS ADD(ACID) FACILITY(cccccccc)

Where cccccccc is the started task name you specified for OMEGAMON for CICS (3270) in PARMGEN.
4. Define a Resource Descriptor Table entry:

TSS ADD(RDT) RESCLASS(OCCANDLE) RESCODE(XX)

The RESCODE is a hexadecimal value of 01–3F. The class name in KOCATOPS (default is OCCANDLE) is
defined on this instruction:

MVC U#CHCLSD,=CL8'OCCANDLE' ALTERNATE RES/CLASS NAME

If you change it in the KOCATOPS module, be sure to also use that name for RESCLASS.
5. To permit access to the OMEGAMON for CICS (3270) command level, enter the following command:

TSS PERMIT(userid) OCCANDLE (INITIAL0)

TSS PERMIT(userid) OCCANDLE (INITIAL1)
TSS PERMIT(userid) OCCANDLE (INITIAL2)
TSS PERMIT(userid) OCCANDLE (INITIAL3)
TSS PERMIT(userid) OCCANDLE (‘INITIAL ‘)

6. Enter the following to enable CA-TOP SECRET to validate commands:

TSS PERMIT(userid) OCCANDLE(XXXX)

Where xxxx is an OMEGAMON for CICS (3270) command that has been defined with EXTERNAL=YES
in the OMEGAMON for CICS (3270) command table.
If you use CA-TOP SECRET to define an initial access to OMEGAMON for CICS (3270), you can specify
EXTERNAL=NO in the control statements.

Chapter 5. Reference 105

 7. You must also specify the CA-TOP SECRET KOCATOPS interface module to enable the CA-TOP SECRET
interface. Use the TSS PERMIT command to define those users who can access the resource by
running the OMEGAMON command.
The following example shows how to authorize a user to run the PEEK command with CA-TOP SECRET:

TSS PERMIT(userid) OCCANDLE(PEEK)

Note: If the command you want to secure begins with a slash (/) or period (.), the CA-TOP SECRET rule
you define must start with a dollar sign ($) instead of the slash (/), or an at sign (@) instead of the period
(.). For example, the command /LOGOUT requires a rule for $LOGOUT.

Using OMEGAMON for CICS (3270) security exit routines

The exit routine provides an interface between OMEGAMON for CICS (3270) and the security product.
You can specify any unique name for your routine, but that name must also be specified in the control
statements that update the security table. The exit routine can be shared between systems.
The KOCARACF, KOCBRACF, KOCAACF2, and KOCATOPS are members of the &rhilev.&rte.RKANSAMU
data set that contain models of RACF, CA-ACF2, and CA-TOP SECRET routines. Many installations use
these members without modification, but because security procedures are installation-dependent, they
have been documented with comments to enable you to modify them. They are supplied as examples
only.
Verify that the resource class you define in the exit routine has the same name as the resource class
you defined when modifying RACF, CA-ACF2, or CA-TOP SECRET rules. The &rhilev.&rte.RKANSAMU data
set contains members, KOCJACF2, KOCJRACF, and KOCJTOPS, which supply sample JCL to help you
assemble and link-edit your routine.
You can use the same exit routine to define security for multiple OMEGAMON for CICS (3270) images. Use
the same name on the MODULE= statement for each OMEGAMON for CICS (3270). You can use the value
of the B#DDPRFX field in the $BIA data area as part of a resource name to be used for the OMEGAMON
for CICS (3270) currently in use.
Use the KOCBRACF sample to create resource names that include the CICS Jobname.
If you have a security system other than RACF, CA-ACF2, or CA-TOP SECRET, you can still implement a
security interface using these models. Use the sample RACF, CA-ACF2, or CA-TOP SECRET exits as guides
to see what information is passed to the exit routine and what information is returned to OMEGAMON for
CICS (3270).

Using OMEGAMON for CICS (3270) calling conventions

OMEGAMON for CICS (3270) uses the $UCHECK control block to pass information to the exit routine. The
exit routine also uses $UCHECK to pass information back to OMEGAMON for CICS (3270). The $UCHECK
control block is mapped by the $UCHECK macro. The macro is defined in the KOBGMAC member of
thilev.TKANMAC library.
The U#CHPIA field in the $UCHECK control block points to the address of a 16-byte control block. The
KOCPIA macro, defined in the thilev.TKANMAC library, maps this control block and gives you the CICS job
name the user requested at logon. OMEGAMON for CICS (3270) maintains the control block for the entire
life of the session and gives the installation a 512-byte work area for its own use.
Note: The $UCHECK work area is limited to 512 bytes. If your installation requires a larger work area,
GETMAIN the additional storage required and place the pointer to this GETMAIN area in $UCHECK.
An attempt to enlarge this work area beyond its 512-byte limit in any other way causes an overlay of
essential OMEGAMON for CICS (3270) control blocks, and results are unpredictable. If you modify the
RACF RACROUTE macro, you must GETMAIN at least 512 bytes for use as the WORKA work area.
The user exit module is called by OMEGAMON for CICS (3270) using the following conventions:

106 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 21. The naming conventions for the user exit module called by OMEGAMON for CICS (3270)
Name Description
Register 1 Address of parameter list.
Register 13 Address of a standard save area.
Register 14 Return address.
Register 15 Entry point address (in).
Register 15 Return code (out).

The Parameter list contains Word 1 – Address of control block.

Reviewing OMEGAMON for CICS (3270) calling flow

The following procedure describes the flow for calls from OMEGAMON for CICS (3270) to your user
security exit routine at initialization, during command verification, and at termination:
1. At initialization, when OMEGAMON for CICS (3270) passes control to your user exit routine, the
initialization call is indicated by an I in the U#CHTYP field. This indicates that OMEGAMON for CICS
(3270) requires a logon validation.
a. If the user ID field length is non zero, the user ID and password information are available.
b. If additional information or some form of retry is required, the routine can request a reshow of the
screen, and reset any field lengths to indicate that no data is present (user ID, password, group, or
new password).
To perform a reshow in VTAM mode:
• Set a message into the U#CHMSG field (120 bytes maximum length)
• Set the U@CHRSHO bit in U#CHRESP
• Return to the caller.
The message appears under the panel. Appropriate fields are filled in (original user ID and
password), unless overridden (length = 0).
a. When validation is complete, a return code of 0 from the user exit indicates that the user can be
allowed to log on. Any other return code will cause the session to be aborted.
b. Upon successful logon acceptance, the validation routine might perform resource validation and
optionally assign a command security level (0, 1, 2, or 3) to the user. The default setting is 0.
Place the appropriate number into the U#CHAUT4 field. To force the user to use only this level,
also set the U@CH1LOK bit in U#CHAUT1.
2. During command verification, OMEGAMON for CICS places a C in the U#CHTYP field. At this point,
the user authorization is verified. The decision to allow or not allow a command on the first encounter
cannot be changed on subsequent attempts by the same user unless security is reset with the /PWD
command. However, on each attempt, the user exit is notified, an audit record might be written, and a
customized error message might be issued.
These might be the return codes:
RC = 0
Indicates that the command is allowed (RACF and CA-ACF2).
RC = 4
Indicates that the command is unknown to RACF (RACF only). OMEGAMON for CICS (3270)
allows the command to run. See “Modifying RACF rules” on page 103 for instructions to define
a command to RACF.

Chapter 5. Reference 107

 RC = 8
Indicates that the command is known to the security package and access is denied (RACF and
CA-ACF2).
3. At re-logon, OMEGAMON for CICS (3270) places an R in the U#CHTYP field to indicate a logon
validation. The processing is the same as at initialization time, except that users cannot enter a new
password or group because OMEGAMON for CICS (3270) does not display a logon panel.
4. At termination, OMEGAMON for CICS (3270) passes a T to the user's exit routine. You can then do any
termination cleanup required, such as freeing user control blocks and FREEMAINing any GETMAINed
areas.

Modifying the security table

This section describes how to update the security table for both external and internal security and
includes the following topics:
• A review of format rules for control statements
• Detailed explanations of each control statement
• An example of using control statements to update the security table
Security tables are compatible with versions 300 and up. For version 120 and earlier versions, you must
customize your table and rerun the security update utility program.
Table 22 on page 108 is a summary of the available options:

Table 22. Available control statements for updating the security table
Control statement Description
AUTHLIB Specifies an authorized screen space (PROC)
library for initialization that bypasses the security
check.
COMMAND Sets the internal security levels of commands,
marks them for external security, and requests an
audit.
LIST Specifies whether a listing of the current security
settings is to be produced on this run.
MINOR Specifies the security options for minor commands.
MODULE Specifies the name of the module containing the
user's external security exit routine.
PASSWORD Specifies the internal passwords
RESET Clears current settings.
UPDATE Specifies whether OMEGAMON for CICS (3270) is
to perform updating on this run.
SMFNUM Specifies the record number for SMF audit
requests.

Updating the security table

To update the security table, use the Configuration Tool and perform these steps:
1. Access the Modify menu system command security option on the Configure OMEGAMON for CICS
panel.

108 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 To change an existing setting for a parameter, you must specify a new setting rather than just blanking
out the old setting. For example, to remove a command from external security checking, change
EXTERNAL=YES to EXTERNAL=NO.
If you are implementing external security, you must enter the MODULE command statement naming
the load module that will contain the exit routine. You must also indicate which commands are to use
external security with the EXTERNAL=YES setting on the COMMAND control statement.
To remove control from external security, blank out the value of the MODULE= keyword. Remember,
that if you do not change commands marked EXTERNAL=YES to EXTERNAL=NO, those with an internal
security level of 0 are non executable.
2. Submit the job to run KOBSUPDT, the security update utility program.
KOBSUPDT performs the updates to the security table, and generates a list of the edits and, if
requested, a complete list of security information. Successful completion of the job produces this
message:
OB9147 LOAD MODULE TEXT SUCCESSFULLY UPDATED

If the update program flags statements as being in error during an update run, correct the statements
and submit them again.
3. To update the security table, perform either one of the following steps:
a. Recycle the address space for the OMEGAMON for CICS (3270).
b. To update the security table without recycling OMEGAMON for CICS (3270), end the current
session and begin a new one.
Changes made to the security table are effective only after the security update job completes
successfully and a new OMEGAMON for CICS (3270) user session is started. Because the security
table is part of a reentrant load module, all OMEGAMON for CICS (3270) user sessions in an address
space must be stopped before security tables are effective. For example, if five VTAM mode sessions
are active, all of them must stop before new sessions can use the updated security tables.
You must ensure that any changes introduced to a runtime environment's command security table
through the Configuration Tool's KC2XSECU member in INSTDATA are synchronized with any command
security table changes for the same runtime environment done through PARMGEN using the KOCSUPDI
member in the RKANSAMU library, or with the sample job KC2JSEC in the TKANSAM library. See
“Configuring the OMEGAMON for CICS (3270) component” on page 28 for an explanation of the
KOCSUPDI sample security table member in the TKANSAM library.

Reviewing format rules for control statements

These general format rules apply to all control statements:
• Control statements can begin anywhere in the input record, but cannot extend beyond column 72.
• Statements can be in any order in the input stream. The update program processes the statements as
it encounters them, with the exception of the LIST and UPDATE statements, which take effect after all
other input is processed.
• All information for a particular control statement must fit in a single line.
• All input must be in uppercase letters.
• Statements must be in this format:

CONTROLSTATEMENT=CCCCCCCC,KEYWORD1=CCCCCCCC,KEYWORD2=CCCCCCCC

There can be no intervening blanks. The update program treats data that follows a blank as a comment.
The data prints on the edit listing, but is ignored for processing purposes.
• To insert comment lines anywhere in the input stream, place an asterisk (*) in column 1 of the input
record.

Chapter 5. Reference 109

 • If the update program flags statements as being in error, correct the statements and submit them
again. To change a setting, you must specify a new setting rather than blank out the old setting. This is
especially important to remember when changing a command from EXTERNAL=YES to EXTERNAL=NO.
• OMEGAMON for CICS (3270) does not recognize changes to control statements until the update job
successfully ends and a new OMEGAMON for CICS (3270) user session is started. The control statement
edit listing can indicate successful completion of the update.

Using control statements to modify the security table

Control statements and their keywords are shown in the following list. Keyword defaults are shown in bold
face type.

AUTHLIB
This control statement specifies the data set name of an authorized screen space library that contains
commands to invoke at OMEGAMON for CICS (3270) address space initialization, bypassing any security
checks. This option lets you run protected commands as part of the initialization screen without entering a
password.
Because all security checking for screens coming from the AUTHLIB data set is bypassed, WRITE access
to this data set might be restricted.
Security checking resumes when any of the following occurs:
• OMEGAMON for CICS (3270) retrieves a screen from an unauthorized library
• OMEGAMON for CICS (3270) retrieves a screen that has been loaded into memory
• You enter any keystroke, including a cursor movement
If you create an authorized screen library and use the OMEGAMON for CICS (3270), security checking
causes initialization to fail when the following items occur:
• OMEGAMON for CICS (3270) pulls a screen containing an authorized command. If you use the
OMEGAMON for CICS (3270), you must leave the .FGO and .VAR commands unprotected.
• OMEGAMON for CICS (3270) pulls a screen space that has been loaded into memory. @ZSCRNDF is the
screen that loads screen spaces into memory.
This is the format of the AUTHLIB control statement:

AUTHLIB=dsname,VOL={volume|NOVOLUME}

Where dsname is the name of the authorized screen library you have created.
AUTHLIB accepts the following keyword:
VOL
Specifies the volume serial where the specified data set is located. This acts as an additional security
measure. You must specify a volume serial number even if the data set is cataloged. The AUTHLIB
statement always requires the VOL keyword. If you do not want the additional volume serial number
checking to be performed, specify NOVOLUME.
Concatenate the data set containing the authorized screens in your RKOCPROC DD statement.
Do not APF-authorize the data set that contains the authorized screens.

COMMAND
This control statement specifies the name of an OMEGAMON for CICS (3270) major, immediate, or
INFO-line command to be protected. Minor commands are protected at the major command level unless
the MINOR control statement is specified.

110 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

When you update an INFO-line command, you must use the actual command name and not its alias.
OMEGAMON for CICS (3270) automatically assigns the same protection attributes to all aliases of the
command.
OMEGAMON for CICS (3270) does not check for multiple COMMAND statements for the same command
in the same run. The last COMMAND statement for the command is the one that OMEGAMON for CICS
(3270) processes.
This is the format of the COMMAND control statement:

COMMAND=
{cccc|.ccc|/cccccc}
[,LEVEL={0|2|3|DISABLE}]
[,EXTERNAL={YES|NO}]
[,AUDIT={ ...}]
WTO
SMF
BOTH
NONE

Where cccc, .ccc, or /cccccc is the name of the OMEGAMON for CICS (3270) command to be protected.
To have the control statement edit listing show the current security settings for a command, enter a
COMMAND=cccc, =.ccc, or =/cccccc statement with no additional operands
COMMAND accepts the following keywords:
LEVEL
Specifies the internal security level to be associated with this command.
Level 0 allows the command to run without an internal security check
Levels 1, 2, and 3 specify that the command runs only if you have previously entered the
corresponding password for that level (or for a higher level) through the /PWD INFO-line command.
DISABLE specifies that OMEGAMON for CICS (3270) is never to run the command.
You can audit attempts to run the command for the session, but you cannot specify internal or
external security.
EXTERNAL
Specifies whether an external security package checks this command. If you specify
LEVEL=DISABLE, OMEGAMON for CICS (3270) ignores the EXTERNAL keyword. If you code
EXTERNAL=YES for a command and no exit routine is available, OMEGAMON for CICS (3270) stops
the command for the session if it has an associated security level of 0, or defaults to internal security
if the command has a security level of 1, 2, or 3. After you specify EXTERNAL=YES, you can change it
only if you specify EXTERNAL=NO and rerun the security update program.
AUDIT
Specifies whether OMEGAMON for CICS (3270) is to audit the command each time a user starts it.
These are the possible values:
WTO
Produces a one-line message on the main console.
SMF
Specifies that OMEGAMON for CICS (3270) write an SMF record. The SMF record number must be
specified in the SMFNUM control statement. If the SMF audit cannot be performed, OMEGAMON
for CICS (3270) defaults to a WTO audit. This option requires APF authorization.
BOTH
Specifies that OMEGAMON for CICS (3270) issue a WTO message to a console and write an SMF
record.
NONE
Specifies no auditing. This is the default setting. If you specify an audit for a disabled command,
you are notified of attempts to run it.

Chapter 5. Reference 111

 LIST
This control statement specifies whether the update program produces a security file listing. A security
file listing is a complete record of the security table that shows the name of the authorized screen library,
its volume serial number, the name of the user exit module, and all command names along with their
corresponding security information.
It does not list the internal security passwords. If you also specify UPDATE=NO, the listing shows what the
control statements and security information can look like if the update had taken place.
To generate the security file listing independent of edits to the control statements, you can submit
LIST=YES as the only control statement in the input stream.
Only one LIST statement is allowed per run. The default setting is LIST=NO.
This is the format of the LIST control statement:

LIST={YES|NO}

MINOR
This control statement specifies the name of an OMEGAMON for CICS (3270) minor command to protect.
OMEGAMON for CICS (3270) protects the minor commands independent of the majors. Therefore, any
changes to minor commands apply to all minors with the same name and attributes, regardless of their
major commands.
Access to a minor command requires access to the appropriate major command. If you do not specify an
EXTERNAL keyword, the associated major controls access to this minor command.
No verification is made for multiple MINOR statements for the same minor command in the same run. The
last MINOR statement for the minor takes effect.
This is the format of the MINOR control statement:

MINOR=cccc
[,LEVEL={1|2|3|DISABLE}]
[,EXTERNAL={YES|NO}]
[,AUDIT={WTO|SMF|BOTH|NONE}]

Where cccc is the name of the minor command to be protected.

Refer to the COMMAND control statement for explanations of the keywords.

MODULE
This control statement specifies the name of the module that contains your external security exit routine.
You must specify this parameter for an external security check to take place. There is no default setting.
This is the format of the MODULE control statement:

MODULE=cccccccc

Where cccccccc is the name of the module that contains your external security exit routine. Verify that this
name matches the load module name you specified in the KOCJACF2, KOCJRACF, or KOCJTOPS members
of the &rhilev.&rte.TKANSAM library.
To remove control from external security, blank out the value of MODULE=, run the security update job,
and restart the OMEGAMON for CICS (3270) address space.

PASSWORD
This control statement specifies the 1–8 character password for each internal security level, to be
used with the /PWD command. Use a separate PASSWORD control statement for each security level.
Use unique passwords for each security level. When you enter a valid password for one security level,

112 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

OMEGAMON for CICS (3270) allows access to commands secured at that level, and commands secured at
levels less than that.
OMEGAMON for CICS (3270) checks the password for a match in this order:
• Level 1
• Level 2
• Level 3
If you assign the same password to more than one level, OMEGAMON for CICS (3270) matches it only at
the lowest level, and denies access to commands protected at higher levels.
This is the format of the PASSWORD control statement:

PASSWORD=password,LEVEL={1|2|3}

Where password is the unique password for this level.

The PASSWORD control statement accepts the following keyword:
LEVEL
Specifies the security level associated with this password. Levels 1, 2, and 3 specify that the
command runs only if you have previously entered the corresponding password for that level (or
for a higher level) through the /PWD INFO-line command. A LEVEL statement is always required for a
password.

RESET
This control statement clears the current settings of the other control statements. Reset commands
remain unprotected unless you specify new settings with the appropriate control statements and rerun
the update program.
Only one RESET statement is allowed per run.
This is the format of the RESET control statement:

RESET=cccccccc

Where cccccccc is one of the following arguments:

ALL
Clears settings for all control statements and all keywords in the OMEGAMON for CICS (3270) security
table.
AUTHLIB
Clears the name and volume serial number of the authorized screen library.
INFO
Clears settings for all INFO-line commands (on the COMMAND control statement). For example, if you
do not want to use the default security levels for INFO-line commands and want to start over, enter
RESET=INFO. For INFO-line commands, this resets all LEVEL settings to security level 0 and also
clears any existing EXTERNAL and AUDIT settings.
MAJOR
Clears settings for all major and immediate commands (on the COMMAND control statement). See
INFO for an example.
MINOR
Clears settings for all minor commands.
MODULE
Clears the name of the user exit routine module.
PASSWORD
Clears the internal passwords.

Chapter 5. Reference 113

 SLASH
Same as INFO.
SMFNUM
Clears the record number for SMF audits.
YES
Same as ALL.

SMFNUM
This control statement indicates the ID number of the SMF record that OMEGAMON for CICS (3270) can
use for its audit.
This is the format of the SMFNUM control statement:

SMFNUM=nnn

Where nnn is the SMF record ID number. This ID number assigned to OMEGAMON for CICS (3270) audit
must be from 128 through 255, and must be different from that used by any other application. There is no
default setting.

UPDATE
This control statement indicates the ID number of the SMF record that OMEGAMON for CICS (3270) can
use for its audit.
This is the format of the SMFNUM control statement:

SMFNUM=nnn

This control statement specifies whether OMEGAMON for CICS (3270) updates the control statements
during this run. The UPDATE=NO statement specifies that this run of the security update program might
be a trial run.
Only one UPDATE statement is allowed per run. The default setting is UPDATE=YES.
This is the format of the UPDATE control statement:

UPDATE={YES|NO}

Using control statements to update the security table

This section provides a list of control statements you can use to update the security table and a detailed
explanation of how each control statement causes particular checks to happen.
The following figure shows an example of using control statements to update the security table:

*
*
* Update: USER01: SYSTEMS GROUP
*
COMMAND=PEEK,LEVEL=1
COMMAND=.DSA,LEVEL=3,EXTERNAL=YES,AUDIT=WTO
COMMAND=MLST,EXTERNAL=YES
COMMAND=XMZP,LEVEL=DISABLE,AUDIT=BOTH
COMMAND=XMLS,LEVEL=2
MINOR=JOBS,LEVEL=2
COMMAND=/SAVE,LEVEL=1,AUDIT=NONE
MODULE=MYSECURE
SMFNUM=233
LIST=YES
UPDATE=NO

114 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Explaining control statement settings
The command control statements in the previous figure result in the following settings for the
OMEGAMON for CICS (3270) commands:

Table 23. Explaining control statement settings

Control statement Result
PEEK A user who has specified the internal security level
1 or higher password can run the PEEK command
and its minors. OMEGAMON for CICS (3270) does
not perform external security checking.
.DSA OMEGAMON for CICS (3270) performs external
security checking and writes a message on the
main console each time .DSA is invoked. If external
security is unavailable, only a user who specified
the internal security level 3 password can run .DSA.
MLIST OMEGAMON for CICS (3270) performs external
security checking, but no auditing.
XMZP The command cannot be run. OMEGAMON for CICS
(3270) writes a message on the main console and
writes an SMF record when XMZP is issued. There
is no external security checking.
XMLS A user who has specified either the level 2 or level
3 internal security password can run XMLS.
JOBS JOBS is a minor of the PEEK command is a level
1 authorized command; however, the LEVEL=2
setting on JOBS specifies that only level 2 or 3
users can access it.
/SAVE A user who has specified either the level 1, level 2,
or level 3 password can run the /SAVE command;
it is not audited.
MODULE The name of the module that contains the security
exit routine.
SMFNUM The SMF ID is set as 233.
LIST YES indicates that OMEGAMON for CICS (3270)
produces a listing.
UPDATE NO indicates that OMEGAMON for CICS (3270)
does not update the security table. This is a trial
run.

Security update program listing

The security update program produces a listing of the control statement modifications. If you specify the
LIST=YES control statement, an additional report is produced that includes all security information.
The security update program listing consists of these parts:
• Header
• Control statement edit listing
• Security file listing
• Security update program trace

Chapter 5. Reference 115

 The Header part contains the following information:
• Data set name where the load module resides
• Module name of the security table (OICMDccc)
• OMEGAMON for CICS (3270) version number (nnn) in the format VnnnCOM
• Messages indicating successful completion of the job or error conditions, for example, a failure to open
the SYSLIB data set or read the security table
The Control statement edit listing part contains the update report, which has a listing of the control
statements that have been edited. The listing shows the previous contents (except for previous
passwords), as well as the new contents. If you specified UPDATE=YES, OMEGAMON for CICS (3270)
reports the date and time of the previous update.
This is a typical control statement listing:

OBSECUP 1.2-- SECURITY UPDATE PROGRAM----

*** CONTROL STATEMENT

EDIT ***

AUTHLIB=rhilev.RKOCPROC,VOL=NOVOLUME
PREVIOUS CONTENTS =
NEW CONTENTS = rhilev.RKOCPROC
NOVOLUME

* CHANGE THE PASSWORD FOR LEVEL 3 COMMAND ACCESS

PASSWORD=TIVOLI3,LEVEL=3
PREVIOUS CONTENTS = ********
NEW CONTENTS = TIVOLI3

* DISPLAY SECURITY INFORMATION FOR THE PEEK COMMAND

COMMAND=PEEK
PREVIOUS CONTENTS = 3 B NEW CONTENTS = 3
B

* DISPLAY SECURITY INFORMATION FOR MINOR JOBS

MINOR=JOBS
PREVIOUS CONTENTS = 0EW NEW CONTENTS = 0EW

* PROTECT MZAP COMMAND

The codes for the PREVIOUS CONTENTS and NEW CONTENTS of commands are positional. There are
three positions:
1. The first position shows the number of the internal security level or an asterisk (*) if the command has
been DISABLED.
2. The second position shows the external security option:
E
Use external security for this command.
b
Blank specifies no external security.
3. The third position shows the auditing option:
W
Audit this command through WTO.
S
Audit this command through SMF
B
Audit this command through WTO and SMF
b
Blank specifies no auditing
If you specify the LIST=YES statement anywhere in the input stream, the Security file listing generates
a complete listing of the security information, including the name of the authorized screen library and its

116 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 volume serial number, the name of the external security user exit module, the SMF record number, and
all of the commands along with their security information. The listing does not show the internal security
passwords.
TYPE specifies the following types of OMEGAMON for CICS (3270) commands:

Table 24. TYPE specifies these commands

Command type Description
C Major
I Immediate
S Slash (info line)

The security level follows the command. An asterisk (*) indicates that a command has been disabled.
Minor commands are listed underneath their corresponding majors.
The Security update program trace part indicates whether an update has successfully completed.
The following example shows a typical trace:

OBSECUP
1.2-- SECURITY UPDATE PROGRAM--

OB9145 OBSELW00 CALLED TO WRITE cccccccc.

OB9148 SYSLIB DCB CLOSED SUCCESSFULLY
OB9147 LOAD MODULE TEXT SUCCESSFULLY UPDATED
OB9150 SYSLIB DCB CLOSED
OB9269 OBSECUP ENDED

Optional external security features

This section explains the options you have for implementing external security packages, for example,
RACF or ACF2.
It contains the following items:
• Customization of error messages
• Password updating
• Audit suppression
• Supplement command tracking
You can set up your user exit routine to use any of the options we discuss in this section. Remember
that you can also use the control options that the security package supplies, such as SHIFT validation
and SOURCE validation. Mark the commands, EXTERNAL=YES, and implement the option as the security
package directs.

Customizing error messages

To suit your individual requirements, your site can create custom error messages to display when a user
has insufficient authority, or enters an invalid user ID or password.
Restrictions: The user security message can be up to 120 bytes long, except for INFO-line messages (for
example, /PWD re-logon messages), which can be a maximum of 60 bytes.

Giving password update capability

You can give the user the capability of interactive communication when logging on to external security.
Example: For example, if a user logs on with an expired password, the security exit might prompt the user
for a new password and update the security database.
Restrictions: Password update capability is not available when logging back on with the /PWD command.

Chapter 5. Reference 117

 Suppressing auditing
OMEGAMON for CICS (3270) gives you the flexibility of suppressing WTO or SMF auditing.
Example: At initialization or re-logon, your exit routine might set a flag in the $UCHECK control block to
indicate WTO or SMF suppression.
Restrictions: There are no restrictions.

Supplement command tracking

In addition to the WTO and SMF audits available with OMEGAMON for CICS (3270), you can use the audit
features of the external security package to supplement command tracking.
Examples: The RACF Report Writer and ACF2 ACFRPT utility programs are examples of this supplemental
audit capability.
Restrictions: There are no restrictions.

Customizing profiles and security

The OMEGAMON for CICS (3270) profiles control the characteristics of an active OMEGAMON for CICS
(3270) user session. Both the installer and the general user community can create and save these
customized profiles. This section describes the types of profiles, how to create them, and how to use
profile security.

Types of profiles and suffixes

These are the types of OMEGAMON for CICS (3270) interface profiles:
• The IBM Tivoli-supplied profile contains session configuration defaults and default exception analysis
thresholds. It enables you to easily install the OMEGAMON for CICS component without customization
and assures you can always initialize the OMEGAMON for CICS (3270) user session, even if no other
profiles are defined.
• The installation-defined profile enables you, the customizer, to define default settings that are different
from the IBM Tivoli-supplied profile settings. This customized profile becomes the default for all
OMEGAMON for CICS (3270) user sessions at your installation. It takes precedence over the IBM
Tivoli-supplied profile.
• The user-defined profile allows individual OMEGAMON for CICS (3270) users to create one or more
profiles to customize their individual OMEGAMON for CICS (3270) user sessions. It takes precedence
over the installation and IBM Tivoli supplied profiles.
Each profile has a unique two character suffix. These are the suffixes for the three types of menu system
interface profiles:
• /C - IBM Tivoli-supplied profile.
• /I - Installation-defined profile.
• cc - User-defined profiles—any two alphanumeric characters.
The profile suffices are used in the following locations:
• On the INFO-line display. The current session's profile suffix appears on the INFO-line next to the
product version number:

______________ ZMENU
VTM LOG OC V510./I SYSA; 05/10/06; 0:3 2:22 5 AB

• On the USER= parameter in your OMEGAMON for CICS (3270) startup JCL or CLIST. For example, if you
want to start a session with the user profile cc, enter USER=cc.
• On the USER=cc option on the ISPF Invocation Menu.

118 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

• The user profile-defined suffix (cc) is specified in the Save/Delete option on the Profile menu in the
OMEGAMON for CICS (3270), which saves and deletes user-defined profiles.

Profile search order

When OMEGAMON for CICS (3270) is initialized, it always loads the IBM Tivoli supplied profile, as well
as the installation-defined profiles and user-defined profiles, if they exist. To see which profile to use,
OMEGAMON for CICS (3270) verifies the value on the USER start parameter.
If a user-defined profile (cc) is specified, and OMEGAMON for CICS (3270) is not able to find the user
member, it searches for the /I profile.
If no installation-defined profile is found, it defaults to /C.
If no user-defined profile is specified, OMEGAMON for CICS (3270) uses the installation-defined profile
(/I). If no installation-defined profile is found, the profile defaults to /C, the IBM Tivoli supplied profile.
If /C is specified, OMEGAMON for CICS (3270) uses the IBM Tivoli supplied profile.

Profile storage
The IBM Tivoli supplied profile is stored in the load library and cannot be changed. Therefore, the IBM
Tivoli supplied values are always available as shipped.
OMEGAMON for CICS (3270) stores the installation-defined and user-defined profiles in your site's profile
data set (rhilev.RKC2PFnn), which is referenced by ddname RKOCPFSV.
The installation-defined profile is stored as member OCINSTAL in rhilev.RKC2PFnn. The user defined
profiles are stored as member names in the form OCUSERcc, where cc is the user-defined profile suffix.

Creating an installation defined profile

You can change some or all of the IBM Tivoli supplied profile defaults to customize OMEGAMON for
CICS (3270) for your installation. Customization includes determining, selecting, and saving appropriate
options and thresholds to create an installation-defined profile. It also includes specifying this profile as
the default for your installation.
The Profile Options and Maintenance menu guides you through the customization process. This menu is
available by selecting Profile from the Main Menu of the OMEGAMON for CICS (3270) interface.
You can use some or all of the following profile options to select the defaults for the installation session
and exception analysis options:
• To set global performance options, choose Configure from the Profile Options and Maintenance menu,
and then select OMEGAMON II Performance.
• To set display options, select Configure or Color.
• To control session logging or automatic update mode, select the appropriate session control option
(Background, Auto On or Off, or Logging).
• To set or display exception analysis thresholds, select Exceptions.

Saving an installation defined profile

You can change the setting of any installation defined profile option at any time during the OMEGAMON
for CICS (3270) user session. OMEGAMON for CICS (3270) uses the changed setting for the duration of
the current session. The only exception is the Page fix option. A change to this option does not take place
until the next OMEGAMON for CICS (3270) user session.
If you want to use the changed profile after your OMEGAMON for CICS (3270) user session ends, you
must save the profile by selecting the Save/Delete option of the Profile Options and Maintenance menu.

Chapter 5. Reference 119

 The saved profile picks up not only the settings you changed, but all of the current settings for all profile
options on the Profile Options and Maintenance menu. Verify that you have changed only those settings
you want to keep in the new profile before saving the profile.
To specify this new profile as the default for your installation, enter USER=/I in your OMEGAMON for CICS
(3270) startup JCL or CLIST.
If you want to change or delete a profile, select the Save/Delete option on the Profile Options menu also.

Creating a user-defined profile

Individual users might want to create their own profiles to use when they are monitoring CICS with the
OMEGAMON for CICS (3270). For information on creating user-defined profiles, see the IBM OMEGAMON
for CICS on z/OS: OMEGAMON for CICS User's Guide and Reference.

Profile Security
OMEGAMON for CICS (3270) is shipped with the IPRF and IOPT commands unsecured, so that you can
easily install and modify the installation-defined profile. These commands control installation-defined
profiles. After you create an installation-defined profile, you might want to protect it from inadvertent
damage or modification by the general user community. Because each user can create a unique user-
defined profile to override the installation-defined profiles and IBM Tivoli-supplied profiles, he or she has
no need to access the installation-defined profile.
To protect the installation-defined profile, you can use either OMEGAMON for CICS (3270) default internal
security or OMEGAMON for CICS (3270) external security packages, such as RACF or CA-ACF2. The
internal security of this product requires a password for authorization to issue a command. An external
security package checks authorization through the user ID and logon password.

The System Management Facilities audit

This section explains how to generate the System Management Facilities (SMF) audit.
When you generate the SMF audit, verify that both of the following actions occur:
• SMF record exits (IEFU83 and IEFU84) do not suppress the ability of OMEGAMON for CICS (3270) to log
the audit activity records.
• The SMF system parameters specifications (SMFPRMcc) do not suppress the ability of OMEGAMON for
CICS (3270) to log the audit activity records.
Note: The SMF audit has a high overhead, so you should use the audit only with sensitive commands,
such as those that could disrupt the system (for example, OCMD and MZAP).

Understanding the System Management Facilities and audit records

The SMF record contains the following items:
• IBM header (IFASMFR maps)
• Common Header ($CANHDR maps)
You define these maps in the KOBGMAC member of the thilev.TKANMAC library.
• Security audit record ($AUDIT maps)
You define these maps in the KOBGMAC member of thilev.TKANMAC library.
The audit record contains the following items:
• The date/time/system stamp
• The User ID/jobname associated with the session
• The actual command text as you entered it on the OMEGAMON for CICS (3270) panel
Records of minor commands also reference their associated major commands.

120 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 Generating the System Management Facilities report
To generate the SMF report, follow these steps:
1. Copy thilev.TKANSAM(KOCASRPT) to rhilev.RKANSAMU(KOCASRPT). Modify the
rhilev.RKANSAMU(KOCASRPT) member as necessary to meet your environmental requirements.
2. Assemble and link rhilev.RKANSAMU(KOCASRPT).
3. Using IFASMFDP, extract SMF records matching the SMFNUM specified in the Command security table.
4. Use the program linked in step 2 to process the SMF data extracted in step 3.

Configuring historical data tables

This section discusses historical data and includes information that you can use to determine the disk
space required to support historical data files.
The installation documentation for your OMEGAMON XE products describes the basic disk space
requirements for the Tivoli Enterprise Monitoring Server and the Tivoli Enterprise Portal. These basic
disk space requirements do not include additional space that is required for maintaining historical data
files. Because of the variations in client distributed systems, system size, number of managed systems,
and so on, it is difficult to provide actual additional disk space requirements necessary for historical data
collection. This section provides the system administrator with basic record sizes for the tables available
for historical data collection in the OMEGAMON enhanced 3270 user interface and it also provides sample
space estimates.

Historical data collection

Historical data collection involves the periodic sampling of selected attribute groups to support
investigation of past problems and performance analysis. This is an optional feature that is enabled
through the Tivoli Enterprise Portal or the OMEGAMON enhanced 3270 user interface.
The following historical data collection facilities are available for all OMEGAMON XE agents:
• Short-term or near-term history: recently sampled data stored in the persistent data store at the
monitoring agent on z/OS
• Long-term or warehoused history: an optional feature that stores older data in the Tivoli Data
Warehouse on a Windows, Linux, or UNIX system. The Summarization and Pruning agent can be used to
manage this data
There is also an historical data collection (Task History Data) that is available for the OMEGAMON for CICS
agent only. The data for the Task History Data collection is stored separately. See “Configuring task history
data” on page 126 for more information about storing task history data.
The persistent data store (PDS) is a set of physically sequential files used for storing and retrieving near-
term historical data. When the active PDS file becomes full, persistent data store processing switches to
the next empty file and checks to see if any empty PDS files remain. If there are no more empty files,
processing empties the file that contains the oldest data. You can configure the number of PDS files used
and the amount of storage allocated to them if the default settings are not sufficient for your environment.
Sample estimates are provided in “Determining PDS sizes for near-term history collection” on page 122.
Near-term historical data is written to the PDS files by the monitoring agent using its CPU cycles.
Additional CPU cycles are used when the Warehouse Proxy extracts data from near-term history and
transfers it to the Tivoli Data Warehouse. If you have collected a large amount of data in near-term history,
the extraction process will significantly increase the monitoring agent's CPU usage. Deciding how often
to migrate data to the Data Warehouse and when to schedule it is dependent on the amount of data
collected and how much space has been allocated to the PDS for storing near-term history. Data that is
not warehoused by the time the persistent data store becomes full will be discarded.
Information to help you understand the persistent data store and help you decide whether you want to
collect historical data is provided in Decision 8: Whether to collect historical data and how to manage it
which is in the Planning section of OMEGAMON shared documentation Version 6.3.0 Fix Pack 2. Additional

Chapter 5. Reference 121

 information about the persistent data store is available in Maintaining the persistent data store located in
the Reference section of OMEGAMON shared documentation Version 6.3.0 Fix Pack 2.

Enabling historical data collection in the enhanced 3270UI

The OMEGAMON enhanced 3270 user interface (enhanced 3270UI) is designed for investigation of
current problems or those that have occurred in the recent past. Therefore, only near-term historical data
can be displayed in the enhanced 3270UI workspaces.
In addition, only a subset of OMEGAMON for CICS on z/OS and OMEGAMON for CICS TG on z/OS attribute
groups are available to configure for historical data collection in the enhanced 3270UI. Historical data
configuration is limited to the subset of groups that can typically be used for problem solving.
Attribute groups that you enable historical collection for using the enhanced 3270UI are also available for
viewing and configuration in the Tivoli Enterprise Portal.
Refer to Decision 8: Whether to collect historical data and how to manage it which is in the Planning
section of OMEGAMON shared documentation Version 6.3.0 Fix Pack 2 for more information about
collecting historical data. Refer to Near-term History in OMEGAMON shared documentation Version 6.3.0
Fix Pack 2: OMEGAMON Enhanced 3270 user interface for more information about viewing and configuring
near-term history in the enhanced 3270UI.

Enabling historical data collection in the Tivoli Enterprise Portal

The Tivoli Enterprise Portal can display historical data stored in the persistent data store and the Tivoli
Data Warehouse. In addition, all attribute groups eligible for periodic sampling can be configured for
historical collection within the Tivoli Enterprise Portal.
An attribute group that you enable historical collection for using the Tivoli Enterprise Portal is available
for viewing and configuration using the OMEGAMON enhanced 3270 user interface (enhanced 3270UI) if
that attribute group is part of the subset of groups available for viewing near-term history in the enhanced
3270UI.
Refer to Decision 8: Whether to collect historical data and how to manage it which is in the Planning
section of OMEGAMON shared documentation Version 6.3.0 Fix Pack 2 for more information about
collecting historical data. Refer to IBM Tivoli Monitoring: Tivoli Enterprise Portal User's Guide for
information about creating historical collections in the Tivoli Enterprise Portal.

Determining PDS sizes for near-term history collection

If the settings for the persistent datastore (PDS) are not sufficient for your environment, you can change
them using PARMGEN. You can adjust the number of files in the PDS and also adjust the amount of
storage allocated to the PDS.
Use the runtime environment parameter RTE_PDS_FILE_COUNT, described in "Common parameters"
in OMEGAMON shared documentation Version 6.3.0 Fix Pack 2: Reference, to set the number of files
in the PDS. Changing this value affects all monitoring agents within the runtime environment. Refer
to OMEGAMON shared documentation Version 6.3.0 Fix Pack 2: Configuring for more information about
configuring your environment.
Use the KC5_PD_CYL parameter to update the PDS storage allocation for OMEGAMON for CICS on z/OS.
Use the KGW_PD_CYL parameter to update the PDS storage allocation for OMEGAMON for CICS TG on
z/OS.
The amount of storage that is required is unique to each environment. The following list shows an
example of factors that may influence how much storage your PDS requires:
• Which attribute groups collect near-term history
• The frequency of collection
• How many days of near-term history you want to store
• The number of monitored CICS regions

122 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

• Transaction activity within each monitored region
At any given time, at least one file in the set of PDS files will be empty to ensure that there is at least one
empty file that can be switched to when the active PDS file becomes full. For estimation purposes, also
assume that, on average, the active PDS file will be approximately 50% full. As a result, on average, 1.5
PDS files contain no data.
To offset this effect, you need sufficient space in the remaining PDS files to support storing all near-term
historical data that you want to collect. Therefore, the Kpp_PD_CYL parameter should be over-specified
in order to ensure that there is an adequate amount of space in the PDS to accommodate the total DASD
space requirement for your near-term history.
To determine an appropriate Kpp_PD_CYL value for your environment, calculate the cylinder space
needed for each available PDS file by dividing the number of available PDS files into the total number of
cylinders required to hold all of the historical data that you want to collect, for example, three days of
near-term history. Then multiply this value by the number of files in the PDS to obtain the Kpp_PD_CYL
value. The calculation is represented in this formula:

((Daily Space CYL x Number of Days to Store) / Number of Available PDS Files) x Number of PDS
Files

where Number of Available PDS Files = Number of PDS Files - 1.5.

Sample estimates are shown in the following information.

Sample PDS estimates for OMEGAMON for CICS on z/OS

This information provides sample estimates for the DASD space required to collect near-term history for
OMEGAMON for CICS on z/OS. Factors in your environment will affect how much space you require.
Table 25 on page 123 shows a sample estimate for the total persistent data store (PDS) disk space
required to support three days of history data, collected at 5 minute intervals for various numbers of
monitored CICS regions. A sample value for KC5_PD_CYL is derived based on the estimates, assuming the
following:
• Six PDS files are allocated.
• The PDS files must be able to contain three days of near-term history.
• The collection interval is every 5 minutes, which is 288 collections each day.
• Near-term history is collected for the attribute groups listed in Table 26 on page 124 and assume the
specifications in that table.
• One cylinder of DASD space can hold approximately 830KB of data.
The Daily Space amounts listed in Table 26 on page 124 are totaled and used to calculate the sample
space estimates in Table 25 on page 123. Numbers were rounded up.

Table 25. Total DASD Space estimates for a varied number of CICS regions
Number of Daily space Total space Total DASD Space per KC5_PD_CYL
monitored (KB) (KB) for 3 days space (CYL) available PDS value for 6 PDS
CICS regions file files
1 16660 49980 61 13.6 82
10 166600 499800 603 134.0 804
20 333200 999600 1205 267.8 1607
50 833000 2499000 3011 669.2 4016

The estimated number of rows and agent row size are dependent on the attribute groups that have been
chosen to be collected and, depending on the attribute group, how much workload has been performed
during the collection interval. Table 26 on page 124 shows the attribute groups selected for this sample
and the estimated number of rows each will provide for one CICS region in one collection interval. The

Chapter 5. Reference 123

 space required for a 24 hour period, assuming the collection interval is 5 minutes, is also shown. The Daily
Space amounts are totaled and used to calculate the figures in Table 25 on page 123.
Your environment and which attribute groups you collect near-term history for will affect the amount of
data you collect.

Table 26. OMEGAMON for CICS on z/OS near-term history tables

Attribu Attribute group Agent Estimate Space Per Daily Estimated number of
te name Row Size d Rows Collection Space rows per monitored
group (bytes) (bytes) (bytes) address space each
ID collection interval
CICSB CICSplex Bottleneck 210 11 2310 665280 1 row per detected
NA Analysis wait reason
CON CICSplex Connection 201 20 4020 1157760 1 row per connected
Analysis system
CICSCO CICSplex 136 1 136 39168 1 row
S Connections
Summary
CICSDS CICSplex DB2 118 1 118 33984 1 row
2 Summary
CICSDL CICSplex DBCTL 160 1 160 46080 1 row
S Summary
CICSCD CICSplex Dispatcher 148 1 148 42624 1 row
S Summary
CICSCD CICSplex Dispatcher 148 21 3108 895104 1 row per TCB mode
M TCB Modes
CICSCD CICSplex Dispatcher 152 5 760 218880 1 row per TCB pool
P TCB Pools
CICSCS CICSplex Dynamic 236 15 3540 1019520 15 rows
D Storage Details
CICSIP CICSplex 189 2 378 108864 2 rows
C IPConnection
Analysis
CICSLP CICSplex LSR Pool 162 5 810 233280 1 row per defined LSR
S Status pool, with a maximum
of 8 per interval
MQCON CICSplex MQ 143 1 143 41184 1 row
N Connection Details
KCPPL CICSplex Overview 142 3 426 122688 1 row per CICSplex
X
CICSPP CICSplex Pagepool 311 1 311 89568 1 row
H Summary
KCPWS CICSplex Plex Service 275 100 27500 7920000 1 row per class per
S Class Analysis CICSplex
CICSR CICSplex Region 187 1 187 53856 1 row
OV Overview

124 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 26. OMEGAMON for CICS on z/OS near-term history tables (continued)
Attribu Attribute group Agent Estimate Space Per Daily Estimated number of
te name Row Size d Rows Collection Space rows per monitored
group (bytes) (bytes) (bytes) address space each
ID collection interval
WSS CICSplex Service 283 20 5660 1630080 1 row per class
Class Analysis
CICSST CICSplex Storage 124 15 1860 535680 1 row per storage area
OR Analysis
TRAN CICSplex Transaction 263 20 5260 1514880 1 row per active
Analysis transaction at the
time of each interval
sample
VSAM CICSplex VSAM 240 10 2400 691200 1 row per VSAM file
Analysis

Sample PDS estimates for OMEGAMON for CICS TG on z/OS

This information provides sample estimates for the DASD space required to collect near-term history for
OMEGAMON for CICS TG on z/OS. Factors in your environment will affect how much space you require.
Table 27 on page 125 shows a sample estimate for the total persistent data store (PDS) disk space
required to support three days of history data, collected at 5 minute intervals for various numbers of
monitored CICS TG address spaces. A sample value for KGW_PD_CYL is derived based on the estimates,
assuming the following:
• Six PDS files are allocated.
• The PDS files must be able to contain three days of near-term history.
• The collection interval is every 5 minutes, which is 288 collections each day.
• Near-term history is collected for the attribute groups listed in Table 28 on page 126 and assume the
specifications in that table.
• One cylinder of DASD space can hold approximately 830KB of data.
The Daily Space amounts listed in Table 28 on page 126 are totaled and used to calculate the sample
space estimates in Table 27 on page 125. Numbers were rounded up.

Table 27. Total DASD Space estimates for a varied number of CICS TG address spaces
Number of Daily space Total space Total DASD Space per KGW_PD_CYL
monitored (KB) (KB) for 3 days space (CYL) available PDS value for 6 PDS
CICS TG file files
address
spaces
1 374 1122 2 0.5 3
10 3740 11220 14 3.2 20
20 7480 22440 28 6.3 38
50 18700 56100 68 15.2 92

The estimated number of rows and agent row size are dependent on the attribute groups that have been
chosen to be collected and, depending on the attribute group, how much workload has been performed
during the collection interval. Table 28 on page 126 shows the attribute groups selected for this sample
and the estimated number of rows each will provide for one CICS TG address space in one collection

Chapter 5. Reference 125

 interval. The space required for a 24 hour period, assuming the collection interval is 5 minutes, is also
shown. The Daily Space amounts are totaled and used to calculate the figures in Table 27 on page 125.
Note: Some attribute groups are only available for collection if the address space is a Gateway daemon.
Your environment and which attribute groups you collect near-term history for will affect the amount of
data you collect.

Table 28. OMEGAMON for CICS TG on z/OS near-term history tables

Attribu Attribute group Agent Estimate Space Per Daily Estimated number of
te name Row Size d Rows Collection Space rows per monitored
group (bytes) (bytes) (bytes) address space each
ID collection interval
CTGCM CICSTG Connection 110 1 110 31680 1 row (Gateway
S Manager Threads daemon only)
CTGCS CICSTG CICS TS 468 1 468 134784 1 row per connected
D Region Details CICS region (Gateway
daemon only)
CTGCS CICSTG CICS TS 176 1 176 50688 1 row per monitored
S Regions address space
(Gateway daemon
only)
CTGGD CICSTG Gateway 146 1 146 42048 1 row (Gateway
S Daemon daemon only)
CTGRO CICSTG Region 164 1 164 47232 1 row
V Overview
CTGRT CICSTG Transaction 162 1 162 46656 1 row
S Response Time
Summary
CTGWT CICSTG Worker 102 1 102 29376 1 row (Gateway
S Threads daemon only)

Configuring task history data

This material provides post configuration information for OMEGAMON for CICS (3270) task history data.

Collecting OMEGAMON for CICS (3270) task history data

OMEGAMON for CICS on z/OS collects OMEGAMON for CICS (3270) task history data that can be
displayed from the Online Data Viewing panel. To retain historical task records for a CICS region across
OMEGAMON for CICS (3270) sessions, you must create a task history data set for that CICS region. For
each region where you want to allocate a task history data set, enter the CICS region name, primary
cluster allocation (in cylinders), and a description. To use a VSAM linear file for storing task history data,
ensure the global data parameter for the ONLINE_VIEWER option specifies:

DATA_STORE_FILE_NAME=&rhlev..*.RKC2HIST

Multiple CICS regions can share a single global data area module if you supply an asterisk (*) in the data
set name. In this case, the job name of the CICS region is substituted for the asterisk when the task
history collector is started. The task history data set is a VSAM linear data set and can be up to four
gigabytes.
You can use PARMGEN to generate the JCL job that allocates the OMEGAMON for CICS (3270) historical
data set. See the IBM Z OMEGAMON for CICS: Parameter Reference for the parameters associated with
OMEGAMON for CICS (3270) historical data set allocation.

126 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 For any CICS region where you do not want to retain historical task records across OMEGAMON for CICS
(3270) sessions, you can bypass this step and use a dataspace for the task history feature. The dataspace
is cleared when CICS stops processing or the task history collector is stopped. To use a dataspace, ensure
the global data area parameter for the ONLINE_VIEWER option specifies:

DSPACE: DATA_STORE_TYPE=DSPACE

Detailed procedures for managing the OMEGAMON for CICS (3270)

Global Data Areas
This section contains information about specifying monitoring options for OMEGAMON for CICS (3270).
Updates to the global field helps are maintained in the context help member, KC256DG1, in the
&hilev.TKANCUS library. The values documented in this section were the most current when this
information was created, but the KC256DG1 member always contains the most current descriptions of
the Global Data Area and the standard defaults. You can use ISPF, or a similar interface, or partitioned
data set utility, to list and print this help member.

Overview of the Global Data Area

The Global Data Area sets the values for the monitoring options for OMEGAMON for CICS (3270)
These values are generated during configuration and apply to all OMEGAMON for CICS sessions that are
monitoring the same CICS region. The Global Data Area enables you to set options for OMEGAMON for
CICS features, such as:
• The task history collector
• The historical reporter
• The interval record collector
• The response time collector
To update these values, a CICS system programmer edits a source dataset and runs a verify job.
Furthermore, you can specify whether the CICS regions using this Global Data should deliver transaction
data to the Service Level Analysis feature of the OMEGAMON for CICS agent.
The KC2_CLASSIC_KC2GLB_SRCLIB PARMGEN parameter specifies where the global members are kept.
Global data areas set up performance monitoring collections, such as historical recording for a CICS
region or writing of performance records to SMS. You can update these values dynamically using the
enhanced 3270 user interface or OMEGAMON for CICS (3270); however, the updates will be lost when
you recycle the CICS address space. If you want the changes to be permanent, you must edit the values in
the data set specified by the KC2_CLASSIC_KC2GLB_SRCLIB parameter.
The global data areas, KC2GLBxx, are members of a typical partitioned data set. You can create your own
version by updating the sample provided, then storing it in the same or a separate dataset and copying it
to your selected runtime environments (RTE).
For new PARMGEN-created RTEs (ones not converted from an existing Configuration Tool environment),
specify a common KC2_CLASSIC_KC2GLB_SRCLIB library to store the customized KC2GLB* globals
that can be copied to the different RTEs' RKANPARU libraries referenced in the RKC2GLBL DD of the
KC2_CCnn_CLASSIC_STC. If you are a first time user, you can create your own data set by running a JCL
job provided in the RKANSAMU data set.
For existing RTEs (those created using the Configuration Tool and converted to PARMGEN), the
WKANSAMU(KC2GLBCP) KC2GLB* copy job may be used to copy the customized globals from the
KC2GLB source library specified in the KC2_CLASSIC_KC2GLB_SRCLIB parameter (INSTDATA by default),
to the RKANPARU library referenced in the RKC2GLBL DD of the KC2_CCnn_CLASSIC_STC.
OMEGAMON for CICS is shipped with a pre-defined set of defaults for the Global Data Area in the member
KC2GLB. This member becomes the default for the Global Data Area in the CICS region JCL.

Chapter 5. Reference 127

 When you configure OMEGAMON for CICS, you can update the monitoring options using the parameters in
the Global Data Area.

Determining the values for the monitoring options in IBM Z OMEGAMON for
CICS
Use the following tables to determine the values to specify for the monitoring options. The tables list the
groups of tasks and shows the options available for that task.
These task groups are as follows:
• “Global Options” on page 129
• “Startup Controls” on page 131
• “Exception Analysis Intervals” on page 139
• “Database Collection” on page 139
• “Program Tracking” on page 141
• “Bottleneck Options” on page 142
• “User Excluded Transactions” on page 144
• “User Event Monitoring” on page 144
• “CPU Monitoring” on page 147
• “Group Definitions” on page 148
• “Group Elements” on page 149
• “Interval Collector” on page 151
• “Online Viewer” on page 151
• “Resource Limiting” on page 154
• “Resource Limiting Interval” on page 159
• “Response Time collection” on page 160
• “Dedicated Sessions” on page 162
• “Service Level Analysis” on page 162
• “Enabling outbound API request monitoring” on page 163

128 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Global Options
Table 29. Global options information
Parameter to use Definition Default
CONVERSE_TIME Enables you to include or exclude terminal I/O NOIOWAIT,IRWAIT
and/or IRC wait time in calculating the total
response times for conversational transactions.
This value enables MRO users to more
completely isolate total transaction response
times from I/O-related wait time.
Note: CONVERSE_TIME affects only
OMEGAMON for CICS data. It does not
adjust the response time collected by CICS
monitoring.
CONVERSE_TIME accepts one or two
parameters. The default values for the
parameters are indicated.
IOWAIT
Specifies that CICS monitoring include the
time that conversational tasks wait for
terminal input when reporting the total
response time for that task.
NOIOWAIT
Removes the I/O wait time from the
transaction response time, including output
wait time.
IRWAIT
Specifies that CICS monitoring include the
time that tasks wait for IRC-link-related
processing.
NOIRWAIT
Removes the IRC wait time from the
transaction response time.
Note: For RUNTIME and ELAPSED, this global
option impacts statistics and functionality. If
NOIOWAIT is enabled (which it is, by default),
a task running workload for RUNTIME testing
might show lower values in statistics and
warning, but a kill will be performed anyway.

ETE_INTERVAL Specifies the ETE response history sampling 1

interval in minutes. Values range from 1-7200
(5 days).
ETE_FREQUENCY Determines how often End-to-End (ETE) 1
response time monitoring occurs for each LU
monitored. ETE_FREQUENCY=n specifies that
one count takes place every n occurrences of
LU activity (1-255).
MAX_GROUPS Specifies the maximum number of groups 30
(1-30) that you can define for internal
bottleneck collection, the response time
collector, and the interval record collector.

Chapter 5. Reference 129

 Table 29. Global options information (continued)
Parameter to use Definition Default
MAX_IDS Specifies the maximum number (1-2000) of 50
transaction IDs, program names, LUs, and
terminal IDs for internal bottleneck collection,
the response time collector, and the interval
record collector.
SHUT_OPTIONS Specifies whether IBM Z OMEGAMON for CICS NOPURGE
will purge conversational tasks waiting on
terminal I/O when a non-immediate shutdown
of CICS is performed. KOCOME00 must be
present in the PLT as a shutdown entry.
Possible values are:
PURGE
Causes IBM Z OMEGAMON for CICS
to purge conversational tasks waiting
on terminal I/O when a non-immediate
shutdown of CICS is performed. KOCOME00
must be present in the PLT as a shutdown
entry.
NOPURGE
Does not purge any tasks
OPER
Indicates that the console operator
specifies PURGE or NOPURGE in response
to a WTO.
You can control the purging of tasks during
CICS shutdown through the CICS Shutdown
Purge Option of the IBM Z OMEGAMON for CICS
Classic (3270) interface (fastpath O.Q).

XM_BUFFER_RECORDS Specifies the number of records 100

(1-2,147,483,648) in the buffer that IBM Z
OMEGAMON for CICS uses to accumulate
transaction records within CICS before they
are sent to the response time collector
and the task history collector. This amount
should correspond to the average number
of transactions within a 2-second period.
The default value should be sufficient
unless you see the message "OC0014 XMCR
communication buffer has wrapped for ..." in
the CICS SYSLOG.

130 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Startup Controls
Table 30. Startup controls information
Parameter to use Definition Default
BOTTLENECK_ANALYSIS Specifies whether or not internal bottleneck AUTO
collection starts automatically.
Possible values are:
AUTO
Start internal bottleneck collection
automatically.
NOAUTO
Do not automatically start internal bottleneck
collection. If you specify NOAUTO, you
can start internal bottleneck collection for
the current region through the Bottleneck
Analysis Control panel of the OMEGAMON for
CICS (3270) interface (faspath O.I).
Note: NOAUTO cannot be specified if you also
specify INTERVAL_RECORDING=AUTO.

Chapter 5. Reference 131

 Table 30. Startup controls information (continued)
Parameter to use Definition Default
CPU_THRESHOLDING Determines whether or not the MAXR exception AUTO
is tripped when CPU consumption exceeds the
MAXCPU threshold. The MAXR exception takes
effect only if you use MAXCPU to specify a
CPU consumption threshold greater than 0. In
addition, CICS version 3.x users must specify
CPU=YES in the MCT to instruct CICS to monitor
CPU consumption.
Possible values are:
AUTO
The MAXR exception is automatically tripped
when the MAXCPU threshold is exceeded.
ENABLE
This setting allows you to activate the
MAXR exception during an OMEGAMON for
CICS session. You can display or change
the global resource limit CPU threshold in
the OMEGAMON for CICS (3270) system.
Select the MAXR option (K) on the Exception
Settings path (under the Profile menu) or
enter fastpath P.A.K. from any panel.
DISABLE
The MAXR exception cannot be activated
during an OMEGAMON for CICS (3270)
session, regardless of CPU consumption
monitoring.
Note: Once a transaction has tripped the MAXR
exception, that transaction will continue to
appear on the Tasks Exceeding Global CPU
Time Limit panel of the OMEGAMON for CICS
(3270) interface, even if you increase the CPU
consumption threshold. Use the more powerful
features of resource limiting instead of MAXR.

DB2_CLOCKS_AND_COUNTERS Specifies whether the DB2 data collector starts AUTO

up automatically. DB2 collector accumulates
elapsed times and counts of DB2 commands for
each CICS transaction.
Possible values are:
AUTO
Specifies that the DB2 data collector starts up
automatically.
NOAUTO
Do not automatically initialize collection.
If you specify NOAUTO, you can dynamically
start and stop DB2 collection through the Control
Database Collectors panel of the OMEGAMON for
CICS (3270) interface (fastpath O.P).

132 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 30. Startup controls information (continued)
Parameter to use Definition Default
DLI_CLOCKS_AND_COUNTERS Specifies whether the DL/I data collector starts AUTO
automatically. The DL/I collector accumulates
elapsed times and counts of DL/I commands for
each CICS transaction.
Possible values are:
AUTO
Specifies that the DL/I data collector starts
automatically.
NOAUTO
Do not automatically initialize collection.
NO
Disable DL/I collection.
Specifying AUTO or NOAUTO enables the
XDLIPRE and XDLIPOST global user exits. You can
dynamically start and stop DL/I collection through
the Control Database Collectors panel of the
OMEGAMON for CICS (3270) interface (fastpath
O.P).
If you specify NO, however, you cannot activate
DL/I collection dynamically.

INTERVAL_RECORDING Specifies whether the interval record collector NOAUTO

starts automatically.
Possible values are:
AUTO
Specifies that the interval record collector
starts automatically.
NOAUTO
Do not start the interval record collector.
You can start the interval record collector through
the Control Interval Recording Collector panel
of the OMEGAMON for CICS (3270) interface
(fastpath O.K).
Note: AUTO requires that
BOTTLENECK_ANALYSIS=AUTO also be specified
in the STARTUP_CONTROL component.

Chapter 5. Reference 133

 Table 30. Startup controls information (continued)
Parameter to use Definition Default
ONLINE_DATA_VIEWING Specifies whether the task history collector starts AUTO
up automatically.
Possible values are:
AUTO
Indicates that the task history collector starts
up automatically.
NOAUTO
Do not start up the task history collector.
You can start the task history collector through
the Start Online Historical Transaction Viewing
Collector panel in the OMEGAMON for CICS
(3270) interface (fastpath O.F).

RESOURCE_LIMITING Specifies whether OMEGAMON for CICS NOAUTO

automatically monitors tasks for resource limiting
once it is initialized.
Possible values are:
AUTO
Specifies that OMEGAMON for CICS
automatically monitors tasks for resource
limiting once it is initialized.
NOAUTO
Specifies that OMEGAMON for CICS does
not monitor tasks until you explicitly start
resource limiting from an OMEGAMON for
CICS session.
You can start resource limiting through the START
RESOURCE LIMITING panel of the OMEGAMON
for CICS (3270) interface (fastpath O.R).

134 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 30. Startup controls information (continued)
Parameter to use Definition Default
RESOURCE_LIMITING_MSG_DEST Specifies the destination for RLIM messages TDQ
OC8902 and OC8903. Following is a list of
possible resource message destination values:
TDQ
Specifies that RLIM messages OC8902 and
OC8903 are only written to transient data
destination CSSL.
LOG
Specifies that RLIM messages OC8902 and
OC8903 are written to the System Console.
No messages will be written to transient data.
TDL
Specifies that RLIM messages OC8902 and
OC8903 are written to the transient data
destination CSSL and the System Console.
(LOG,WARN)
Specifies that RLIM message OC8902 is
written to the System Console. No messages
will be written to the transient data
destination CSSL.
(TDL,WARN)
Specifies that RLIM messages OC8902 and
OC8903 are written to the transient data
destination CSSL. RLIM message OC8902 is
also written to the System Console.
The current settings may be viewed on the
OMEGAMON for CICS (3270) system's RESOURCE
LIMITING STATUS panel (fastpath O.T).

Chapter 5. Reference 135

 Table 30. Startup controls information (continued)
Parameter to use Definition Default
RESOURCE_LIMITING_SYSTEM_TASK This parameter allows you to use the WARN NO
S thresholds specified in Resource Limiting to
alert you to any system tasks which exceed
the WARN threshold. It also allows you to
KILL tasks using IBM-provided programs, these
might include CEMT or CICS mirror transactions.
CICS transaction manager determines which
transactions are system tasks.
Possible values are:
NO
Resource Limiting will not KILL or WARN a
transaction which is marked as a system task
or is running a program which begins with
DFH, EYU, DSN, or CSQ.
YES
Resource Limiting will WARN transactions
marked as a system task. It will WARN and
KILL transactions which are currently running
a program which begins with DFH, EYU, DSN,
or CSQ if the limit is exceeded.
Note:
It is not possible to KILL a system task using
Resource Limiting.

RESOURCE_LIMITING_ABEND_CANC Specifies whether the CANCEL option is used by YES

EL RLIM when KILLing a transaction
Possible values are:
YES
Specifies that the CANCEL option is used by
RLIM when KILLing a transaction. This means
that the HANDLE ABEND routine will not be
invoked. Typically this is the desired behavior
as RLIM is designed to prevent excessive
resource consumption and a HANDLE ABEND
routine could, for example, continue the
transaction.
NO
Specifies that the CANCEL option is not used
by RLIM when KILLing a transaction.
Note: RLIM will attempt to KILL a task only once.
If a task continues to process and exceeds other
limits RLIM will take no action for this task.

136 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 30. Startup controls information (continued)
Parameter to use Definition Default
RESOURCE_LIMITING_TRACE_WARN Specifies whether transactions that are warned by YES
ED RLIM will have Application Trace activated for the
task automatically
Possible values are:
YES
Specifies that transactions that are warned by
RLIM will have Application Trace activated for
the task automatically. This will enable the
trace to be viewed from the Task display or
from Online Data viewing once the transaction
ends. This will not affect other Application
Trace settings or filters.
NO
Specifies that Application trace will not be
enabled when RLIM warns a task.

ENABLE_APPLICATION_TRACE Specifies whether OMEGAMON for CICS will be NOAUTO

able to record Application Trace for transactions
running in CICS.
Possible values are:
AUTO
Specifies that OMEGAMON for CICS will
be able to record Application Trace for
transactions running in CICS. This does not
mean that all transactions will be traced. It
refers to the capability to enable trace for a
task from the OMEGAMON for CICS (3270)
system or via Resource Limiting.
NOAUTO
Specifies that OMEGAMON for CICS will not
trace transactions until you explicitly enable
Application Trace from an OMEGAMON for
CICS session.
You can enable Application Trace through the
Application Trace Facility Status panel of the
OMEGAMON for CICS (3270) interface (fastpath
O.W).

Chapter 5. Reference 137

 Table 30. Startup controls information (continued)
Parameter to use Definition Default
ENABLE_FILE_CONTROL_EXIT Specifies whether global user exits XFCFRIN and NO
XFCFROUT will be initialized. These exits enable
OMEGAMON for CICS to collect file level data for
transactions which access VSAM files.
Possible values are:
NO
Do not enable global user exits XFCFRIN and
XFCFROUT.
YES
Global user exits XFCFRIN and XFCFROUT
are enabled, and OMEGAMON for CICS GLUE
code is enabled at exit points. YES should
typically be specified only in a File Owning
Region.

RESPONSE_TIME_ANALYSIS Specifies whether the response time collector AUTO

starts up automatically.
Possible values are:
AUTO
Specifies that the response time collector
starts up automatically.
NOAUTO
Do not start up the response time collector.
You can start the response time collector during
a session using the START RESPONSE TIME
MONITOR panel of the OMEGAMON for CICS
(3270) interface (fastpath O.A).

AUTO_RESTART Specifies whether, after the OMEGAMON for CICS NO

address space is restarted, OMEGAMON for CICS
is not restarted in the CICS region
Possible values are:
NO
Specifies that after the OMEGAMON for CICS
address space is restarted OMEGAMON for
CICS is not restarted in the CICS region.
YES
Specifies that following a restart of
the OMEGAMONfor CICS address space,
OMEGAMON for CICS will attempt to start
the Online Data Viewing (ONDV) component
to collect information contained within the
OMEGAMON buffers. It will then perform an
OMEG REMOVE and an OMEG INIT to refresh
the OMEGAMON code in the CICS region and
restart the required features.

138 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 30. Startup controls information (continued)
Parameter to use Definition Default
HISTORY_CATCHUP_TIME Specifies the maximum time in seconds (0-300) 0
after a restart of the OMEGAMON for CICS
address space that OMEGAMON will wait for the
Online Data Viewing component to retrieve the
data in the OMEGAMON buffers before starting
the recycle of the code in the CICS region. If
a value of 0 is coded (the default), no attempt
is made to start history prior to recycling the
OMEGAMON code in the CICS region.
TRANSACTION_TRACKING Specifies whether the Transaction Tracking API NOAUTO
will be initialized when the OMEGAMON for CICS
address space is started.
Possible values are:
AUTO
Specifies that the Transaction Tracking API
will be initialized when the OMEGAMON for
CICS address space is started.
NOAUTO
Do not initialize the Transaction Tracking API
when the OMEGAMON for CICS address space
starts. You can also initialize the Transaction
Tracking API through the OMEGAMON for
CICS (3270) system.

Exception Analysis Intervals

Table 31. Exception analysis intervals information
Parameter to use Definition Default
VSAM_MONITORING_INTERVAL Specifies the interval of time for which statistics 15 minutes
concerning VSAM CA splits, CI splits and extents
are collected. Possible values for this field
are 1-1440 minutes. A value of zero means
statistics are collected and evaluated every time
the Region Status or VSAM panels are refreshed.
DUMPS_MONITORING_ Specifies the interval of time for which statistics 15 minutes
INTERVAL concerning system dumps and transaction
dumps are collected. Possible values for this
field are integers from 1-60 minutes.
VIOLATIONS_MONITORING_ Specifies the interval of time for which statistics 15 minutes
INTERVAL concerning storage violations are collected.
Possible values for this field are 1-60 minutes.

Database Collection
In this section of the Global Data Areas values, you can select database products to be monitored. You
can specify ADABAS, Db2, DATACOM, DLI, IDMS, SUPRA, VSAM, MQ, or USREVNT1 for monitoring to get
file I/O statistics by transaction.
VSAM statistics are derived from only EXEC-level file control requests.

Chapter 5. Reference 139

 To capture DL/I statistics at OMEGAMON for CICS startup, you must specify
DLI_CLOCKS_AND_COUNTERS=AUTO on the STARTUP_CONTROL component. DL/I statistics are from
EXEC-level or CALL-level requests. For local or remote PSBes, the statistics are captured by DBD name.
For DBCTL, the statistics are captured by PSB name.
For ADABAS, CA-DATACOM, IDMS, and SUPRA, you must carry out the installation process as described in
“Installing third-party support” on page 196
If you wish to monitor an event other than the supported Files or Databases, specify the USREVNT1
sub-component.
Selecting the database types also affects the global user exits that will be enabled during this execution of
CICS. The OMEGAMON for CICS code, which runs at XMNOUT and XEIOUT, is activated by default (unless
the CICS_CMF_MONITORING parameter is set to NO). The OMEGAMON for CICS GLUE code is activated
as follows:
• DLI=YES will enable XDLIPRE and XDLIPOST.
• MQ=YES will enable XRMIOUT.
• TRACE=YES will enable XRMIOUT and XPCABND.
Each of the databases previously discussed can be set with the following values:

Table 32. Database collection values information

Parameter to use Definition Default
AUTO_START Specifies that collection starts up automatically. YES
ONDV_WRITE Specifies that statistics are to be available for YES
the task history collector.
SMF_WRITE Specifies whether to write statistics to SMF for NO
batch reporting.
Possible values are:
YES
Writes statistics to SMF for batch reporting.
NO
Does not write to SMF.
TRACE data cannot be written to SMF. If
you select this option the SMF_WRITE=YES
parameter card will be discarded.

DETAIL Specifies report formatting option for ADABAS NO

clock and counter statistics.
Possible values are:
YES
Appends the command code to Database ID
and causes the file number to display the
name of an ADABAS database accessed by a
CICS transaction.
NO
Does not alter the database name.

The following options are also available when USREVNT1 is specified:

140 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 33. Additional database collection options available when USREVNT1 is specified
Parameter to use Definition Default
EVENT Defines a 1-8 character name. This operand None
is used only when USREVNT1 is specified. It
denotes an in-house database name, a user
program name, or any other user event.
FUNCTION Defines a list of 1 to 10 names. Each name None
represents a pair of buckets used to hold
the clock and count statistics related to the
previously defined EVENT. A FUNCTION name
must be between 1 and 8 characters long.

Note: The following example shows EVENT and FUNCTION specifications.

EVENT=MYDBASE
FUNCTION=(BROWSE,ADD,UPDATE,DELETE)

Program Tracking
Table 34. Program Tracking information
Parameter to use Definition Default
ENABLE Specifies whether Program Tracking is enabled. NOAUTO
AUTO: Start Program Tracking automatically.
NOAUTO: Do not automatically start Program
Tracking.
AGGREGATE This option will allow you to see the metrics for NOAUTO
program usage across the entire CICS region.
These metrics are accumulated as of when the
task ends. Looking at programs used within
a CICS region, the Used tab will show the
collective metrics for all programs which have
had data collected since the region started or
program manager statistics were reset.
WRITE_TO_HISTORY This option will record the collected program YES
data for a task to Task History. This will provide
the Programs tab when looking at the details for
a task. This tab will provide information about
all programs used during the time covered by
the history record.
SMF This option will record the collected information NO
to SMF. The data can then be processed offline
by utilities such as IBM CICS Performance
Analyzer.

Chapter 5. Reference 141

 Bottleneck Options
Table 35. Bottleneck options information
Parameter to use Definition Default
CLEAR_INTERVAL_LONG Specifies (in minutes) the default CLEAR 30
interval for long-term accumulators (0-999). To
disable this automatic reset, specify 0.
CLEAR_INTERVAL_SHORT Specifies (in minutes) the default CLEAR 10
interval for short-term accumulators (0-999).
Zero (0) resets the short-term accumulators
every internal bottleneck collection cycle.
SAMPLE_INTERVAL Specifies (in tenths of a second) the sample 23
interval for internal bottleneck collection
(1-99).
Note: The relationship between
SAMPLE_INTERVAL and CPU usage is not linear.
For example, changing the interval from 2 to 4
seconds does not yield a 50% reduction.

VARIABLE_BUCKETS Specifies the maximum number of variable 1000

buckets that internal bottleneck collection can
allocate. The value can range from 0-32767.
Whenever the allocated storage overflows, the
Bottlenecks panel in the OMEGAMON for CICS
(3270) interface displays a new line that shows
the wait reason sub-ID of *OVERFLW* and also
the percentage of waits that used the overflow
area.
Note: Use the following formula to compute the
amount of storage required for each variable
bucketset.

(12*X) + 92

Where X is the maximum number of groups

coded on the MAX_GROUPS operand of the
GLOBAL_OPTIONS component.

EXCLUDE_SYSTEM_TASKS Specifies whether system tasks waiting on NO

resources are excluded from Bottleneck
Analysis.
Possible values are:
YES
Specifies that system tasks waiting on
resources are excluded from Bottleneck
Analysis.
NO
Specifies that system tasks waiting on
resources are not excluded from Bottleneck
Analysis

142 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 35. Bottleneck options information (continued)
Parameter to use Definition Default
EXCLUDED_TRANS Specifies transactions to be excluded from None
Bottleneck Analysis. This can be the actual 1-
to 4-character transaction ID(s) or a generic
specification using wildcard characters. You can
use the question mark (?) wildcard character for
single-character substitution and the asterisk
character (*) as a trailing character only.
The following are examples of wildcarding:
• EXCLUDED_TRANS=(ABCD,E*): Excludes the
ABCD transaction(s) and all transaction IDs
that begin with E.
• EXCLUDED_TRANS=F?: Excludes all 2-
character transaction IDs where the first
character is F.
• EXCLUDED_TRANS=G??H: Excludes all 4-
character transaction IDs starting with G and
ending with H.
The following transaction IDs are always
excluded from Bottleneck Analysis:
• CSSY System Task
• CSJC Journal Control
• CVST VSAM Subtasking
• CSSX IRLM Abend Recovery
• CSGX IRLM Global Command
• CSNC Cross Region Support
• DSNC DB2 Support
Note: If the list of transactions will not fit
on one line, use additional EXCLUDED_TRANS
statements.

BOTTLENECK_ANALYSIS Specifies whether internal bottleneck collection AUTO

starts automatically.
Possible values are:
AUTO
Start internal bottleneck collection
automatically.
NOAUTO
Do not automatically start internal
bottleneck collection. If you specify
NOAUTO, you can start internal bottleneck
collection for the current region through the
BOTTLENECK ANALYSIS CONTROL panel of
the OMEGAMON for CICS (3270) interface
(faspath O.I).
Note: NOAUTO cannot be specified if you also
specify INTERVAL_RECORDING=AUTO.

Chapter 5. Reference 143

 User Excluded Transactions
To simplify your user-defined situations, you can specify a list of transactions that you want to exclude
from being counted toward a situation. This user excluded list of transactions will reside in the
OMEGAMON for CICS global data member.
To exclude transactions, specify the USER_EXCLUDED_TRANS parameter, with the TranID(s) you want to
exclude.
A user-defined situation can then check for the TranID value(s) you specified. If a transaction has a name
that matches the value of USER_EXCLUDED_TRANS, that transaction will not be included in the situation.
You can use the question mark (?) and asterisk (*) wildcard characters in the transaction list; the asterisk
can only be used as a trailing character.
Note: With PTF UJ01596, the CPU_EXCLUDED_TRANS section in the global data member was
repurposed as USER_EXCLUDED_TRANS for use with situations. If you refresh your global data
member or perform a Reformat (KC2GLBVR Job) , the CPU_EXCLUDED_TRANS section will be renamed
USER_EXCLUDED_TRANS. When the TRAN attribute group formats a row, it will check if the TranID, as
displayed, matches an entry in the USER_EXCLUDED_TRANS list. If so, the new excluded attribute is set
to YES. If the TranId is not in the list, the excluded attribute is set to NO. There are two other conditions
where the agent cannot make a determination. In these cases, a specific value is used for the attribute:
• If the KOCCI is not active. The attribute value O (No_KOCCI) is used.
• If the global data member is not loaded. The attribute value G (No Global) is used.

Table 36. User excluded transactions

Parameter to use Definition Default
EXCLUDED_TRANS The transactions you want to exclude from None
situations.

The exclude list may contain the actual 1-

to 4-character transaction ID(s) or a generic
specification using wildcard characters. You can
use the question mark (?) wildcard character for
single-character substitution and the asterisk (*)
as a trailing character only. The following are
examples of wildcarding:
EXCLUDED_TRANS=(ABCD,E*)
Excludes the ABCD transaction(s) and all
transaction IDs that begin with E.
EXCLUDED_TRANS=F?
Excludes all 2-character transaction IDs where
the first character is F.
EXCLUDED_TRANS=G??H
Excludes all 4-character transaction IDs starting
with G and ending with H.

User Event Monitoring

Defines and tailors user-event monitoring to OMEGAMON for CICS. OMEGAMON for CICS turns on
several global user exits and, if not already activated, CICS CMF performance monitoring. This allows
OMEGAMON for CICS to collect additional data about transaction execution.
This data is used by the response time collector, interval record collector, resource limiting, and task
history collector; and appears in SMF 112 and SMF 110 records written to SMF from the CICS address
space by both OMEGAMON for CICS and CICS. This additional data causes a slight increase in the

144 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

pathlength of CICS transactions and in the CPU usage of the monitored CICS address space, depending on
the transaction load.
OMEGAMON for CICS lets you limit the additional CPU utilization introduced by OMEGAMON for CICS into
CICS transaction execution path length.
CICS_CMF_MONITORING can be used to suppress the automatic activation of CICS CMF performance
monitoring.

Table 37. User event monitoring information

Parameter to use Definition Default
BASIC_SECTION=OMEGBSC Specifies the entry name of the event-monitoring OMEGBSC
point in the MCT for the BASIC section. This
name must match the ID operand of the
DFHMCT macro.
DB2_SECTION=OMEGDB2 Specifies the entry name of the event-monitoring OMEGDB2
point in the MCT for the DB2 section. This name
must match the ID operand of the DFHMCT
macro.
DLI_SECTION=OMEGDLI Specifies the entry name of the event-monitoring OMEGDLI
point in the MCT for the DLI section. This name
must match the ID operand of the DFHMCT
macro.
MQ_SECTION Specifies the entry name of the event-monitoring CANMQ
point in the MCT for the MQ section. This name
must match the ID operand of the DFHMCT
macro.
USREVNT1_SECTION Specifies the entry name of the event-monitoring CANUE1
point in the MCT for the USREVNT1 section.
This name must match the ID operand of the
DFHMCT macro.

Chapter 5. Reference 145

 Table 37. User event monitoring information (continued)
Parameter to use Definition Default
CICS_CMF_MONITORING Suppresses startup CMF performance YES
monitoring only if not already active.
Possible values are:
YES
Allows CMF performance monitoring and
XMNOUT CICS global user exit.
NO
Monitoring status inactive
Notes®:
1. When CICS_CMF_MONITORING=NO is
specified, the following features of
OMEGAMON for CICS are not functional: Task
history, Application trace, Interval record
collector, Response time collection, SMF data
suppression, File statistics, Storage statistics,
Program compressions, Task CPU utilization,
TP I/O data. Resource limiting for the
following resources: CPU, DLI, DSA, EDSA,
VSAM
2. CICS_CMF_MONITORING=NO overrides any
DLI specification in the STARTUP_CONTROL
component.
3. CICS_CMF_MONITORING=NO disables
all global user exits.
CICS_CMF_MONITORING=YES enables all
global user exits required for data collection
in your environment.
4. Global user exits are not required for resource
limiting of the following resources: ADABAS,
DATACOM, Db2, ELAPSED, IDMS, SUPRA,
USREVNT1

CICS_CMF_WRITE Determines whether CMF is allowed to generate YES

and write SMF type 110 records.
Possible values are:
YES
Allows CMF to write SMF type 110 records.
Be sure that the SMF data sets are large
enough for these records.
NO
CMF is not allowed to write SMF type 110
records.
Note: If you specify CICS_CMF_WRITE=NO and
CICS_CMF_MONITORING=YES, OMEGAMON for
CICS turns on CMF in order to collect transaction
data about response time and task history, but
does not log this data to SMF (for batch reporting
by the historical reporter).

146 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 37. User event monitoring information (continued)
Parameter to use Definition Default
COMPRESS_SMF112_RECORDS Controls the compression of the OMEGAMON NO
for CICS SMF 112 (database) records during
XMNOUT processing.
Possible values are:
NO
OMEGAMON for CICS will write
uncompressed SMF records.
YES
Allows OMEGAMON for CICS to compress the
SMF buffer before it is written to SMF.
You can optionally write database performance
data to SMF.
The OMEGAMON for CICS SMF buffers may
contain data for multiple CICS transactions, and
will be written to SMF when the buffer fills.
Optionally the data can be compressed before
the write to SMF occurs. This compression is
performed using a standard compression utility,
CSRCESRV.

MCT_VALIDATION_MESSAGES OMEGAMON EMPs are required if data is to be NO

written to SMF. This field specifies whether the
MCT scan routine will display messages.
Possible values are:
NO
The MCT scan routine will not display
messages regarding OMEGAMON EMPs.
YES
The MCT scan routine will display messages
regarding OMEGAMON EMPs

CPU Monitoring
The parameter defines the threshold for monitoring internal CPU consumption by CICS transactions.

Chapter 5. Reference 147

 Table 38. CPU monitoring information
Parameter to use Definition Default
CPU_THRESHOLD Specifies the CPU-consumption threshold in 0
seconds (0-32,768). The default, 0, means that
the CPU-consumption exception (MAXR) will not
be tripped.
Note: The CPU_THRESHOLDING operand of
the STARTUP_CONTROL component determines
whether the MAXR exception is tripped when
the threshold is exceeded. Once a transaction
has tripped the MAXR exception, that transaction
will continue to appear on the Tasks Exceeding
Global CPU Time Limit panel, even if you
increase the CPU-consumption threshold.

Group Definitions
Group Definitions define transaction, terminal, and program groups for internal bottleneck collection.
You can also dynamically define groups through the Groups panel of the OMEGAMON for CICS (3270)
interface (fastpath,G.), but the changes remain in effect only temporarily.
Keep in mind the following group definition limits for a CICS region:
1. You can define as many as 30 groups.
2. Each group can contain one or more element names, such as a CICS transaction ID or terminal ID.
3. All the elements in a group must be of the same resource type.
4. You can define a maximum aggregate of 2000 elements across all groups.
5. The same element can appear in multiple groups.
Code one subentry for each group you define. Each entry must have a unique group number and group
name.

Table 39. Group Definitions information

Parameter to use Definition Default
GROUP_NUMBER Specifies the group number (01-30) or the 01
maximum number of groups allowed as
specified by the MAX_GROUPS operand of the
GLOBAL_OPTIONS component.
GROUP_NAME Specifies the name of this group (1-12 (TRAN GRP A* )
characters).
GROUP_TYPE Specifies the group type (PROG, TERM, or TRAN). TRAN

148 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 39. Group Definitions information (continued)
Parameter to use Definition Default
RESPONSE_TIME_THRESHOLD Specifies average response time thresholds for 20
this group (1-999 tenths of a second) for the
interval record collector and the response time
displays.
Note: OMEGAMON for CICS, uses the value
you specify as the Warning threshold for the
response time light. Also, OMEGAMON for
CICS doubles the RESPONSE_TIME_THRESHOLD
value to compute the critical threshold for the
response time light.

Group Elements
Group Elements define elements in one or more monitoring groups.
You can also dynamically define elements within groups through the Groups panel of the OMEGAMON for
CICS (3270) interface (fastpath G.).
Specifies information for an ID entry. You must specify at least one ID.TERM, TRAN, PROG, LU, and
TASKREQ are mutually exclusive. You must code a separate ID for each element that you wish to include
in a group.
You can use the PROG, TERM, and TRAN keywords with an asterisk (*) as a wildcard character to
represent all possible characters. For example, TERM=L* specifies all terminals beginning with the letter
L.

Table 40. Group Elements information

Parameter to use Definition Default
GRAPH_SCALE Specifies the height (1-99 seconds) of the 2
response time problems (RSP) graph. This entry is
for the response time collector only.
TIME_WINDOW Specifies the selection time window (1-10 10
minutes) for the RSP dynamic slot analysis (moving
time slots). This entry is for the response time
collector only.

Chapter 5. Reference 149

 Table 40. Group Elements information (continued)
Parameter to use Definition Default
ID Specifies the start of the ID entry. You must code a None
separate ID entry for each element that you wish to
include in a GROUP.
Possible values are:
TRAN
Specifies a 4-character transaction ID.
(Accepts the * wildcard character.)
PROG
Specifies the 8-character program name.
(Accepts the * wildcard character.)
TERM
Specifies a terminal ID, as defined in the CICS
terminal control table (TCT). (Accepts the *
wildcard character.)
TASKREQ
Specifies a 4-character special ID that
corresponds to a PA key, function key, light pen,
and so forth, as shown in this example:

#PAnPA keys (n = 1-3).

#FnnPF keys (nn = 01-36).
#LPALight pen attention.
#MAGMagnetic stripe reader.
#OCDOperator ID card

Note: TRAN, PROG, TERM, and TASKREQ are

mutually exclusive.

ELIGIBLE_GROUPS Specifies the GROUP or GROUPS with which (01)

the ID is associated. You can specify from 1
to the maximum number of groups allowed
according to the MAX_GROUPS operand of the
STARTUP_CONTROL component.
TOTAL_RESPONSE_THRESHOLD Specifies the response time threshold (0-999 20
tenths of a second) at which this ID appears in the
dynamic portion of the RSP display. This entry is for
the response time collector only.
HOST_RESPONSE_THRESHOLD Specifies the host response time threshold (0-999 None
tenths of a second). If an LU exceeds this
threshold, the ETE response time displays show
the host response time in red and record the
condition in the response history graph with a red
bar. This operand can be specified only for LU IDs.
NETWORK_RESPONSE_THRESHOLD Specifies the network response time threshold None
(0-999 tenths of a second). If an LU exceeds this
threshold, the ETE response time displays show
the network response time in red and record the
condition in the response history graph with a red
bar. You can use this operand only for LU IDs.

150 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 40. Group Elements information (continued)
Parameter to use Definition Default
FIXED_DISPLAY Indicates whether the ID should remain on the NO
graph presented by the RSP command in the
OMEGAMON for CICS (3270) system, regardless of
the response time.
Possible values are:
YES
The ID should always be displayed on the RSP
graph.
NO
The ID will only appear on the RSP graph
when the response time threshold has been
exceeded.

Interval Collector
This set of values defines interval record collector options. After the options are defined in the global data
area module, you can control the interval record collector options through the Control Interval Recording
Collector panel in the OMEGAMON for CICS (3270) system (fastpath O.K).

Table 41. Interval Collector information

Parameter to use Definition Default
NUMBER_DASD_DEVICES Specifies the number of internal queue 0
elements for the I/O sub-analysis routine (the
number of DASD devices allocated to the CICS
region). Valid values are 0-99. A value of
0 indicates that no I/O sub-analysis will be
conducted by Interval Recording.
RECORDING_INTERVAL Specifies the interval recording collection 1 minute
interval. This interval may be set to a value from
1-255 minutes.

Online Viewer
This section defines options for the task history collector. The following values are defined:

Chapter 5. Reference 151

 Table 42. Online Viewer information
Parameter to use Definition Default
DATA_STORE_TYPE Defines the way that data is saved. DSPACE

Possible values are:

DSPACE
Indicates that data for task history collection
is saved in a data space owned by the
OMEGAMON for CICS (3270) interface. This
data is saved until the task history collector
terminates.
FILEOCMP
Indicates that task history data is saved in a
VSAM linear dataset. No z/OS data space is
used. FILEOCMP is required if you have a very
large number of CICS transaction records
that you wish to access through the ONDV
command in OMEGAMON for CICS (3270)
interface.
The size of the VSAM file does not have
an impact on the amount of virtual storage
used in the OMEGAMON for CICS or CICS
address spaces. FILEOCMP causes data to be
compressed before it is written to the data
store.
The file should be allocated prior to restarting
the CICS address space using this FILEOCMP
monitoring option. Refer to the planning and
configuration guide for further information.
Auto
Indicates that the value of
DATA_STORE_TYPE could automatically be
switched between DSPACE and FILEOCMP.
The value FILEOCMP is used if the file which
is specified for a CICS region exists. If no file
matches the definition then the value DSPACE
is used.
Whether you use a data space or linear dataset,
the task history collector writes records using
a wraparound format. Once the data space or
dataset is full, the task history collector resumes
writing records from the beginning, overlaying the
previous data.

DATA_STORE_SIZE If you specify DSPACE, you must specify the size 956
of the data space in kilobytes. Each transaction
record requires about 808 bytes. The maximum
size is 2,097,148 kilobytes.

152 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 42. Online Viewer information (continued)
Parameter to use Definition Default
RESERVED_SIZE Specifies the portion of the data space (from 0 25
to 50 percent) reserved for file, database clock
and counter statistics, and Application Trace
records. See the Application Trace feature in the
OMEGAMON for CICS.
You must specify a number greater than 0 or
statistics by filename and/or Application Trace
records will not be available from the task history
collector.
The RESERVED_SIZE operand is not needed
when the DATA_STORE_TYPE=FILEOCMP is
specified. It will be ignored if it is supplied.
File and database clock and counter statistics
are always available in the FILEOCMP data store
when they are being collected in the CICS region
(through use of the DATABASE_COLLECTION
component).

DATA_STORE_FILE_NAME Specifies the name of a VSAM linear dataset None

when the DATA_STORE_TYPE=FILEOCMP or
DATA_STORE_TYPE=AUTO is specified.
You can share global data area modules (but not
VSAM data sets) across different CICS regions
even though a dataset name is specified in the
global data area module. To do this, you must
insert one wildcard character (*) somewhere in
the VSAM dataset name on this operand. When
the task history collector is running, the wildcard
character is replaced by the job name of the CICS
region being monitored. The wildcard character
may appear anywhere in the dataset name and
should occur only once.

Chapter 5. Reference 153

 Table 42. Online Viewer information (continued)
Parameter to use Definition Default
EXCLUDED_TRANS Indicates transactions to exclude from analysis. None
The list of transactions is limited to 63
transaction IDs. Transactions that start before
phase 3 of the PLTPI or end after phase 1 of
the PLTSD are not excluded. Any CICS-generated
transactions that initiate without going through
TRUE processing are not excluded either.
The exclude list may contain the actual 1-
to 4-character transaction ID(s) or a generic
specification using wildcard characters. You can
use the question mark (?) wildcard character
for single-character substitution and the asterisk
character (*) as a trailing character only. The
following are examples of wildcarding:

EXCLUDED_TRANS=(ABCD,E*)

Excludes the ABCD transaction(s) and all

transaction IDs that begin with E.

EXCLUDED_TRANS=F?

Excludes all 2-character transaction IDs where

the first character is F.

EXCLUDED_TRANS=G??H

Excludes all 4-character transaction IDs starting

with G and ending with H.
Note: If the list of transactions will not fit
on one line, use additional EXCLUDED_TRANS
statements.

Resource Limiting
Resource Limiting defines resources with their respective thresholds and identifies the action to be taken
when a resource threshold or limit has been exceeded.

154 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 43. Resource Limiting Parameters
Parameter to use Definition Default
Resource Specifies a resource for limiting usage: None

VSAM
EXEC-level file control requests.
DSA
HWM of storage from the DSA.
EDSA
HWM of storage from the UDSA and EUDSA.
GDSA
HWM of storage from the GUDSA.
CPU
CPU time limit.
ELAPSED
Elapsed time limit.
CONTAINR
HWM of Container storage used by the task.
CPUGP
Time spent on a General Processor CPU.
CPUQR
Time spent on the QR TCB.
DLI
EXEC DL/I and CALL DL/I requests.
ADABAS
ADABAS requests.
IDMS
IDMS requests.
DATACOM
DATACOM requests.
SUPRA
SUPRA requests.
DB2
DB2 requests.
MQ
Message queuing requests
RUNTIME
Time for tasks held due to MXT or Class
maximum. This is the time the task actually
ran excluding time spent waiting for MXT or
Class max tasks.
USREVNT1
Any user-defined requests.

Chapter 5. Reference 155

 Table 43. Resource Limiting Parameters (continued)
Parameter to use Definition Default
EXCLUDED_TRANS Specifies one or more transactions to exclude
from resource limiting. This can be the actual
1- to 4-character transaction ID(s) or a generic
specification using wildcard characters. You can
use the question mark (?) wildcard character
for single-character substitution and the asterisk
character (*) as a trailing character only.
The following are examples of wildcarding:

EXCLUDED_TRANS=(ABCD,E*)

Excludes the ABCD transaction(s) and all

transaction IDs that begin with E

EXCLUDED_TRANS=F?

Excludes all 2-character transaction IDs where

the first character is F.

EXCLUDED_TRANS=G??H

Excludes all 4-character transaction IDs starting

with G and ending with H.
Non-displayable transaction IDs are specified as
follows:

#PAnPA keys (n = 1-3).

#FnnPF keys (nn = 01-36).
#LPALight pen attention.
#MAGMagnetic stripe reader.
#OCDOperator ID card

Note: Neither KILL_LIMIT nor WARN_LIMIT can

be used with EXCLUDED_TRANS.
Exclude CICS system transactions by specifying
EXCLUDED_TRANS=C*.
If the list of transactions will not fit on one line,
use additional EXCLUDED_TRANS statements.

156 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 43. Resource Limiting Parameters (continued)
Parameter to use Definition Default
INCLUDED_TRANS Specifies one or more transactions for resource None
limiting. This can be the actual 1- to 4-character
transaction ID(s) or a generic specification using
wildcard characters. You can use the question
mark (?) wildcard character for single-character
substitution and the asterisk character (*) as a
trailing character only.
The following are examples of wildcarding:

INCLUDED_TRANS=(ABCD,E*)

Selects the ABCD transaction(s) and all

transaction IDs that begin with E

INCLUDED_TRANS=F?

Selects all 2-character transaction IDs where the

first character is F.

INCLUDED_TRANS=G??H

Selects all 4-character transaction IDs starting

with G and ending with H.
Non-displayable transaction IDs are specified as
follows:

#PAnPA keys (n = 1-3).

#FnnPF keys (nn = 01-36).
#LPALight pen attention.
#MAGMagnetic stripe reader.
#OCDOperator ID card

Note: If INCLUDED_TRANS is specified, either

KILL_LIMIT or WARN_LIMIT (or both) must also
be specified. See below for information on these
parameters.
If the list of transactions will not fit on one line,
use additional INCLUDED_TRANS statements.

KILL_LIMIT Specifies a threshold for limiting resource usage. None

Transactions that exceed this value are abended.
Thresholds can be set at the following values:

Resource Threshold
CPU and ELAPSED 1-32768 seconds
DSA 1-9999999 bytes
EDSA 1-999999999 bytes
File and DataBase 1-99999999 number
of requests
GDSA and CONTAINR 1-99999999 kilobytes

Chapter 5. Reference 157

 Table 43. Resource Limiting Parameters (continued)
Parameter to use Definition Default
WARN_LIMIT Specifies a threshold for limiting resource usage. None
OMEGAMON for CICS issues a warning message
for transactions that exceed this value. The value
must be lower than the KILL_LIMIT if specified.

A transaction executing under CEDF is not abended. Instead, a message is issued to the terminal and the
transaction continues normal execution. OMEGAMON for CICS writes messages, issued as a result of KILL
or WARN action, to the CICS Transient Data Queue (ID of CSSL, dataset MSGUSR) or via a WTO.
Transaction selection tips:
Since you might have some overlap in transaction codes if you use both EXCLUDED_TRANS and
INCLUDED_TRANS with wildcarding, OMEGAMON for CICS selects a transaction for resource limiting as
follows:
• If you do not specify the INCLUDED_TRANS operand or if you specify the INCLUDED_TRANS operand
that matches a specification in the list, OMEGAMON for CICS selects the transaction. If a transaction
ID qualifies for resource limiting under more than one rule, the most specific INCLUDED_TRANS
specification is used. For example:

Rule 1: Rule 2:
------------------- -------------------
<<DB2>> <<DB2>>
INCLUDED_TRANS=TST* INCLUDED_TRANS=TST1
KILL_LIMIT=100 KILL_LIMIT=50
WARN_LIMIT=80 WARN_LIMIT=40

When transaction TST1 executes, the limits attached to Rule 2 apply. To exclude a transaction from a
resource list, the EXCLUDED_TRANS specification must be at least as specific as the INCLUDED_TRANS
specification under which it applies for that resource limit. For example:

Rule 1: Rule 2:
------------------- -------------------
<<DB2>> <<DB2>>
INCLUDED_TRANS=TST1 EXCLUDED_TRANS=T*
KILL_LIMIT=100
WARN_LIMIT=80

When transaction TST1 executes, it will be subject to the resource limit because INCLUDED_TRANS=TST1
is more specific than EXCLUDED_TRANS=T*. If, however:

Rule 1: Rule 2:
------------------- -------------------
<<DB2>> <<DB2>>
INCLUDED_TRANS=TST* EXCLUDED_TRANS=TST1
KILL_LIMIT=100
WARN_LIMIT=80

Then transaction TST1 will be excluded from the resource limit.

RLIM versus ICVR tips:
The ICVR parameter, available through CICS, and the RLIM CPU option, available through OMEGAMON for
CICS, serve two separate functions:
1. The ICVR value allows you to set an upper limit for the amount of CPU time that a task may consume
within a single dispatch.
2. The RLIM CPU limit allows you to set an upper limit on the total amount of CPU time that a task may
consume across multiple dispatches.
You may consider RLIM and ICVR to be complementary tools you can use to prevent a task from
monopolizing the CPU.

158 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

When determining whether or not a task should be abended due to excessive CPU consumption, RLIM
compares the value in USRCPUT, DFHTASK_008 in the Transaction Monitoring Area, with the CPU limit
specified in the appropriate global data area module, KC2GLBnn.
The CICS Monitoring Facility updates the value in USRCPUT when a task issues a CICS command that
suspends the task and causes the dispatcher to be invoked. RLIM CPU usage checking is performed
whenever an EXEC CICS request is issued. Additionally, if you have installed support for a third-party
database product and are collecting clock and counter statistics for that database type, a request issued
to the database will cause the task's CPU usage to be checked.
Certain CICS commands usually do not drive the dispatcher and therefore the USRCPUT value may not be
incremented. Consequently, RLIM probably will not abend any task that only issues one or more of these
commands in a loop. The commands that rarely drive the dispatcher are:
• ASKTIME
• HANDLE
• ENQ
• DEQ
• FREEMAIN
• RELEASE
• TRACE ON/OFF
• XCTL
In addition, a READ request that can be satisfied from the buffer, as opposed to requiring physical I/O,
does not invoke the dispatcher. Other CICS commands may invoke the dispatcher, but only if the request
cannot be satisfied immediately and the task is suspended. Therefore, an application that, for instance,
repeatedly issues a GETMAIN and FREEMAIN for a small area may not give up control. In such a situation,
the task's CPU time value will not be updated and RLIM will not abend the task (see "External task
resource limiting," below). Conversely, because the USRCPUT value is updated only at the end of each
dispatch, the CICS runaway-task mechanism, controlled by the ICVR parameter in the SIT, does not use
it. To determine whether or not to abend the task, CICS refers to a timer that is reset each time the task is
redispatched. While dispatched, CICS decrements the timer at regular intervals. If the timer reaches zero,
the task is abended with code AICA.

External task resource limiting

When RESOURCE_LIMITING_MSG_DEST is specified as "LOG" or "TDL," RLIM runs an additional program
each second which monitors active tasks and, if needed, takes action against a task. This is done only if
limits were specified for resource types "CPU" or "ELAPSED" and is intended to handle tasks that are in
a long wait or actively using CPU but not issuing EXEC CICS requests. Message KCP8906I is issued and
serves as a notification that the task has exceeded the threshold even though RLIM cannot ABEND it. You
may use this message to automate actions to notify operators that external action may be required.

Resource Limiting Interval

The RESOURCE_LIMITING_INTERVAL specifies at what interval resource limiting should process user
defined rules. Once RLIM is active, the interval settings apply to all resources and their respective rules,
hence a global implication. There are two ways to specify an interval. Either, specify a TIME_INTERVAL or
specify EXEC_CALLS and/or DB_CALLS.
The values in the following tables can be used.

Chapter 5. Reference 159

 Table 44. Resource limiting interval information
Parameter to use Definition Default
TIME_INTERVAL Defines the amount of time, in units of seconds, which 0
must pass before existing resource limits or rules
could be processed. Default value of zero seconds
implies that RLIM processing will not be based on
time interval. Maximum allowable value is one week
or 604800 seconds.
EXEC_CALLS Defines the number of EXEC CICS commands which 0
must be issued by the application program before
existing resource limits or rules could be processed.
Default value of zero implies that RLIM processing will
not be based on the number of EXEC calls. Maximum
allowable value is 99999999.
DB_CALLS Defines the number of DataBase commands or EXEC 0
CICS SQL commands which must be issued by the
application program before existing resource limits
or rules could be processed. Default value of zero
implies that RLIM processing will not be based on
the number of DataBase or EXEC CICS SQL calls.
Maximum allowable value is 99999999.

Note: The default value of zero for all settings implies that RLIM processes the rules or limits, according
to their definition, on every invocation. By the same token, when an interval(s) is set the processing of
defined limits or rules only occurs within that interval.
Only those transactions which are started after the intervals were last refreshed, are eligible for
processing.

Response Time collection

The RESPONSE_TIME_COLLECTION value specifies the time intervals for the response time collector.
The values in the following table can be used.

Table 45. Response time collection information

Parameter to use Definition Default
TIME_INTERVALS Specifies the time intervals for the Average (5,10,30)
Response Times display. You must enter three
values:

short,mid,long

These are the three intervals for reporting RTA

data. In order to roll the values from one interval
to the other, OMEGAMON for CICS requires that
"long" be an integer multiple of "mid" and that
"mid" be an integer multiple of "short". The
values are in minutes within the range 1-999.

160 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 45. Response time collection information (continued)
Parameter to use Definition Default
EXCLUDED_TRANS Specifies transactions to exclude from analysis. None
The list of transactions is limited to 63
transaction IDs. Transactions that start before
phase 3 of the PLTPI or end after phase 1 of
the PLTSD are not excluded. Any CICS-generated
transactions that initiate without going through
TRUE processing are not excluded either.
The exclude list may contain the actual 1-
to 4-character transaction ID(s) or a generic
specification using wildcard characters. You can
use the question mark (?) wildcard character
for single-character substitution and the asterisk
character (*) as a trailing character only.
The following are examples of wildcarding:

EXCLUDED_TRANS=(ABCD,E*)

Excludes the ABCD transaction(s) and all

transaction IDs that begin with E.

EXCLUDED_TRANS=F?

Excludes all 2-character transaction IDs where

the first character is F.

EXCLUDED_TRANS=G??H

Excludes all 4-character transaction IDs starting

with G and ending with H.
Note: If a transaction is matched in the
EXCLUDED_TRANS list, OMEGAMON for CICS
excludes it from analysis, whether or not it
matches a GROUP_ELEMENTS component on
either terminal ID, program, transaction ID, LU
name, or TASKREQ.
If the list of transactions will not fit on one line,
use additional EXCLUDED_TRANS statements.

Chapter 5. Reference 161

 Table 45. Response time collection information (continued)
Parameter to use Definition Default
TIME_SLOT Specifies the time slot definitions (1-48 slots) for 0000,0800
the Today's Response Times display. It specifies 0800,0900
0900,1000
the start time (first entry) and end time (second 1000,1100
entry) of the slot. Enter the values in 24-hour 1100,1200
clock format using this syntax: 1200,1300
1300,1400
1400,1500
(hhmm,hhmm) 1500,1600
1600,1700
1700,2400
Where hh (hours) is a 2-digit number from 00
through 24 and mm (minutes) is a 2-digit number
from 00 through 59.
At least one slot must be defined; if more
than one slot is defined, the slots must be in
ascending order. The ending time value on one
slot may be the same as the beginning time
value on the next slot, but overlaps are not
allowed. (A shared minute is not an overlap.)
The default RTA TIME_SLOTs daily configuration
is one slot from 0000 to 0800, then contiguous
hourly slots until 1700, and one more slot from
1700 to 2400.

Dedicated Sessions
The DEDICATED_SESSIONS values define terminals for OMEGAMON for CICS dedicated mode sessions.
The values in the following tables can be used.

Table 46. Dedicated sessions information

Parameter to use Definition Default
UNIT Specifies the beginning of information for an None
external monitoring session. It is followed by the
other operands defining a session.
UNIT_ADDRESS Specifies the device address of the terminal. None
PHYSICAL_ROWS Specifies the number of physical rows (1-999) 24
on the terminal.
LOGICAL_ROWS Specifies the number of logical rows (1-999). 99
COLUMNS Specifies the number of columns (80, 132, or 80
160) on the terminal.
USER_PROFILE Specifies the user profile suffix (any two None
characters). Any session of OMEGAMON for
CICS can use a different profile by specifying a
different two-character suffix.

Service Level Analysis

The SERVICE_LEVEL_ANALYSIS value controls whether data will be written to the Service Level Analysis
subtask running in the CICS agent address space.
The value in the following tables can be used.

162 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 47. Service level analysis information
Parameter to use Definition Default
INCLUDE_REGION Specifies whether performance data collected by YES
OMEGAMON is sent to the SLA summarization
routines running in the OMEGAMON for CICS
agent address space and displayed in the Service
Level Analysis reports.
Possible values are:
YES
Performance data collected by OMEGAMON
is sent to the SLA summarization routines
running in the OMEGAMON for CICS agent
address space. Data for regions that use this
global data area is displayed in the Service
Level Analysis reports.
NO
Performance data collected by OMEGAMON
is not sent to the SLA summarization routines
running in the OMEGAMON for CICS agent
address space. Data for regions which use
this global data area is not displayed in the
Service Level Analysis reports.

Enabling outbound API request monitoring

The OUTBOUND_API_REQUEST_MONITORING parameter, AGGREGATE, controls whether file level
monitoring will be enabled, to collect data for outbound API request monitoring. The following table
gives the values that can be used.

Table 48. Outbound API Request Monitoring

Parameter to use Definition Default
AGGREGATE Specifies whether file level collection for NOAUTO
outbound API request monitoring is enabled.
AUTO
Start file level collection automatically.
NOAUTO
Do not start file level collection
automatically.

TRUE Monitoring
The TRUE_MONITORING values control whether data for Task Related User Exits (TRUE) will be collected,
written to task history, and written to SMF so that the data can be processed offline by utilities such as
IBM CICS Performance Analyzer.

Table 49. TRUE Monitoring information

Parameter to use Definition Default
ENABLE Specifies whether TRUE Monitoring is enabled. NOAUTO
AUTO: Start TRUE Monitoring automatically.
NOAUTO: Do not start TRUE Monitoring
automatically.

Chapter 5. Reference 163

 Table 49. TRUE Monitoring information (continued)
Parameter to use Definition Default
WRITE_TO_HISTORY This option will record the collected data for YES
a task to Task History. This tab will provide
information about all TRUEs used during the
time covered by the history record.
SMF This option will record the collected information NO
to SMF. The data can then be processed offline
by utilities such as IBM CICS Performance
Analyzer.

Refreshing the monitoring options

OMEGAMON for CICS uses the Global Data Area to load the information into z/OS storage in the
OMEGAMON for CICS (3270) interface address space on behalf of a monitored CICS region.
Each region that OMEGAMON for CICS monitors is represented by its own unique copy of the Global Data
Area in the address space. This is true even if you defined only one module for monitoring multiple CICS
regions. Each one of those regions has a separate, unique copy loaded for it at the time OMEGAMON for
CICS prepares to monitor it.
You can change the contents of a Global Data Area without stopping your CICS regions by creating a new
Global while the old one is being used.
You can delete a region's Global Data Area copy from storage for OMEGAMON for CICS (3270) and replace
it with your updated version by performing any one of the following:
• Stop the OMEGAMON for CICS collector address space and restart it.
• Stop the CICS address space and restart it.
• Stop OMEGAMON for CICS from monitoring the target CICS while the CICS address space continues
running normally.
To stop OMEGAMON for CICS monitoring, perform all of the following steps:
1. If KOCOME00 was run at the CICS PLTPI time or if the OMEG INIT command was issued in the CICS
region, issue the OMEG REMOVE command to reverse the process.
2. Stop task history collection, internal bottleneck collection, interval recording, and response time
collection for the target CICS region.
3. End all OMEGAMON for CICS sessions monitoring the target CICS region, including dedicated sessions.
When this procedure is completed, OMEGAMON for CICS deletes the Global Data Area copy used by
the target CICS region.
4. After completing the procedure, issue a new OMEG INIT command in the CICS address space to use
the new Global Data Area.
Note: Recycling the global module will only affect transactions started after the global module has been
recycled.

Additional Considerations
The following tables list CICS global exit names supported by EXIT_SUPPRESSION, the data gathered,
CMF performance monitoring possibilities, and OMEG INIT processing implications.

OMEG INIT processing for CICS_CMF_MONITORING

CICS_CMF_MONITOR is subordinate to the user-defined CMF environment. If you specify
CICS_CMF_MONITOR=NO at PLTPI time or in OMEG INIT processing, OMEGAMON for CICS takes action
depending on the state of CMF monitoring.

164 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

The following table describes the contingencies.

Table 50. OMEG INIT processing scenarios

If CMF monitoring
is . . . Then Tivoli OMEGAMON. . . And . . .
Not active Allows it to remain off The XMNOUT exit activation is bypassed.
Active Determines whether CMF • If performance class data gathering is
performance class data active, OMEGAMON activates the XMNOUT
gathering is active. exit so that CMF monitoring can use the data
CICS is already gathering.
• If performance class data gathering
is inactive, OMEGAMON allows CMF
monitoring to remain inactive and bypasses
the XMNOUT exit.

CMF monitoring possibilities

Several settings affect the monitoring and writing of CMF performance data:
• CMF performance monitoring parameters in your SIT (MN and MNPER SIT operands)
• CICS_CMF_WRITE in USER_EVENT_MONITORING (YES or NO)
• CICS_CMF_MONITORING in USER_EVENT_MONITORING (YES or NO)
• CEMT SET MONITOR command (ON or OFF)
The following three tables illustrate the interaction of these factors:
• The Table 51 on page 165 table shows the eight possible combinations of settings before initialization.
• TheTable 52 on page 166 table shows what happens after you run the OMEG INIT transaction to start
OMEGAMON for CICS. The first column indicates whether or not data is written to SMF. The second
column indicates whether or not data will be available to ONDV and RTA.
• The Table 53 on page 166table shows what happens if you run CEMT SET MONITOR ON after
OMEGAMON for CICS has been started.
To determine how performance data will be handled with your current option settings, find the row in
the first table that contains your settings before initialization. Then, check the corresponding row in the
second and third tables.
The following tables describes the contingencies.

Table 51. Settings Before Initialization

CMF Perf. Monitoring SMFCICS3 MONITOR
OFF NO NO
OFF NO YES
OFF YES NO
OFF YES YES
ON NO NO
ON NO YES
ON YES NO
ON YES YES

Chapter 5. Reference 165

 Table 52. After OMEG INIT
SMF Write ONDV/RTA Get Data Comments
NO NO
NO YES CMF turned on, XMNOUT
activated.
NO NO
YES YES CMF turned on. XMNOUT
activated.
YES NO SMFCICS=NO
NO YES
YES NO
YES YES CICS and OMEGAMON for CICS
write to SMF. All OMEGAMON
for CICS data collected. XMNOUT
activated.

Table 53. After CEMT SET MONITOR PERF ON

SMF Write ONDV/RTA Get Data Comments
YES NO XMNOUT is OFF.
N/A N/A Monitoring is already ON.
YES NO XMNOUT is OFF.
N/A N/A Monitoring is already ON.
N/A N/A Monitoring is already ON.
N/A N/A Monitoring is already ON.
N/A N/A Monitoring is already ON.
N/A N/A Monitoring is already ON.

SAS historical reporting

This section describes how SAS supplements the existing historical reporter feature of OMEGAMON for
CICS component.
This implementation provides the following:
• An alternative reporting mechanism
• Sample SAS reports that you might adapt to local requirements
• A means to generate one-off reports without you having in-depth knowledge of SAS
• A means to generate response time group definitions that you can imbed into your global data area
module (GLOBAL_OPTIONS).

Using the SAS historical reporter

Use the SAS historical reporter to accomplish the following tasks:
• Allocating a sequential SAS DETAIL data set that contains a complete day's worth of collected data

166 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 • Allocating a sequential SAS DAILY dataset that contains 31 days of summarized, aged information from
the DETAIL data set
• Using a Generalized Report Writer to produce custom reports on any collected data
• Using the Response Time Transaction Group Build program to analyze the collected SAS data and build
response time group parameter entries. You can then insert these parameters into the OMEGAMON for
CICS global data area module (GLOBAL_OPTIONS).

Overview of the SAS historical reporting process

To collect performance data, SMF recording must be enabled for OMEGAMON for CICS. You can enable
SMF recording during product customization.
Table 54 on page 167 shows the steps in the SAS historical reporting process, from OMEGAMON for CICS
data collection to SAS report creation.

Table 54. Steps in the SAS historical reporting process

Stage Description
1 OMEGAMON for CICS collects performance data using additional event monitoring
points defined in the MCT and clocks and counters information defined in the
GLOBAL_OPTIONS module. CICS or OMEGAMON for CICS writes performance data
as SMF 110 records and, optionally, clocks and counters information as SMF user
records.
2 SAS creates a DETAIL data set and, using job KC2SMFJ, populates it with collected
SMF data.
3 SAS uses data in the SAS DETAIL data set (through job KC2REPTJ) to generate the
supplied reports and charts (KC2TRPn and KC2TCHn).
4 You can generate user-defined reports by using the supplied Generalized Report
Writer job KC2GRWJ.
5 You can generate response time group definitions by using the supplied transaction
group build job KC2TRXJ.
6 At the end of the day, SAS summarizes the DETAIL data set to the DAILY data set and
archives the DETAIL data set to cartridge (through job KC2DLYJ) for post processing
purposes.
7 SAS uses data in the SAS DAILY data set (through job KC2REPTJ) to generate the
supplied reports and charts (KC2DRPn and KC2DCHn).
8 Ad hoc reports may be produced directly from the SMF data set using job KC2ADHCJ.

Preparing to run the sample SAS reports

This section provides the steps you follow to prepare to run the sample SAS supplied reports.
The preparatory steps are as follows:
1. Create and populate the SAS runtime JCL and macro libraries.
2. Allocate the sequential SAS data sets.
3. Customize SAS macros.
4. Run the daily collection jobs to populate the SAS DETAIL and DAILY data sets.
For details on these steps, see:
• “Installation procedures” on page 168
• “Customization procedures” on page 168
• “Running the daily collection jobs” on page 169

Chapter 5. Reference 167

 Location of the SAS code
All the SAS code described in this section is distributed through the OMEGAMON for CICS hilev.TKANSAM
target library.

Installation procedures
The following sections describe the installation procedures that you perform. Perform the installation only
once.

Create and populate the SAS runtime JCL and macro libraries
To allocate and populate the SAS system files, edit and submit the JCL in the TKANSAM library member,
KC2SASJB. The IEBGENER job allocates these PDS files, KC2SJCL and KC2SPROS, and copies specific
members into them from the TKANSAM library. The purpose of these files is as follows:
KC2SJCL
Contains JCL procedures to allocate and maintain the SAS database and run the sample SAS reports.
KC2SPROG
Contains SAS system macros and the sample programs.
Important: Any further customization that you perform should be done on the members in the KC2SJCL
and KC2SPROG PDS files. Do not make changes directly to members in the TKANSAM library because it is
an SMP/E library that could change due to maintenance.

Allocate the sequential SAS data sets, DETAIL and DAILY

To create the DETAIL and DAILY SAS data sets, edit and submit the supplied job KC2ALOCJ, located in the
KC2SJCL data set. SAS requires that a standard sequential data set be allocated for use as the repository
for all the data collected from OMEGAMON for CICS. The purpose of these data sets is as follows:
• The DETAIL data set contains one or two data files:
– The CICSTRAN data file consisting of one record for each logical SMF 110 record; that is, one per
CICS transaction. This information is gathered daily from the SMF data sets. Each stored record is
approximately 2259 bytes.
– An optional DBD data file that contains database clocks and counters information for each
transaction collecting DBCOL information from the global data area (GLOBAL_OPTIONS). Each stored
record is approximately 76 bytes.
• The optional DAILY data set comprises data files (one per day) that contain summarized information
gathered from the DETAIL data set and aged over a number of days. As supplied, 31 days of information
is retained. Each stored record is approximately 824 bytes. If you do not want to produce summarized
data, do not create the DAILY data set.

Customization procedures
This section describes the customization procedures you can perform. Perform customization only once.

Customizing SAS macros and programs

Review and customize the following SAS macro members in the order indicated. These members are
located in the KC2SPROG data set. Follow these steps to customize the SAS macros and programs:
1. Customize KC2GRP and KC2GRF with group definitions and names.
KC2GRP allows you to group transactions for reporting purposes. Transactions defined in Group 0 are
overhead transactions and can be excluded from any report. The sample KC2GRP member contains
entries for some sample groups. KC2GRF defines names for the groups created in the KC2GRP macro.
2. Customize KC2CMPY with your company name. This name appears in the title of all reports produced.
3. Customize KC2SHFT with shift times if you want reporting by shift; otherwise, skip this step.

168 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 The default shifts are 8 a.m. to 5 p.m. (day shift), 5 p.m. to midnight (evening shift), and midnight to 8
a.m. (night shift).
4. Customize KC2WEEK to define the first day of the week at your site.
The default first day of the week is Sunday.
5. Review SAS macros for SMF record mappings. These mappings are equivalent to complete SMF 110
records; no fields have been excluded.
KC2V640
Provides the mapping of the CICS-produced SMF 110 record for CICS Transaction Server V3.1
(CICS Version 6.4.0).
KC2V650
Provides the mapping of the CICS-produced SMF 110 record for CICS Transaction Server V3.2
(CICS Version 6.5.0).
KC2V660
Provides the mapping of the CICS-produced SMF 110 record for CICS Transaction Server V4.1
(CICS Version 6.6.0).
KC2V670
Provides the mapping of the CICS-produced SMF 110 record for CICS Transaction Server V4.2
(CICS Version 6.7.0).
If you exclude fields from the Monitoring Control Table (MCT), you must modify the SMF 110 mapping
accordingly. To do so, create a new member name, then copy to it the appropriate mapping that
corresponds to the CICS release. You should then comment out redundant fields that were excluded.
If you use CICS Version 3.x and higher, the KC2DICTJ job is supplied to print the dictionary records.
The KC2DICTJ job reads and reports the structure of the dictionary record and assists you in
determining the format of your SMF 110 records.
6. If user-defined mappings are created as a result of the previous step, review and customize KC2PICK
to invoke the new mapping. The SAS code located in KC2PICK demonstrates how to select a specific
mapping according to the CICS release or applid.
Note: SMF 110 record layouts differ across CICS releases. You might have different SMF mappings for
CICS systems at the same release level due to MCT field exclusions. The main SMF converter program,
KC2SMFR, invokes KC2PICK to determine which SMF 110 mapping to use. The actual SMF mappings
are retained in separate members.
7. Review KC2BSC.
This SAS macro, used within the SMF converter program KC2SMFR, provides a mapping of the 132-
byte OMEGBSC EMP that is supplied. If you have excluded fields from the default supplied OMEGBSC,
you must modify this member accordingly. Be sure you specify the length of the customized OMEGBSC
correctly.
You can control the size of the OMEGBSC data area. The sample KC2BSC member demonstrates
how to select a specific mapping according to the CICS applid. The sample shows how to define a
mapping to be used by a CICS system, ”NODBCICS," that excludes the eight 4-byte database clocks
and counters fields. This exclusion reduces the size of the OMEGBSC from 132 bytes – 100 bytes. All
other CICS systems use the standard 132-byte supplied definition. This accommodates those users
who may have customized their OMEGBSC EMP differently for separate CICS systems.

Running the daily collection jobs

The last steps that you perform before you run the sample SAS reports are to populate the DETAIL and
DAILY data sets.

Populating the DETAIL data set

See Stage 2 of Table 54 on page 167.

Chapter 5. Reference 169

 To extract the SMF records, customize and run the supplied job, KC2SMFJ, located in the KC2SJCL data
set. You can run this job periodically during the day to populate the SAS DETAIL data set. By the end of the
day the DETAIL data set contains the full day's worth of SMF CICS data. Alternatively, if you already have
procedures in place to gather daily SMF data into one single data set, you can run this job just once at the
end of the day.
The supplied job, KC2SMFJ does the following:
• The IFASMFDP program supplied by IBM is run to unload the SMF data to a sequential data set; it
extracts SMF 110 and 112 records
• The SAS program, KC2SMFR, located in the KC2SPROG data set, is run to create a temporary SAS data
set using the input from the previous list item. (see Using the KC2SMFR converter program in the next
section).
• Runs a SAS procedure to append the temporary data set created in the KC2SMFR program to the
DETAIL data set.

Using the KC2SMFR converter program

KC2SMFR is the SAS SMF converter program that decodes the SMF 110 records and, optionally, the SMF
112 records. This program creates the SAS data files CICSTRAN and DBD on the DETAIL data set. The
CICSTRAN and DBD data files created by KC2SMFR contain fields for all the current releases of CICS.
The KC2SMFR converter program provides the following parameters:
TRAN=YES,NO
Determines whether the CICSTRAN datafile is generated. YES is the default setting.
DBD=NO,YES
Determines whether the DBD data file that contains clocks and counters information is generated. NO
is the default setting.
DBSMF=255,nnn
Specifies the SMF user record containing clocks and counters information. 255 is the default value.
CICS= ALL,xxxxxxxx
Determines whether SMF records relating to all or a specific or generic CICS applid are processed. For
example, CICS=PROD restricts processing to all CICS applids beginning with PROD. Alternatively, you
can specify CICS=ALL and use the EXIT= option to accommodate more specific processing. ALL is
the default setting.
C2SMF=110,nnn
Allows you to specify the same user record number that you specified in the SMFCICS2 parameter
of the USER_EVENT_MONITORING parameter (located in GLOBAL_OPTIONS) for the OMEGAMON for
CICS generated subset of the SMF type 110 record. 110 is the default setting.
DBSMF=112,nnn
Allows you to specify the same user record number that you specified in the SMFCICS2 parameter
of the USER_EVENT_MONITORING parameter (located in GLOBAL_OPTIONS) for the OMEGAMON for
CICS generated subset of the SMF type 112 record. 112 is the default setting.
GMTOFF=99,nn
A value of 99 signifies that the GMT offset in the OMEGBSC should be applied. You can specify an
override containing the actual GMT offset; for example, GMTOFF=+8, as not all transactions have an
OMEGBSC segment. An example is transactions that started before OMEGAMON for CICS component
is initialized. 99 is the default setting.
UMB=YES,NO
When set to YES, this parameter specifies that if the umbrella program and transaction ID are present,
they are used in preference to the actual CICS program and transaction ID. YES is the default setting.
EXIT=NO,xxxxxxxx
Specifies the name of a user-written exit program that allows greater selection criteria. For example,
to limit the size of the DETAIL file, you may omit specific transactions. The default setting is NO. This

170 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 is an example of the kind of program you would write to exclude records for a particular region and
exclude all CICS transactions:

IF SMFMNPRN = “PRODACCT” THEN DELETE; /*drop records for this region*/ IF

TRAN =: “C” THEN DELETE; /*and drop ‘CICS' trans */

DBDEXIT=NO,xxxxxxxx
Specifies the name of a user-written exit program to be applied to the DBD component of the DETAIL
file. NO is the default setting.
STOP=NO,nnn W.
When set to a numeric value, restricts processing to a specified number of input records for debugging
purposes. NO is the default setting.
DEBUG=NO,YES
When set to YES, this parameter switches debugging on. NO is the default setting.

Running the DETAIL reports and charts

See Stage 3 of Table 54 on page 167.
After the DETAIL data set is populated, you can run DETAIL reports and charts against this data set using
the KC2REPTJ job, located in the KC2SJCL data set. KC2REPTJ executes the SAS procedure that specifies
which of the supplied reports to produce (reports from both the DETAIL and DAILY data sets can be
produced by this job).

//STEP01 EXEC SASxxx,SASAUTO=&OHILEV.KC2SPROG,

// OPTIONS=&apos;MACRO MAUTOSOURCE S=72 S2=72 DQUOTE&apos;
//DETAIL DD DISP=SHR,DSN=&OHILEV.SAS.DETAIL
//DAILY DD DISP=SHR,DSN=&OHILEV.SAS.DAILY
//****************************************************************
// PLACE YOUR REPORT OPTIONS AFTER THE SYSIN STATEMENT ALONG WITH*
// ANY ADDITIONAL KEYWORD SELECTION CRITERIA. *
//****************************************************************
//SYSIN DD *
%KC2TRP1;
%KC2TRP2;
%KC2TRP3 (EXIT=MYEXIT); /* ONLY REPORT ON ABENDED */
/* TRANSACTIONS VIA AN EXIT */
%KC2TCH1;
%KC2DRP7 (DAILYLO=1,DAILYHI=7,SUMBY=WEEK);
%KC2DCH5 (DAILYLO=1,DAILYHI=7);
//MYEXIT DD *
IF ABCODEO =: “00”X THEN DELETE; /* DROP TRANS THAT HAVEN&apos;T ABENDED
*/

Figure 14. Example of the JCL you enter to specify the DETAIL and DAILY reports

Populating the DAILY data set

See Stage 6 of Table 54 on page 167.
Customize and run the supplied job KC2DLYJ, located in the KC2SJCL data set. This job does the
following:
1. Invokes the KC2SUMD program, located in the KC2SPROG data set, which takes as input the DETAIL
data set and summarizes its contents into the DAILY data set. The DAILY data set is aged over a
user-defined period (the default aging period is 31 days).
2. Runs a SAS procedure to copy the contents of the DETAIL dataset to a cartridge for archiving. You can
produce DETAIL reports directly from this cartridge.
3. Reallocates the DETAIL data set to make it available for the next day's processing.
You can run this job at the end of the day. You can then either produce reports from an archived copy of
the DETAIL data set or produce reports directly from the DAILY data set.

Chapter 5. Reference 171

 Using the KC2SUMD program
KC2SUMD is the SAS code that summarizes and ages the contents of the DAILY data set from the DETAIL
data set. Transaction data is summarized by region name, month, week, day, hour, userid, LU name, and
transaction ID. The DAILY data set occupies significantly less space than the DETAIL data set and allows
long-term summary reports to be produced.
The KC2SUMD program provides the following parameters:
DAYS=31,nn
The number of days of data to retain in the DAILY data set. This assumes that KC2SUMD is run daily.
You can determine your own requirements, bearing in mind the overall DASD storage requirements.
31 is the default setting.
EXIT=NO,xxxxxxxx
Specifies the name of a user-written exit program to allow greater selection criteria. NO is the default
setting.
STOP=NO,nnn
When set to a numeric value, this parameter restricts processing to a specified number of input
records for debugging purposes. NO is the default setting.
DEBUG=NO,YES
When set to YES, this parameter switches debugging on. NO is the default setting.
The KC2SUMD program does not summarize every field found in the DETAIL data set.

The DETAIL data set archive

Once summarizing and aging have occurred, the DETAIL data set is archived automatically and cleared,
ready for the next day's propagation phase. After the DETAIL data set has been cleared, you cannot report
against it directly. You can, however, report directly against the archived copy using the KC2REPTJ job. In
your JCL, just indicate the cartridge that contains the data set.

Running the DAILY reports and charts

See Stage 7 of Table 54 on page 167.
After summarizing and aging have occurred to populate the DAILY data set, you can produce reports on
the DAILY file by using the KC2REPTJ job, located in the KC2SJCL data set. KC2REPTJ executes the SAS
procedure that specifies the supplied reports to produce (reports from both the DETAIL and DAILY data
sets can be produced by this job).

Producing reports directly from SMF data

See Stage 8 of Table 54 on page 167.
The job KC2ADHCJ, located in the KC2SJCL data set, allows you to produce reports without creating a
permanent DETAIL data set. You can produce ad hoc reports directly from the unloaded SMF data, and
can specify any number of reports.
The KC2ADHCJ job performs the following tasks:
• Runs the IFASMFDP program supplied by IBM to unload the SMF data to a sequential data set.
• Runs KC2SMFR, located in the KC2SPROG data set, to create a temporary SAS data set that uses the
input from the IFASMFDP program.
In the following JCL, you can add report statements to the SYSIN DD statement following KC2SMFR.

172 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 For example, you could enter:

//DETAIL EXEC SASxxx,SASAUTO=&OHILEV..KC2SPROG,

OPTIONS='MACRO MAUTOSOURCE S=72 S2=72 DQUOTE'
//DETAIL DD DISP=(,PASS),DSN=&DETAIL,UNIT=SYSDA,
// SPACE=(CYL,(50,10))
//SMF DD DISP=OLD,DSN=&&SMF
//SYSIN DD *
/*THE FOLLOWING STATEMENT READS IN SMF DATA FROM THE SMF DD */
/*AND WRITES THE SAS DATA TO THE DETAIL DD Temporary dataset
/ %KC2SMFR (CICS=ALL,GMTOFF=+8,DBD=YES,DBSMF=112);
/* ENTER THE REPORTS YOU WISH TO PRODUCE. */
%KC2TRP1;
%KC2TRP2;
%KC2TRP3;
/*

Figure 15. Example of the JCL to use when you want to add report statements to the SYSIN DD statement

Producing reports from the SAS DETAIL data set

This section describes the sample SAS reports you can produce from the SAS DETAIL data set. Report
programs KC2TRxx and charts KC2TCHx are provided as samples.

Running the sample SAS reports

To run the supplied sample SAS reports, do one of the following:
• Customize and run the supplied KC2REPTJ job, located in the KC2SJCL data set, at any time. This job
runs the sample SAS reports on either the current SAS DETAIL data set (or its archived copy) or the
summarized DAILY data set.
• Customize and run the supplied KC2ADHCJ job at any time to report directly against the SMF data set.

Parameters for the DETAIL reports and charts

The following parameters are available to the DETAIL sample reports TRP1 through TRnn and charts
TCH1 through TCHnn.
These are parameters for the DETAIL reports and charts:
DAILYHI=DAILYLO value,nn
Determines the highest (oldest) daily file to be used. DAILYLO and DAILYHI determine the range of
history data to be reported. If you enter only DAILYLO, DAILYHI assumes that same value. If you enter
DAILYLO and inadvertently enter DAILYHI with a less value (error situation), DAILYHI again assumes
the DAILYLO value. DAILYLO is the default setting.
CICS=ALL,xxxxxxxx
Determines whether SMF records relating to all or a specific or generic CICS applid are processed. For
example, CICS=PROD restricts processing to all CICS applids beginning with PROD. Alternatively, you
can specify CICS=ALL and use the EXIT= option to accommodate more specific processing. ALL is
the default setting.
HRLO=00,nn
Determines the start time of data reported. 00 is the default setting.
HRHI=23,nn
Determines the end time of data reported. 23 is the default setting.
LUNAME=ALL,xxxxxxxx
Processes all VTAM LUs and allows you to restrict processing to a specific or generic LUNAME. ALL is
the default setting.
GROUP=ALL,WORKLOAD,nn
Processes transactions that belong to all GROUPS defined in KC2GRP. Allows you to restrict
processing to a specific group of transactions. If you specify GROUP=WORKLOAD, then all transactions
belonging to GROUP 0 are ignored from all processing. ALL is the default setting.

Chapter 5. Reference 173

 SHIFT=ALL,nn
Restricts the selection criteria to a specific shift as defined in KC2SHFT. ALL is the default setting.
SUMBY=DAY,WEEK,MONTH
Determines how a report is summarized. For example, you can create a report by day for 7 days by
specifying DAILYLO=1, DAILYHI=7, SUMBY=DAY, or by week by specifying DAILYLO=1, DAILYHI=7,
SUMBY=WEEK. KC2DCH1, a Response Time Chart by Hour, is summarized by week as follows:

DAILYLO=1,DAILYHI=7,LOTIME=09:00:00,HITIME=12:00:00,SUMBY=WEEK

This would graph the response time distribution for the three hour period over the week. This
parameter is not valid for reports KC2DCH5, KC2DCH6, and KC2DRP7. DAY is the default setting.
TRAN=ALL,xxxx
Restricts the selection criteria to a specific or generic transaction ID. ALL is the default setting.
USERID=ALL,xxxxxxxx
Restricts the selection criteria to a specific or generic userid. ALL is the default setting.
EXIT=NO,xxxxxxxx
Specifies the name of the exit program you write to allow greater selection criteria. NO is the default
setting.
STOP=NO,nnn
When set to a numeric value, restricts processing to a specified number of input records for debugging
purposes. NO is the default setting.
DEBUG=NO,YES
When set to YES, this parameter switches debugging on. NO is the default setting.

DETAIL reports and graph charts

These are the DETAIL reports and graph charts that can be produced:
• KC2TRP1 - Response Time Statistics by Transaction
This report has no additional parameters.
• KC2TRP2 - Response Time Statistics by Interval
This report program provides the following additional parameter. This parameter allows you to override
the default reporting interval.
INTERVAL=60,nn
Defines the reporting interval period in minutes. 60 is the default setting.
• KC2TRP3 - Transaction Detail
This report program provides the following additional parameter. Use this parameter to set a specific
response time threshold.
THRESH=NO,nn
Limits selection to a specific response time threshold in seconds, for example, THRESH=1 or
THRESH=0.5. NO is the default setting.
• KC2TRP4 - Service Level Report by Transaction
This report has no additional parameters.
• KC2TRP5 - Service Level Report by Interval
To override the default reporting interval, this report has the following additional parameter.
INTERVAL=60,nn
Defines the reporting interval period in minutes. 60 is the default setting.
• KC2TRP7 - Response Time Graphs
This report provides the following additional parameters:

174 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 INTERVAL=15,nn
Defines the reporting interval period in minutes. 15 is the default setting.
RPTINT=YES,NO
Specifies whether the Interval Response report is produced. YES is the default setting.
RPTTRAN=YES,NO
Specifies whether the Transaction Response report is produced. YES is the default setting.
RPTLU=YES,NO
Specifies whether the LU Response report is produced. YES is the default setting.
RPTPGM=YES,NO
Specifies whether the Program Response report is produced. YES is the default setting.
These are the graphs that can be produced:
– response time by user-defined interval
– response time by transaction ID
– response time by VTAM LU
– response time by program
• KC2TRP8 - Response Time and VSAM/DB Activity by Transaction
This report has no additional parameters.
• KC2TRP9 - Response Time and VSAM/DB Activity by interval
This report provides the following additional parameter.
INTERVAL=60,nn
Defines the reporting interval period in minutes. 60 is the default setting.
• KC2TRP13 - Response Time Distribution by Transaction
This report has no additional parameters.
• KC2TRP14 - Storage Utilization Statistics
This report has no additional parameters.
• KC2TRP16 - Region Summary
This report has no additional parameters.
• KC2TRP17 - Database/File Response Time Statistics
A report of database/file response time statistics by transaction. To produce this report, clocks and
counters data must have been collected by KC2SMFR using the parameter DBD=YES.
• KC2TCH1 - Chart of average response time by interval parameters
This chart provides the following additional parameters:
INTERVAL=15,nn
Specifies the response time graph interval. 15 is the default setting.
SPLIT=
You can specify the keyword ‘CICSGRP,' if you need it to produce charts by transaction group.
TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=RESPTIME,xxxxxxxx
Although this is by default a response time chart, you may specify another field here; for example,
USRCPUTM, to obtain a chart of User CPU Time. RESPTIME is the default setting.
HDR=AVERAGE RESPONSE TIME,cccc..ccc
Allows a user-defined header to be specified. AVERAGE RESPONSE TIME is the default setting.
SCALE=5,nn,0.n
Determines the maximum scale to use for the graph axis. 5 is the default setting.

Chapter 5. Reference 175

 These are examples of the graphs:
– a response time chart
– chart of average user CPU time
• KC2TCH2 - Average response time by interval parameters
KC2TCH2, which is a chart of average response time by interval within a group, provides the following
additional parameters:
INTERVAL=15,nn
Specifies the response time graph interval. 15 is the default setting.
SPLIT=
You can specify the keyword ‘CICSGRP,' if you need it to produce charts by transaction group.
TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=RESPTIME,xxxxxxxx
Although this is a chart of transaction response time, you may produce a chart using a different
variable. RESPTIME is the default setting.
HDR=AVERAGE RESPONSE TIME,cccc..ccc
Allows a user-defined header to be specified when requesting a different CHARTVAR variable.
AVERAGE RESPONSE TIME is the default setting.
SCALE=5,nn,0.n
Determines the maximum scale to use for the graph axis. 5 is the default setting.
• KC2TCH3 - A chart of total user CPU time by Interval parameters.
This chart provides the following additional parameters:
INTERVAL=15,nn
Specifies the graph interval.
SPLIT=
You can specify the keyword ‘CICSGRP,' if you need it to produce charts by transaction group.
TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=USRCPUTM,xxxxxxxx
Although this is a chart of user CPU time, you may produce a chart using a different variable.
USRCPUTM is the default setting.
HDR=USER CPU TIME,cccc..ccc
Allows a user-defined header to be specified when you are requesting a different CHARTVAR
variable. USER CPU TIME is the default setting.
SCALE=5,nn,0.n
Determines the maximum scale to use for the graph axis. 5 is the default setting.
• KC2TCH4 - Total User CPU Time by Interval within Group parameters
This chart provides the following additional parameters:
INTERVAL=15,nn
Specifies the graph interval.
SPLIT=
You can specify the keyword ‘CICSGRP,' if you need it to produce charts by transaction group.
TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=USRCPUTM,xxxxxxxx
Although this is a chart of user CPU time, you may produce a chart using a different variable.
USRCPUTM is the default setting.

176 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 HDR=USER CPU TIME,cccc..ccc
Allows a user-defined header to be specified when you are requesting a different CHARTVAR
variable. USER CPU TIME is the default setting.
SCALE=5,nn,0.n
Determines the maximum scale to use for the graph axis. 5 is the default setting.

Running the DETAIL reports and charts

See Stage 3 in Table 54 on page 167.
After the DETAIL data set is populated, you can run DETAIL reports and charts against this data set using
the KC2REPTJ job, located in the KC2SJCL data set. KC2REPTJ executes the SAS procedure that specifies
which of the supplied reports to produce (reports from both the DETAIL and DAILY data sets can be
produced by this job).
This is an example of the JCL you enter to specify the DETAIL and DAILY reports:

//STEP01 EXEC SAS608,SASAUTO=&OHILEV.KC2SPROG,

// OPTIONS=&apos;MACRO MAUTOSOURCE S=72 S2=72 DQUOTE&apos;
//DETAIL DD DISP=SHR,DSN=&OHILEV.SAS.DETAIL
//DAILY DD DISP=SHR,DSN=&OHILEV.SAS.DAILY
//****************************************************************
// PLACE YOUR REPORT OPTIONS AFTER THE SYSIN STATEMENT ALONG WITH*
// ANY ADDITIONAL KEYWORD SELECTION CRITERIA. *
//****************************************************************
//SYSIN DD *
%KC2TRP1;
%KC2TRP2;
%KC2TRP3 (EXIT=MYEXIT); /* ONLY REPORT ON ABENDED */
/* TRANSACTIONS VIA AN EXIT */
%KC2TCH1;
%KC2DRP7 (DAILYLO=1,DAILYHI=7,SUMBY=WEEK);
%KC2DCH5 (DAILYLO=1,DAILYHI=7);
//MYEXIT DD *
IF ABCODEO =: “00”X THEN DELETE; /* DROP TRANS THAT HAVEN&apos;T ABENDED
*/

Figure 16. Example of a JCL to enter to specify the DETAIL and DAILY reports

Populating the DAILY data set

See Stage 6 of Table 54 on page 167.
Customize and run the supplied job KC2DLYJ, located in the KC2SJCL data set. This job does the
following:
• Invokes the KC2SUMD program, located in the KC2SPROG data set, which takes as input the DETAIL
data set and summarizes its contents into the DAILY data set. The DAILY data set is aged over a
user-defined period (the default aging period is 31 days).
• Runs a SAS procedure to copy the contents of the DETAIL dataset to a cartridge for archiving. You can
produce DETAIL reports directly from this cartridge.
• Reallocates the DETAIL data set to make it available for the next day's processing.
You can run this job at the end of the day. You can then either produce reports from an archived copy of
the DETAIL data set or produce reports directly from the DAILY dataset.

Using the KC2SUMD program

KC2SUMD is the SAS code that summarizes and ages the contents of the DAILY data set from the DETAIL
data set. Transaction data is summarized by region name, month, week, day, hour, userid, LU name, and
transaction ID. The DAILY data set occupies significantly less space than the DETAIL data set and allows
long-term summary reports to be produced.
The KC2SUMD program provides the following parameters:

Chapter 5. Reference 177

 DAYS=31,nn
The number of days of data to retain in the DAILY data set. This assumes that KC2SUMD is run daily.
You can determine your own requirements, bearing in mind the overall DASD storage requirements.
31 is the default setting.
EXIT=NO,xxxxxxxx
Specifies the name of a user-written exit program to allow greater selection criteria. NO is the default
setting.
STOP=NO,nnn
When set to a numeric value, this parameter restricts processing to a specified number of input
records for debugging purposes. NO is the default setting.
DEBUG=NO,YES
When set to YES, this parameter switches debugging on. NO is the default setting.
The KC2SUMD program does not summarize every field found in the DETAIL data set.

The DETAIL dataset archive

Once summarizing and aging have occurred, the DETAIL data set is archived automatically to cartridge
and cleared, ready for the next day's propagation phase. After the DETAIL data set has been cleared, you
cannot report against it directly. You can, however, report directly against the archived copy using the
KC2REPTJ job. In your JCL, just indicate the cartridge that contains the data set.

Running the DAILY reports and charts

See Stage 7 of Table 54 on page 167.
After summarizing and aging have occurred to populate the DAILY data set, you can produce reports on
the DAILY file by using the KC2REPTJ job, located in the KC2SJCL data set. KC2REPTJ executes the SAS
procedure that specifies the supplied reports to produce (reports from both the DETAIL and DAILY data
sets can be produced by this job).

Producing reports directly from SMF data

See Stage 8 of Table 54 on page 167.
The job KC2ADHCJ, located in the KC2SJCL data set, allows you to produce reports without creating a
permanent DETAIL data set. You can produce ad hoc reports directly from the unloaded SMF data, and
can specify any number of reports.
The KC2ADHCJ job performs the following tasks:
• Runs the IFASMFDP program supplied by IBM to unload the SMF data to a sequential data set.
• Runs KC2SMFR, located in the KC2SPROG data set, to create a temporary SAS data set that uses the
input from the IFASMFDP program.

Producing reports from the SAS DAILY data set

This section describes sample SAS reports produced from the SAS DAILY data set. Report program
KC2DRxx and charts KC2DCHx are provided to run against the summarized SAS DAILY data set.

Running the sample SAS reports against the DAILY data set
To run the supplied sample SAS reports, customize and run the supplied KC2REPTJ job, located in the
KC2SJCL data set, at any time. This job runs the sample SAS reports on either the current SAS DETAIL
data set (or its archived copy) or the summarized DAILY data set.

178 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Parameters for the DAILY reports and charts
The following parameters are available to the DAILY sample reports: DRP1 through DRnn and charts
DCH1 through DCHnn.
These are parameters for the DAILY reports and charts:
DAILYHI=DAILYLO value,nn
Determines the highest (oldest) daily file to be used. DAILYLO and DAILYHI determine the range of
history data to be reported. If you enter only DAILYLO, DAILYHI assumes that same value. If you
enter DAILYLO and inadvertently enter DAILYHI with a less than value (error situation), DAILYHI again
assumes the DAILYLO value. DAILYLO is the default setting.
CICS=ALL,xxxxxxxx
Determines whether SMF records relating to all or a specific or generic CICS applid are processed. For
example, CICS=PROD restricts processing to all CICS applids beginning with PROD. Alternatively, you
can specify CICS=ALL and use the EXIT= option to accommodate more specific processing. ALL is
the default setting.
HRLO=00,nn
Determines the start time of data reported. 00 is the default setting.
HRHI=23,nn
Determines the end time of data reported. 23 is the default setting.
LUNAME=ALL,xxxxxxxx
Processes all VTAM LUs and allows you to restrict processing to a specific or generic LUNAME. ALL is
the default setting.
GROUP=ALL,WORKLOAD,nn
Processes transactions that belong to all GROUPS defined in KC2GRP. Allows you to restrict
processing to a specific group of transactions. If you specify GROUP=WORKLOAD, then all transactions
belonging to GROUP 0 are ignored from all processing. ALL is the default setting.
SHIFT=ALL,nn
Restricts the selection criteria to a specific shift as defined in KC2SHFT. ALL is the default setting.
SUMBY=DAY,WEEK,MONTH
Determines how a report is summarized. For example, you can create a report by day for 7 days by
specifying DAILYLO=1, DAILYHI=7, SUMBY=DAY, or by week by specifying DAILYLO=1, DAILYHI=7,
SUMBY=WEEK. KC2DCH1, a Response Time Chart by Hour, is summarized by week as follows:

DAILYLO=1,DAILYHI=7,LOTIME=09:00:00,HITIME=12:00:00,SUMBY=WEEK

This would graph the response time distribution for the three hour period over the week. This
parameter is not valid for reports KC2DCH5, KC2DCH6, and KC2DRP7. DAY is the default setting.
TRAN=ALL,xxxx .
Restricts the selection criteria to a specific or generic transaction ID. ALL is the default setting.
USERID=ALL,xxxxxxxx
Restricts the selection criteria to a specific or generic userid. ALL is the default setting.
EXIT=NO,xxxxxxxx
Specifies the name of the exit program you write to allow greater selection criteria. NO is the default
setting.
STOP=NO,nnn
When set to a numeric value, restricts processing to a specified number of input records for debugging
purposes. NO is the default setting.
DEBUG=NO,YES
When set to YES, this parameter switches debugging on. NO is the default setting.

Chapter 5. Reference 179

 DAILY reports and graph charts
These are the DAILY reports and graph charts that can be produced:
• KC2DRP1 - Response Time Statistics by Transaction
This report has no additional parameters.
• KC2DRP2 - Response Time Statistics by Hour
This report has no additional parameters.
• KC2DRP4 - Service Level Report by Transaction
This report has no additional parameters.
• KC2DRP5 - Service Level Report by Hour
This report has no additional parameters.
• KC2DRP7 - Response Time Graphs
This report provides the following additional parameters:
RPTINT=YES,NO
Specifies whether the Interval Response report is produced. YES is the default setting.
RPTTRAN=YES,NO
Specifies whether the Transaction Response report is produced. YES is the default setting.
RPTLU=YES,NO
Specifies whether the LU Response report is produced. YES is the default setting.
These are the graphs that can be produced:
– response time by interval
– response time by transaction ID
– response time by VTAM LU
• KC2DRP8 - Response Time and VSAM/DB Activity by Transaction
This report has no additional parameters.
• KC2DRP9 - Response Time and VSAM/DB Activity by Hour
This report has no additional parameters.
• KC2DR16 - Region Summary
This report has no additional parameters.
• KC2DCH1 - Chart of Average Response Time by Hour parameters
This chart provides the following additional parameters:
SPLIT=
You can specify the keyword ‘CICSGRP,' if you need it to produce charts by transaction group.
TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=RESPTIME,xxxxxxxx
Although this is by default a response time chart, you may specify another field here; for example,
USRCPUTM, to obtain a chart of User CPU Time. RESPTIME is the default setting.
HDR=AVERAGE RESPONSE TIME,cccc..ccc
Allows a user-defined header to be specified. AVERAGE RESPONSE TIME is the default setting.
SCALE=5,nn,0.n
Determines the maximum scale to use for the graph axis. 5 is the default setting.
• KC2DCH2 - Average Response Time by Hour within Group

180 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 KC2DCH2, which produces a chart of average response time by hour within each group, has the
following additional parameters:
INTERVAL=15,nn
Specifies the response time graph interval. 15 is the default setting.
TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=RESPTIME,xxxxxxxx
Although this is a chart of transaction response time, you may produce a chart using a different
variable. RESPTIME is the default setting.
HDR=AVERAGE RESPONSE TIME,cccc..ccc
Allows a user-defined header to be specified when requesting a different CHARTVAR variable.
AVERAGE RESPONSE TIME is the default setting.
SCALE=5,nn,0.n
Determines the maximum scale to use for the graph axis. 5 is the default setting.
• KC2DCH3 - Chart of Total User CPU Time by Hour parameters
This chart provides the following additional parameters:
SPLIT=
You can specify the keyword ‘CICSGRP,' if you need it to produce charts by transaction group.
TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=USRCPUTM,xxxxxxxx
Although this is a chart of user CPU time, you may produce a chart using a different variable.
USRCPUTM is the default setting.
HDR=USER CPU TIME,cccc..ccc
Allows a user-defined header to be specified when you are requesting a different CHARTVAR
variable. USER CPU TIME is the default setting.
SCALE=5,nn,0.n
Determines the maximum scale to use for the graph axis. 5 is the default setting.
• KC2DCH4 - Total User CPU Time by Hour within Group parameters
KC2DCH4, which produces a chart of total user CPU time by hour within each group, has the following
additional parameters:
TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=USRCPUTM,xxxxxxxx
Although this is a chart of user CPU time, you may produce a chart using a different variable.
USRCPUTM is the default setting.
HDR=USER CPU TIME,cccc..ccc
Allows a user-defined header to be specified when you are requesting a different CHARTVAR
variable. USER CPU TIME is the default setting.
• KC2DCH5 - Chart of Average Response Time by Day
This chart provides the following additional parameters:
SPLIT=
You can specify the keyword ‘CICSGRP' to produce charts by transaction group.
TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=RESPTIME,xxxxxxxx
Although this is a chart of user CPU time, you may produce a chart using a different variable.
RESPTIME is the default setting.

Chapter 5. Reference 181

 HDR=RESPONSE TIME STATISTICS,cccc..ccc
Allows a user-defined header to be specified. RESPONSE TIME STATISTICS is the default setting.
SCALE=5,nn,0.n
Determines the maximum scale to use for the graph axis. 5 is the default setting.
KC2DCH5 uses a default value of 7 for the DAILYHI parameter rather than the usual default of 1. Using
this higher value, you can produce a report of daily response time for a seven day period.
• KC2DCH6 - Average Response Time by Day within Group
KC2DCH6, which produces a chart of average response time by day within each group, provides the
following additional parameters:
SPLIT=
You can specify the keyword ‘CICSGRP' to produce charts by transaction group.
TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=RESPTIME,xxxxxxxx
Although this is a chart of user CPU time, you may produce a chart using a different variable.
RESPTIME is the default setting.
HDR=RESPONSE TIME STATISTICS,cccc..ccc
Allows a user-defined header to be specified. RESPONSE TIME STATISTICS is the default setting.
SCALE=5,nn,0.n
Determines the maximum scale to use for the graph axis. 5 is the default setting.

Producing reports through the Generalized Report Writer

You can create your own custom reports from the DETAIL data set, using the Generalized Report Writer.
This facility allows you to supply the report field names, using the SAS LET command, and the
summarization criteria and output format that you require. A list of field names is contained in member
KC2LABL, which is used in the KC2SMFR program.
Reports can be list or summary type reports, depending on the parameters you define.

Using the KC2TGRW program

KC2TGRW is the SAS code that performs the Generalized Report Writer function. Whenever you want
user-defined reports, invoke the KC2TGRW program by customizing and running the supplied KC2GRWJ
job, located in the KC2SJCL data set, against the SAS DETAIL data set (or its archived copy).
The KC2TGRW program provides the following parameters:
CICS= ALL,xxxxxxxx
Determines whether SMF records relating to all or a specific or generic CICS applid are processed. For
example, CICS=PROD restricts processing to all CICS applids beginning with PROD. Alternatively, you
can specify CICS=ALL and use the EXIT= option to accommodate more specific processing. ALL is
the default setting.
LUNAME=ALL,xxxxxxxx
Processes all VTAM LUs and allows you to restrict processing to a specific or generic LUNAME. All is
the default setting.
GROUP=ALL,WORKLOAD,nn
Processes transactions that belong to all GROUPS defined in KC2GRP. Allows you to restrict
processing to a specific group of transactions. If you specify GROUP=WORKLOAD, then all transactions
belonging to GROUP 0 are ignored from all processing. All is the default setting.
SHIFT=ALL,nn
Restricts the selection criteria to a specific shift as defined in KC2SHFT. All is the default setting.
TERM=ALL,xxxx
Restricts the selection criteria to specific or generic terminal IDs. All is the default setting.

182 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

TRAN=ALL,xxxx
Restricts the selection criteria to a specific or generic transaction ID. All is the default setting.
USERID=ALL,xxxxxxxx
Restricts the selection criteria to a specific or generic userid. YES is the default setting.
LODATE=NO,mm/dd/yy
Restricts the selection criteria to a specific start date. NO is the default setting.
LOTIME=NO:,hh:mm:ss
Restricts the selection criteria to a specific start time. NO is the default setting.
HIDATE=NO,mm/dd/yy
Restricts the selection criteria to a specific end date. NO is the default setting.
HITIME=NO,hh:mm:ss
Restricts the selection criteria to a specific end time. NO is the default setting.
EXIT=NO,xxxxxxxx
Specifies the name of the exit program you write to allow greater selection criteria. NO is the default
setting.
STOP=NO,nnn
When set to a numeric value, restricts processing to a specified number of input records for debugging
purposes. NO is the default setting.
HDR=User Defined Report,cc..cc
Allows you to specify a heading to be generated as part of the report title. User Defined Report is the
default setting.
DEBUG=NO,YES
When set to YES, this parameter switches debugging on. NO is the default setting.

Running the Generalized Report Writer

Customize and run the supplied KC2GRWJ job, located in the KC2SJCL data set, against the SAS DETAIL
data set (or its archived copy) when you want user-defined reports.

Merging of the SAS DETAIL data files

Since the SAS DETAIL data set comprises of two data files, CICSTRAN and the optional DBD data file,
the Generalized Report Writer must merge the files for reporting purposes when the KEEPDBD parameter
specifies at least one field. The two files are merged based upon their internal CICS unit-of-work token
and transaction ID. Any mismatches are dropped from the report.

Control statements for generating custom reports

Use the following control statements in KC2GRWJ to generate custom reports: All control statements
must be present and each statement terminated with a semicolon (;).
KEEP=field1 field2 field3 field4..;
Assigns all the fields from the CICSTRAN data file within the DETAIL data set that you require to
produce the report. At least one field must be present.
KEEPDBD=field1 field2 field3 field4..;
Assigns any optional fields from the DBD data file within the DETAIL data set that you require to
produce the report. If no fields are required, you must define this parameter as KEEPDBD=; If you do
so, the data files (from the SAS DETAIL data set) are not merged.
SORTBY=field1 field2 field3..;
Assigns all the fields you sort by.
SUMVARS=field1 field2 field3..;
Specifies the field names to be summarized. The output from the summarization process generates
summarized variables in the order matching the SUMVARS statement; for example:

Chapter 5. Reference 183

 SUMVARS=USRCPUTM RESPTIME

This definition provides averages, totals, maximums and minimums of transaction CPU and response
times. The presence of variables defined to the SUMVARS control statement determines whether a list
or summary report is produced.
IMPORTANT: For each field defined in the SUMVAR control statement, you must define a
corresponding field in each of the AVER, TOTAL, MAX and MIN control statements. Therefore, you
might need to define dummy fields for fields you do not need. If you do not require any output
variables of a certain type, you can specify a null value; for example, MIN=.;.
AVER=useravgfield1 useravgfield2..;
Defines the user-specified fields for averages, for each field defined in the same order as specified in
the SUMVARS statement.
TOTAL=usertotfield1 usertotfield2..;
Defines the user-specified fields for totals, for each field defined in the same order as specified in the
SUMVARS statement.
MAX=usermaxfield1 usermaxfield2..;
Defines the user-specified field for maximums, for each field defined in the same order as specified in
the SUMVARS statement.
MIN=usermaxfield1 usermaxfield2..;
Defines the user-specified field for minimums, for each field defined in the same order as specified in
the SUMVARS statement.
PRINTBY=field1,userfieldx..;
Defines the print control break. For example, if you want a report of transaction counts by CICS region,
you can first sort by region (SMFMNPRN) and transaction ID (TRAN), summarize to get the total
transaction count, and then use the PRINTBY statement to force a break at every new region name.
PRINTID=field1;
Specifies the first field to appear on each line of the report. This parameter also prevents SAS from
numbering each line of the report.
PRINT=field1 userfieldx..;
Defines the fields that you want to appear on the report, including user-defined fields specified in the
AVER, TOTAL, MAX and MIN statements.
HEADING=userfield1=heading1 userfield2=heading2;
User-defined fields specified in AVER, TOTAL, MAX and MIN, which are to be written to the report, can
have headings defined. For example: HEADING=TRAN_CT=Total Transaction*Count;..
FORMAT=field1 field2 format..;
Defines the format in which a field is to be printed using standard SAS notation. For example, to print
User CPU Time and the Dispatch Wait Time as eight character fields to four decimal places, specify
the following: FORMAT USRCPUTM DISPWTTM 8.4
In addition, an internal format exists (IN_K.) to display count fields in units of thousands. For example,
to print a File Control I/O Requests field, specify: FORMAT FCTOTCT IN_K.; This field reports as nnn
for values less than 1000 and nnnK for values in excess of 1000. If FORMAT is set to default, the fields
print in accordance with their internal SAS format.
KC2TGRW
The SAS macro that invokes the Generalized Report Writer. The JCL supplied for KC2TGRW,
KC2GRWJ, contains sample custom reports that you can customize.

Tips for producing list and summary reports

If you require a list report, leave SUMVARS, AVER, TOTAL, MAX and MIN set to nulls; for example, specify
MIN=;. You might then report on any field defined in the KEEP list.
If you require a summary report, follow these steps:
1. Specify the required fields in the KEEP list.

184 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

2. In the SORTBY list, specify the fields you want to sort and summarize.
In the SUMVARS list, specify the fields for which you want summary information. If you require
averages, totals, minimums, or maximums, then specify fields in the AVER, TOTAL, MAX, and MIN
parameters, respectively. You can now report on the fields specified in the parameters SORTBY, AVER,
TOTAL, MAX and MIN.

Examples of custom reports

This section contains report definition examples for explanations of how the control statements are used
for custom reports:
Summary report for transaction abend codes
To produce a summary report of transaction abend codes, sorted by abend code with a count of the
number of abended transactions and how many resources these transactions consumed, specify the
following control statements:

%LET KEEP =SMFMNPRN ABCODEO TRANCNT RESPTIME USRCPUTM FCTOTCT;

%KEEPDBD =; /* No fields from DBD data file required */
%LET SORTBY = SMFMNPRN ABCODEO;/*Summarize by abend code within region*
%LET SUMVARS = TRANCNT RESPTIME USRCPUTM FCTOTCT;/*fields to summarize*
%LET AVER =DUM1 RESP_AVG CPU_AVG FC_AVG; /*user-defined fields*/
%LET TOTAL =TRAN_CNT RESP_TOT CPU_TOT FC_TOT; /*for averages,totals*/
%LET MAX = DUM3 RESP-MAX DUM4 DUM5; /*and maximums */
%LET MIN =;
%LET PRINTBY =SMFMNPRN; /*print by region*/
%LET PRINTID =ABCODEO; /*first report field*/
%LET PRINT =TRAN_CNT RESP_AVG RESP_MAX RESP_TOT CPU_AVG CPU_TOT
FC_AVG FC_TOT; /*field sequence on print line*/
%LET FORMAT =; /*no special formatting needed*/
%LET HEADING =TRAN_CNT ="Total*Tran*Count" /*meaningful headings to*/
RESP_AVG = "Average*Response*Time*(Secs)" /*fields */
RESP_MAX = "Maximum*Response*Time*(Secs)"
RESP_TOT = "Total*Response*Time*(Secs)"
CPU_AVG = "Average*CPU*Time*(Secs)"
CPU_TOT = "Total*CPU*Time*(Secs)"
FC_AVG = "Average*File*Requests"
FC_TOT = "Total*File*Requests" ;
%KC2TGRW (EXIT=MYEXIT,HDR=ABEND CODE SUMMARY REPORT);
/*
//MYEXIT DD *
IF ABCODEO=:"00" THEN DELETE; /*exit to filter just abends*/
/*

Note: The aforementioned example shows four fields specified in SUMVARS, so four fields must
appear in AVER, TOTAL, MAX, and MIN. No minimum values are required, however, so this control
statement is coded with null values. DUM1 is a dummy variable that acts as a placeholder for
TRANCNT in the AVER control statement, since the average transaction count is not required. This
is also true for dummy variables DUM3, DUM4, and DUM5.
The Abend Code Summary Report is an example of a report produced from the data previously
mentioned.
List report of transactions using umbrella services
To produce a list report of transactions that use OMEGAMON umbrella transaction services, specify
the following control statements. This report shows the umbrella transaction ID, program name, and
the 32 - byte user work area. Only those transactions with an umbrella transaction ID or program
name are reported.

%LET KEEP =SMFMNPRN TRANNUM TRAN PGMNAME START USRCPUTM RESPTIME

MUMBPTC MUMBUSR MUSRWRK;
%KEEPDBD =; no fields from DBD datafile required*/
%LET SORTBY = SMFMNPRN TRANNUM;
%LET SUMVARS =; /*denotes a LIST type report */
%LET AVER =; /*therefore AVER */
%LET TOTAL =; /* and TOTAL */
%LET MAX =; /* and MAX */
%LET MIN =; /* and MIN are not used so set to null*/
%LET PRINTBY = SMFMNPRN; /* print by region */
%LET PRINTID = TRANNUM; /* first report field */
%LET PRINT = TRAN PGMNAME START USRCPUTM RESPTIME MUMBPTC

Chapter 5. Reference 185

 MUMBUSR MUSRWRK; /* field sequence on print line */
%LET FORMAT =; /*Use default formatting */
%LET HEADING =; /*no special heading requirements needed */
%KC2TGRW (CICS=TDOCS66,GROUP=WORKLOAD,
HDR=UMBRELLA TRANSACTION REPORT,EXIT=UMBEXIT);
/*
//UMBEXIT DD *
IF MUMBPTC=:”00”X AND MUMBUSR=:”00”X THEN DELETE; /*our filter criteria
/*

The Umbrella Transaction Report is an example of a report that is produced from the previously
mentioned data.
Replication of the supplied SAS report, KC2TRP3
You can use the Generalized Report Writer to replicate the supplied SAS report, KC2TRP3. Specify the
following control statements:

%LET KEEP =SMFMNPRN TRAN START TRANNUM TTYPE TERM RESPTIME

USRCPUTM FCTOTCT SUSPNDTM DISPWTTM ABCODEO;
%LET KEEPDBD =; /*no fields from DBD needed */
%LET SORTBY =SMFMNPRN START; /*by task start time in region*/
%LET SUMVARS =; /*this is a list report so */
%LET AVER =; /*none */
%LET TOTAL =; /*of */
%LET MAX =; /*these */
%LET MIN =; /*fields needed */
%LET PRINTBY =SMFMNPRN; /*print by region */
%LET PRINTID =TRAN; /*first field on the report */
%LET PRINT =START TRANNUM TRANTYPE TERM RESPTIME USRCPUTM FCTOTCT
SUSPNDTM DISPWTTM ABCODEO; /*other fields in order */
%LET HEADING =TRANTYPE='Tran*Type'; /*Tran Type is our
/*representation of TTYPE */
%LET FORMAT =SUSPNDTM DISPWTTM 8.3 FCTOTCT IN_K.
USRCPUTM 8.4;
%KC2TGRW (HDR=TRP3 EQUIVALENT REPORT,EXIT=MYEXIT,GROUP=WORKLOAD);
/*
//MYEXIT DD *
IF ABCODEO=: "00"X THEN DELETE;

The TRP3 Equivalent Report is an example of a report that is produced from the previously mentioned
data.

Building response time transaction groups

KC2TRXG, located in the KC2SPROG data set, is the Response Time Transaction Group Build program.
This program analyzes the SAS DETAIL data set and produces GROUP_DEFINITIONS and ID parameter
for each CICS system for which transaction data is found.

Group threshold values

KC2TRXG can produce 15 groups (GROUP_DEFINITIONS parameters) with default thresholds of 1-10, 15,
20, 30, 45, and 60 seconds, respectively. Ascending threshold values are assigned to the groups.
You can override the default group thresholds, but ensure that you assign thresholds an ascending value
for each group. If you have no requirement to use all 15 groups, assign the unused groups a value of zero.
Each analyzed transaction ID is assigned to one of the 15 groups. If a transaction cannot be assigned to a
specific group, a warning message is provided. For example, a message may occur because the calculated
response time threshold for a transaction exceeds the highest group threshold.

Using the KC2TRXG program

KC2TRXG is the SAS program that performs the response time transaction group build function. To run the
build function, customize and run the supplied job KC2TRXJ, located in the KC2SJCL data set, to produce
ID and GROUP_DEFINITIONS parameters. You can then insert these parameters into the global data area
module (GLOBAL_OPTIONS).
The KC2TRXGh program provides the following parameters:

186 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

CICS= ALL,xxxxxxxx
Determines whether SMF records relating to all or a specific or generic CICS applid are processed. For
example, CICS=PROD restricts processing to all CICS applids beginning with PROD. Alternatively, you
can specify CICS=ALL and use the EXIT= option to accommodate more specific processing. ALL is
the default setting.
LUNAME=ALL,xxxxxxxx
Processes all VTAM LUs and allows you to restrict processing to a specific or generic LUNAME. All is
the default setting.
GROUP=ALL,WORKLOAD,nn
Processes transactions that belong to all GROUPS defined in KC2GRP. Allows you to restrict
processing to a specific group of transactions. If you specify GROUP=WORKLOAD, then all transactions
belonging to GROUP 0 are ignored from all processing. All is the default setting.
SHIFT=ALL,nn
Restricts the selection criteria to a specific shift as defined in KC2SHFT. All is the default setting.
TERM=ALL,xxxx
Restricts the selection criteria to specific or generic terminal IDs. All is the default setting.
TRAN=ALL,xxxx
Restricts the selection criteria to a specific or generic transaction ID. All is the default setting.
USERID=ALL,xxxxxxxx
Restricts the selection criteria to a specific or generic userid. YES is the default setting.
LODATE=NO,mm/dd/yy
Restricts the selection criteria to a specific start date. NO is the default setting.
LOTIME=NO:,hh:mm:ss
Restricts the selection criteria to a specific start time. NO is the default setting.
HIDATE=NO,mm/dd/yy
Restricts the selection criteria to a specific end date. NO is the default setting.
HITIME=NO,hh:mm:ss
Restricts the selection criteria to a specific end time. NO is the default setting.
EXIT=NO,xxxxxxxx
Specifies the name of the exit program you write to allow greater selection criteria. NO is the default
setting.
STOP=NO,nnn
When set to a numeric value, restricts processing to a specified number of input records for debugging
purposes. NO is the default setting.
GROUP1=10,nn
Determines the threshold (in 10ths of a second) to be applied to this group. This value is equivalent to
the ELOG= parameter in the GROUP_DEFINITIONS parameter. 10 is the default setting.
GROUP2=20,nn
Determines the threshold (in 10ths of a second) to be applied to group 2. 20 is the default setting.
GROUP3=30,nn
Determines the threshold (in 10ths of a second) to be applied to group 3. 30 is the default setting.
GROUP4=40,nn
Determines the threshold (in 10ths of a second) to be applied to group 4. 40 is the default setting.
GROUP5=50,nn
Determines the threshold (in 10ths of a second) to be applied to group 5. 50 is the default setting.
GROUP6=60,nn
Determines the threshold (in 10ths of a second) to be applied to group 6. 60 is the default setting.
GROUP7=70,nn
Determines the threshold (in 10ths of a second) to be applied to group 7. 70 is the default setting.

Chapter 5. Reference 187

 GROUP8=80,nn
Determines the threshold (in 10ths of a second) to be applied to group 8. 80 is the default setting.
GROUP9=90,nn
Determines the threshold (in 10ths of a second) to be applied to group 9. 90 is the default setting.
GROUP10=100,nn
Determines the threshold (in 10ths of a second) to be applied to group 10. 100 is the default setting.
GROUP11=150,nn
Determines the threshold (in 10ths of a second) to be applied to group 11. 150 is the default setting.
GROUP12=200,nn
Determines the threshold (in 10ths of a second) to be applied to group 12. 200 is the default setting.
GROUP13=300,nn
Determines the threshold (in 10ths of a second) to be applied to group 13. 300 is the default setting.
GROUP14=450,nn
Determines the threshold (in 10ths of a second) to be applied to group 14. 400 is the default setting.
GROUP15=600,nn
Determines the threshold (in 10ths of a second) to be applied to group 15. 500 is the default setting.
Values must be assigned to groups using increasingly higher values. If you do not require a specific
group, then set its value to zero.
CHKVALU=SIGMA3,PCT90,PCT95,PCT99
Determines the threshold to use when deciding to which response time group to allocate the
transaction. (Sigma3 is equivalent to 3 * Standard Deviation + the Mean. SIGMA3 is the default
setting.

Determining relevant thresholds for the local environment

KC2TRXG produces a report that shows the group and calculated threshold for each transaction found.
You should review the report and determine whether the thresholds are relevant to the local environment.
You might decide that the calculation method used is inappropriate and that a more realistic threshold
might have to be applied manually. By default, the threshold used to determine the group into which a
transaction is assigned is based on 3*Standard Deviation plus the Mean; that is, Sigma3.
As an alternative to the default calculation, you might want to apply the 90th, 95th, or 99th percentile
threshold. You can rerun the report as often as required using the alternative algorithms, until a more
relevant result is achieved. You might find, however, that due to fluctuations in the analyzed data,
discrepancies might occur that can only be addressed by local knowledge and manual adjustment.
Therefore, you may want to run KC2TRXG against data for different days and compare the results before
applying them.
For each transaction ID, KC2TRXG produces a corresponding ID parameter and rounds up the specific
transaction threshold to the next tenth of a second. For example, a calculated response threshold of
0.461 is defined as THRESH=50 in the ID parameter.

Running the response time transaction group builder

To run the Response Time Transaction Group Builder, customize and run the supplied SAS macro
KC2TRXJ, located in the KC2SJCL data set, to produce the ID and GROUP_DEFINITIONS parameters.
You can later insert these parameters into the global data area module (GLOBAL_OPTIONS).
A report that is produced from KC2TRXG is Response Time Profile for Transactions by CICS Region.
This the Parameter Definitions List:

*
*
* DEFINITIONS FOR CICS REGION PROD
*
GROUP_DEFINITIONS INITIAL
GROUP_DEFINITIONS ID,GRP=1,GTYP=TRAN, X

188 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

NAME='PROD GROUP1',ELOG=10
GROUP_DEFINITIONS ID,GRP=2,GTYP=TRAN, X
NAME='PROD GROUP2',ELOG=20
GROUP_DEFINITIONS ID,GRP=3,GTYP=TRAN, X
NAME='PROD GROUP3',ELOG=30
GROUP_DEFINITIONS ID,GRP=4,GTYP=TRAN, X
NAME='PROD GROUP4',ELOG=40
GROUP_DEFINITIONS ID,GRP=5,GTYP=TRAN, X
NAME='PROD GROUP5',ELOG=50
GROUP_DEFINITIONS ID,GRP=6,GTYP=TRAN, X
NAME='PROD GROUP6',ELOG=60
GROUP_DEFINITIONS ID,GRP=7,GTYP=TRAN, X
NAME='PROD GROUP7',ELOG=70
GROUP_DEFINITIONS ID,GRP=8,GTYP=TRAN, X
NAME='PROD GROUP8',ELOG=80
GROUP_DEFINITIONS ID,GRP=9,GTYP=TRAN, X
NAME='PROD GROUP9',ELOG=90
GROUP_DEFINITIONS ID,GRP=10,GTYP=TRAN, X
NAME='PROD GROUP10',ELOG=100
GROUP_DEFINITIONS ID,GRP=11,GTYP=TRAN, X
NAME='PROD GROUP11',ELOG=150
GROUP_DEFINITIONS ID,GRP=12,GTYP=TRAN, X
NAME='PROD GROUP12',ELOG=200
GROUP_DEFINITIONS ID,GRP=13,GTYP=TRAN, X
NAME='PROD GROUP13',ELOG=300
GROUP_DEFINITIONS ID,GRP=14,GTYP=TRAN, X
NAME='PROD GROUP14',ELOG=450
GROUP_DEFINITIONS ID,GRP=15,GTYP=TRAN, X
NAME='PROD GROUP15',ELOG=600
GROUP_DEFINITIONS FINAL
*
ID INITIAL,SCALE=2,WINDOW=10
*WARNING*
* TRANSACTION LSR1 COULD NOT BE PUT IN ANY GROUP
*WARNING*
*WARNING*
* TRANSACTION MIKE COULD NOT BE PUT IN ANY GROUP
*WARNING*
*WARNING*
* TRANSACTION MISC COULD NOT BE PUT IN ANY GROUP
*WARNING*
*WARNING*
* TRANSACTION OEN2 COULD NOT BE PUT IN ANY GROUP
*WARNING*
*WARNING*
* TRANSACTION QTDI COULD NOT BE PUT IN ANY GROUP
*WARNING*
*WARNING*
* TRANSACTION QTI1 COULD NOT BE PUT IN ANY GROUP
*WARNING*
*WARNING*
* TRANSACTION QTS2 COULD NOT BE PUT IN ANY GROUP
*WARNING
ID ID,TRAN=AADD,GROUPS=(1),THRESH=1
IDID ID,TRAN=AC2A,GROUPS=(1),THRESH=4
ID ID,TRAN=AC20,GROUPS=(1),THRESH=2
ID ID,TRAN=AC22,GROUPS=(1),THRESH=3
ID ID,TRAN=AC28,GROUPS=(1),THRESH=7
ID ID,TRAN=AMNU,GROUPS=(1),THRESH=1
ID ID,TRAN=AUPD,GROUPS=(1),THRESH=8
ID ID,TRAN=DEGE,GROUPS=(1),THRESH=3
ID ID,TRAN=IDMS,GROUPS=(1),THRESH=2
ID ID,TRAN=LSRW,GROUPS=(1),THRESH=1
ID ID,TRAN=OAD1,GROUPS=(1),THRESH=1
ID ID,TRAN=OAID,GROUPS=(1),THRESH=2
ID ID,TRAN=OENQ,GROUPS=(1),THRESH=1
ID ID,TRAN=OICE,GROUPS=(1),THRESH=1
ID ID,TRAN=OIC1,GROUPS=(1),THRESH=4
ID ID,TRAN=OMEG,GROUPS=(1),THRESH=2
ID ID,TRAN=PAIN,GROUPS=(1),THRESH=6
ID ID,TRAN=RAID,GROUPS=(1),THRESH=1
ID ID,TRAN=STAT,GROUPS=(1),THRESH=4
ID ID,TRAN=STR1,GROUPS=(1),THRESH=2
ID ID,TRAN=VADD,GROUPS=(1),THRESH=1
ID ID,TRAN=VAD1,GROUPS=(1),THRESH=5
ID ID,TRAN=VBR1,GROUPS=(1),THRESH=10
ID ID,TRAN=VSTR,GROUPS=(1),THRESH=1
ID ID,TRAN=WD80,GROUPS=(1),THRESH=4
ID ID,TRAN=ABRW,GROUPS=(2),THRESH=17
ID ID,TRAN=AINQ,GROUPS=(2),THRESH=13
ID ID,TRAN=DEGS,GROUPS=(2),THRESH=13
ID ID,TRAN=INIT,GROUPS=(2),THRESH=11

Chapter 5. Reference 189

 ID ID,TRAN=QMNU,GROUPS=(3),THRESH=21
ID ID,TRAN=QTS1,GROUPS=(3),THRESH=30
ID ID,TRAN=DEGG,GROUPS=(4),THRESH=31
ID ID,TRAN=QTSA,GROUPS=(4),THRESH=39
ID ID,TRAN=DEGC,GROUPS=(5),THRESH=42
ID ID,TRAN=QTSM,GROUPS=(6),THRESH=56
ID ID,TRAN=VBRW,GROUPS=(7),THRESH=62
ID ID,TRAN=DEGT,GROUPS=(9),THRESH=89
ID ID,TRAN=QTDG,GROUPS=(9),THRESH=83
ID ID,TRAN=DEGV,GROUPS=(10),THRESH=99
ID ID,TRAN=DEGA,GROUPS=(14),THRESH=399
ID ID,TRAN=MANT,GROUPS=(14),THRESH=425
ID ID,TRAN=VSEX,GROUPS=(14),THRESH=329
ID FINAL
*
*END OF DEFINITIONS FOR PROD

OMEGAMON for CICS optional features

This section contains configuration information on some optional features that you can use in
OMEGAMON for CICS.

Enabling monitoring for user-defined events

This information is about enabling monitoring for user-defined events. Monitoring for user-defined events
allows you to monitor the performance of CICS applications and display the results you are monitoring in
OMEGAMON for CICS.

Background about monitoring for user-defined events

When you enable monitoring for user-defined events, you can monitor any event in a CICS application.
Use this feature for the following tasks:
• Collecting clock and counter statistics for an event including up to 10 functions for the event
• Displaying the results in OMEGAMON for CICS
The clock and counter statistics are displayed in the following locations in OMEGAMON for CICS:
• Task File Statistics Eventname panel
• Task History panel
• Task History Details panel
• Task History Eventname Resources panel
• Task History Eventname Details panel
• Application Trace panel

The process for monitoring for a user-defined event

The following information provides an overview of the process you follow to enable monitoring for events.
• When you specify the monitoring options for the product in the Global Data Area, specify the event and
the parameters for the event.
• In the code for the application, specify a call to the subroutine before and after the event you want to
monitor.

Specifying a user-defined event and parameters for the event

In the Global Data Area, use USREVNT1 to specify the event you want to monitor.
Table 55 on page 191 shows the parameters you can specify for the event and the values you can use.

190 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 55. Parameters available for USREVNT1
Parameter Purpose Valid Value
AUTO_START Specifies whether or not collection starts YES or NO
automatically.
ONDV_WRITE Specifies whether or not include or exclude YES or NO
statistics for the task history collector.
SMF_WRITE Specifies whether or not to write statistics to SMF. YES or NO
EVENT Specifies the name you want for the event. 1 to 8 character string
(OMEGAMON for CICS displays this name on the
panels where the event occurs.)
FUNCTION Specifies up to 10 function names that can be 1 to 8 character string
displayed for the event.

Event example
This event example has the following characteristics.
• Collection starts automatically.
• Statistics are available for the task history collector.
• Statistics are not written to SMF.
• OMEGAMON for CICS displays the event on the panels as SALTLAKE.
• OMEGAMON for CICS displays the functions ADD, DELETE, BROWSE, UPDATE, and READ when details
are displayed for the event.

<<USREVNT1>>
AUTO_START=YES
ONDV_WRITE=YES
SMF_WRITE=NO
EVENT=SALTLAKE
FUNCTION=(ADD, DELETE, BROWSE, UPDATE, READ)

Specifying the call to the subroutine in the application

In the code for the application, you must also call the subroutine before and after the event you want to
monitor.
OMEGAMON for CICS provides samples of the code you use to monitor the event and this information
covers how to use the samples.

Sample code provided by OMEGAMON for CICS

OMEGAMON for CICS provides samples of the code you use to monitor the event. The samples are
located in hilev.midlev.TKANSAM and thilev.midlev.TKANMAC libraries.
Table 56 on page 191 shows the name of the data set and member that contains the sample code and
provides the purpose of the sample provided.

Table 56. Data set and member purpose for event monitoring sample code
Data set and member Purpose
thilev.midlev.TKANSAM( KOCUE1DR) Driver program that collects the records for the
event.
thilev.midlev.TKANSAM(KOCAUE1) When the records are collected, DSECT you
can use to map the SMF type 112 records for
Assembler.

Chapter 5. Reference 191

 Table 56. Data set and member purpose for event monitoring sample code (continued)
Data set and member Purpose
thilev.midlev.TKANSAM(KOCCUE1) When the records are collected, DSECT you can
use to map the SMF type 112 records for COBOL.
thilev.midlev.TKANSAM(KOCPUE1) When the records are collected, DSECT you can
use to map the SMF type 112 records for PLI.
thilev.midlev.TKANSAM(KOCSUE1) When the records are collected, DSECT you can
use to map the SMF type 112 records for SAS.
thilev.midlev.TKANMAC(KOCAUE1D) Macro used by the driver to map the parameter list.
thilev.midlev.TKANMAC (KOCUE1) Macro used by the driver to generate the storage
definitions for the output fields.
thilev.midlev.TKANMAC (KOCAUE1) Macro used by the driver to generate online code
that calls the OMEGAMON for CICS code.
Note: You might have to alter the register
convention to adhere with your coding standards.

Where to specify the call for the subroutine in the application

The table in this section shows where you specify the call for the subroutine.
• The first column shows the order in the application before you add the subroutine.
• The other column shows the order in the application after you add the call for the subroutine.

Table 57. Where to specify the call to the subroutine for monitoring user-defined events
Application before you add the subroutine Application after you add the subroutine
Your Application Code Your Application Code
User Event • Location to add the code to build the parameter
list and the call to OMEGAMON for CICS to start
Your Application Code
to monitor the event.
User Event
• Location to add the code to build the parameter
list and the call to OMEGAMON for CICS to stop
the monitoring for the event.
Your Application Code

What to specify in your application code before the user event

Follow these instructions to add the code to build the parameter list and add the call to OMEGAMON for
CICS to start monitoring the user event.
The instructions use the following examples:
• The event name is SAMPLE.
• The resource name is TESTING.
• The function defined in the Global Data Area is SUBTRACT.
1. Build the PLIST using DSECT KOCAUE1D (located in thilev.midlev.TKANMAC).
• Move value START into field CALLER_COMMAND
• Move value TESTING into CALLER_RESOURCE_NAME
• Move value SUBTRACT into CALLER_FUNCTION_TYPE

192 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 • Move a return code (RC) into CALLER_STATUS (optional)
2. Call KOCUE1DR ensuring that the address of the parameter list is passed in register 1. (KOCUE1DR is
located in thilev.midlev.TKANSAM.)

What to specify in your application code after the user event

Follow these instructions to add the code to build the parameter list and call OMEGAMON for CICS to stop
monitoring the user event.
The instructions use the following examples:
• The event name is SAMPLE.
• The resource name is TESTING.
• The function defined in the Global Data Area is SUBTRACT.
1. Build the PLIST using DSECT KOCAUE1D (located in thilev.midlev.TKANMAC).
• Move value STOP into field CALLER_COMMAND
• Move value TESTING into CALLER_RESOURCE_NAME
• Move value SUBTRACT into CALLER_FUNCTION_TYPE
• Move a return code (RC) into CALLER_STATUS (optional)
2. Call KOCUE1DR ensuring that the address of the parameter list is passed in register 1. (KOCUE1DR is
located in thilev.midlev.TKANSAM.)

System Management Facility considerations

This section describes interval, system-related, and task-related records and the ways to start, stop, and
limit their logging to SMF.
OMEGAMON for CICS writes interval, system-related, and task-related records to the IBM System
Management Facility (SMF). You can use these records to produce historical reports of your system’s
performance.
You specify all the options for SMF logging using the Global Data Area.
Depending on the options you specified in your Global Data Area for collecting data, OMEGAMON for CICS
can write many records per second to SMF. Therefore, make sure your site has enough storage in your
SMF data sets for these records.

System Management Facility record type

For CICS transaction records, the record type is 110. For all other SMF records, it is 112. Audit records are
specified in the SMFNUM control statement.
Note: Security audit records do not have a default record type.

Record layout
Each record produced by OMEGAMON contains a standard SMF header followed by an OMEGAMON for
CICS (3270) header common to all the records. You must use the OMEGAMON for CICS (3270) header to
identify the record type.
The library thilev.TKANSAM contains Statistical Analysis System (SAS), COBOL, and PL/I record layouts
for all the records written by the OMEGAMON for CICS component. The record layout for the SMF 110
records and OMEGAMON for CICS (3270) header portion is found in member:
• KOCSSMF for SAS records
• KOCCSMF for COBOL records
• KOCPSMF for PL/I records
The library thilev.TKANMAC contains assembler record layouts. The record layout for the SMF and
OMEGAMON for CICS (3270) header portion is found in member KOCSMF in thilev.TKANMAC.

Chapter 5. Reference 193

 For specific member names of each record layout, refer to the following sections.
– “Interval records” on page 194
– “System records” on page 194
– “File and database records” on page 195
– “Transaction records” on page 196
– “Dictionary records” on page 196

Interval records
An interval record contains one-minute summaries of response time, bottleneck, and resource
information.
Frequency of records
The number of records depends on the number of buckets generated by such features as the internal
bottleneck collector and the response time collector.
Approximate record length
The length depends on the number of element IDs containing response time data and the number of
unique wait reasons detected by the internal bottleneck collector during the interval.
Controls
Records are written only if the interval record collector is active. The collector starts automatically, if
the AUTO parameter is specified with the INTR keyword, when the monitoring options were specified
for the product using the Global Data Area. You can manually start and stop the collector from
an OMEGAMON for CICS (3270) session by selecting the Control option on the Main Menu in the
OMEGAMON for CICS (3270) interface.
Post processing
OMEGAMON for CICS supplies a program to extract the records and produce reports. The job is in the
thilev.TKANSAM(KOCREPT).
Record description
See the KOCSINTR, KOCCINT2, KOCPINTR, and KOCAINTR members in thilev.TKANSAM for the SAS,
COBOL, PL/I, and assembler record layouts.

System records
Each time OMEGAMON for CICS (3270) starts and stops monitoring a CICS region, OMEGAMON for CICS
(3270) creates a system record that contains z/OS-related statistics as well as copies of the CSA and
system initialization table (SIT) from CICS.
This can happen in either of the following ways:
• OMEG INIT or OMEG SHUT
• PLT startup or shutdown when the KOCOME00 program is run.
Frequency of records
One record when OMEGAMON for CICS (3270) starts to monitor a CICS region and one record when
OMEGAMON for CICS (3270) stops monitoring a CICS region.
Approximate record length
Record length depends on the version of your CICS Transaction Server.
• V3.1.0 approximately 5912 bytes
• V3.2.0 approximately 5912 bytes
• V4.1.0 approximately 6776 bytes
• V4.2.0 approximately 6616 bytes
Controls
Writing of records is controlled by the Global Data Area WRITE_SYSTEM_RECORDS parameter. If it is
set to YES, system records are written; if it is set to NO, system records are not written; if it is set to

194 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 CMF, the setting of the Global Data Area CICS_CMF_WRITE parameter determines if system records
are written. For example, CICS_CMF_WRITE=YES or CICS_CMF_WRITE=NO.
Post processing
OMEGAMON for CICS converts these records to produce the System Detail Report.
Record description
Refer to the KOCSSREC, KOCCSREC, KOCPSREC, and KOCASREC members of thilev.TKANSAM for the
SAS, COBOL, PL/I, and assembler record layouts.

File and database records

OMEGAMON for CICS produces records detailing the file and database usage for each CICS transaction.
These records contain counts and elapsed times for each type of file or database command that a
transaction issues. These records are intended to be used along with the CICS type 110 SMF records.
The creation of file and database SMF records is controlled by the DATABASE_COLLECTION keyword in
the Global Data Area. You must define one for each file or database product for which you want data
collected. In addition, third-party products require the steps described in “Installing third-party support”
on page 196.
Frequency of records
One record for each transaction for each file or database product used by the transaction. If a single
transaction accesses both DL/I and native VSAM, a file and a database record (2 records) is produced.
One record contains DL/I statistics, and the other record contains VSAM statistics.
Approximate record length
Each record has a totals segment followed by a detail segment for each file or database accessed
during the transaction. The number of files or databases accessed during the life of the transaction
determines the number of bytes in each record.
Controls
Records are written based on the parameter in the DATABASE_COLLECTION keyword in the Global
Data Area for the particular file or database product. You can also turn logging on or off dynamically
from an OMEGAMON for CICS (3270) session by selecting the Control option on the Main Menu in the
OMEGAMON for CICS (3270) interface.
Post processing
Use the CICS Performance Analyzer for z/OS program to process these 112 records; it produces a
transaction level report on file usage by transaction.
Record description
Table 58 on page 195 lists the type of file or database and the member names in the thilev.TKANSAM
library where you can find sample record layouts.

Table 58. Location of file or database sample record layouts

File or database type Programming language Member name
File Control (VSAM) SAS COBOL PL/1 assembler KOCSVSAM KOCCVSAM KOCPVSAM
KOCAVSAM
ADABAS SAS COBOL PL/1 assembler KOCSADA KOCCADA KOCPADA KOCAADA
CA-DATACOM SAS COBOL PL/1 assembler KOCSDCOM KOCCDCOM KOCPDCOM
KOCADCOM
DL/I SAS COBOL PL/1 assembler KOCSDLI KOCCDLI KOCPDLI KOCADLI
IDMS SAS COBOL PL/1 assembler KOCSIDMS KOCCIDMS KOCPIDMS
KOCAIDMS
SUPRA SAS COBOL PL/1 assembler KOCSSUPR KOCCSUPR KOCPSUPR
KOCASUPR
MQ SAS COBOL PL/1 assembler KOCSMQ KOCCMQ KOCPMQ KOCAMQ

Chapter 5. Reference 195

 Transaction records
Transaction records contain resource usage and performance-related statistics for each CICS transaction.
Transaction records are produced by CMF.
CICS Transaction Server produces the following records:
• For each conversation if MNCONV=YES is coded in the SIT
• At each syncpoint if MNSYNC=YES is coded in the SIT
• At the interval specified if MNFREQ is coded with a valid time value
• Every time an EXEC CICS MONITOR request is processed to deliver data for a valid Event Monitoring
Point
• During normal end-of-task processing
Frequency of records
Data is written to a buffer for each transaction or conversation. When the buffer is full, the contents
are written to SMF. The rate at which the buffer fills and is written to SMF varies with the rate of
transactions.
Approximate record length
The length of the record depends on the release of CICS and what is coded in the MCT (field
inclusions, exclusions or user EMPs).
Controls
CICS Transaction Server writes records to SMF unless they are suppressed with the
CICS_CMF_RECORDS keyword set to NO. If you want CMF records in CICS TS, you must set the
CICS_CMF_WRITE keyword to YES. You can also selectively suppress the writing of transaction
records based on transaction ID, refer to the USER_EVENT_MONITORING keyword in the Global Data
Area for more information.
Post processing
You can convert these records and use the historical reporter to produce batch reports.
Record description
Refer to the KOCSTRAN, KOCCTRAN, and KOCPTRAN members in thilev.TKANSAM for the SAS,
COBOL, and PL/I record layouts. In addition, refer to these members to map the OMEGBSC event
monitoring point, which is part of the transaction record. For general information on all of these
members, see KOC$DEF.

Dictionary records
Dictionary records describe the contents of SMF type 110 records and are required when reporting on
transaction records.
OMEGAMON for CICS writes a dictionary record during CICS startup or whenever CMF recording of
transaction records can be enabled by, for example, a CEMT SET MONITOR command.

Installing third-party support

OMEGAMON for CICS can monitor several third-party database and fourth-generation language products.
This section describes how to install support for the products.
These are the supported database products:
• ADABAS
• CA-DATACOM
• IDMS (excluding UCF applications)
• SUPRA
OMEGAMON for CICS provides the following information:

196 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

• Count and elapsed times of database calls per transaction. This data is available through Task History
panels of the OMEGAMON for CICS (3270) interface, the ONDV command of the OMEGAMON for CICS
(3270) interface, or as SMF records for batch historical reporting.
• The database name. This data is collected as part of the waiting resource name during the database
call. The waiting resource name is used in the task display and internal bottleneck analysis.
The fourth-generation language products supported are:
• CA-IDEAL
• GENER/OL
• Millennium
• NATURAL
• PCS
• UFO/Forms
OMEGAMON for CICS (3270) supplies the application name as the umbrella program name on the Task
History panels of the 3270 interface, ONDV command output in the interface, and in SMF 110 records for
historical reporting.
Note:
1. The supported products and the steps you must take to provide that support can change. Before
installing support for any of the third-party products listed, you must
• Check the Preventative Service Planning (PSP) documentation
• Contact IBM Software Support to ensure that you have the latest support and any required
maintenance.
2. When installing a new release of OMEGAMON for CICS or doing a major maintenance upgrade,
investigate whether you have to implement the TPPS facilities again.

Installing ADABAS support

The Tivoli OMEGAMON support for ADABAS has two user exits that you must assemble and link-edit into
the ADABAS/CICS interface module during installation.
There are several versions of the exits provided by OMEGAMON, which one you require, depends on your
ADABAS version and configuration.
If you are using a driver program to run multiple exits at either ADABAS exit point, you must modify the
supplied exits to conform to the standards required by the driver program.
If you are a user of ADABAS and Software AG's VISTA, use the VISTA file translation facility. If you
want to monitor FILE/DATABASE usage using the file numbers as translated by VISTA, use the exits
and JCL defined in the KOCADAVI member of thilev.TKANSAM library. See the KOCADVII member of
thilev.TKANSAM library for further instructions. If you do not need to monitor the VISTA translated FILE /
DATABASE number, use the ADABAS sample exits for your version of ADABAS.
If you are using ADABAS Version 7, and you are not using the VISTA exits, use the exits and JCL defined in
the KOCADAV7 member of thilev.TKANSAM library. See the KOCADV7I member of thilev.TKANSAM library
for further instructions.
If you are not using the Vista exits and are using ADABAS version 8, use the exits and JCL defined in the
KOCADAV8 member of thilev.TKANSAM library. See the KOCADV8I member of thilev.TKANSAM library for
further instructions.

Installing CA-DATACOM and CA-IDEAL support

Support for CA-DATACOM is available for Versions 8 to 12 inclusive.
1. Modify a copy of the CA-DATACOM exit DCCTXPR as follows:
a. Change the line:

Chapter 5. Reference 197

 TEMP B RETURN SKIP THE COREMARK

to

TEMP B OVERHEAD SKIP THE COREMARK

b. After OVERHEAD label add the following line:

KOCDC832 ,

2. Assemble and link-edit DCCTXPR.

a. Modify the CA-supplied JCL as follows:
b. Assemble step: Point SYSIN to the modified copy of DCCTXPR:

//SYSIN DD DISP=SHR,DSN=your.source.lib(DCCTXPR)

c. Add OMEGAMON TKANMAC to SYSLIB concatenation:

//SYSLIB DD DISP=SHR,DSN=...............
// DD DISP=SHR,DSN=thilev.TKANMAC

Note: Be sure to use the latest CICS, DATACOM, and OMEGAMON CICS macro libraries for the
assembly.
d. Link step: Add OMEGAMON CICS TKANMOD as SYSLIB:

//SYSLIB DD DISP=SHR,DSN=thilev.TKANMOD

Note: If your configuration uses the SMP libraries, include thilev.TKANMOD in the SYSLIB
concatenation.
e. Modify the control statements to include an OMEGAMON CICS module, for example:

// DD *
INCLUDE SYSLIB(KOCFIN00)
NAME DCCTXPR(R)

3. Specify <<DATACOM>> in the <DATABASE_COLLECTION> section of the Global Data Area.

Installing GENER/OL support

To install GENER/OL support, follow these steps:
1. Add an entry to the PPT for KOCGENcc, with the attributes of assembler and resident.
2. Replace the cc in KOCGENcc with the 2-character suffix that represents the version you are running, as
shown in the following table.

Table 59. Suffix for Transaction Server by version

CICS Transaction Server release Suffix
3.1 CA
3.2 DA
4.1 EA
4.2 FA
3. Select option 4, Security, from the GENER/OL Customize Task Exit Parameters panel. The System
Administration menu is displayed.
4. Select option 4, Customize, from the System Administration menu. The Customize Task
Parameters menu is displayed .
5. Enter the following information on the Customize Task Parameters menu:

198 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 • KOCGENcc for the program name
• L for Use Branch Entry or CICS Link
• YES for GENER/OL Initialization
• NO for all other fields
6. Restart GENER/OL.

Installing IDMS support

This section describes how to install IDMS support for Versions 10 and 12.
To install support for IDMS, you must modify the IDMS-supplied macro IDMSINTC with the supplied
macros by completing the following procedure.
1. Make a copy of the IDMSINTC macro.
• For V10, modify this copy by inserting KOCAIDMS START after the statement that generates the
following set of installation instructions.

IDMSINC1 STM R14,R12,12(R13)

L R9,BASE
LR R8,R13
L R13,CSAADDR
L R12,CSACDTA
KOCAIDMS START

Insert KOCAIDMS STOP after the statement that generates the following set of installation
instructions.

IDMSINC2 STM R14,R12,12(R13)

L R9,BASE
LR R8,R13
L R13,CSAADDR
L R12,CSACDTA
KOCAIDMS STOP

• For V12, make a copy of the IDMSINTC macro. Modify this copy by inserting the statement
KOCAID12 START as shown. The instructions are located near the label NOOPTI.

L R1,CALLERSV+24 R1 -> CALLER’S PLIST

KOCAID12 START
B *(R5)

Insert the statement KOCAID12 STOP as shown.

XXIDMS DS 0H
KOCAID12 STOP
B *(R5) GO BASED ON TYPE OF CALL

2. Reassemble and link the module. You must include the thilev.TKANMAC and the IBM AMODGEN data
sets in the SYSLIB concatenation for the assemble step.
The link-edit step must also include:
a. The thilev.TKANMOD library in the SYSLIB concatenation
Note: If your configuration uses the SMP libraries, include thilev.TKANMOD in the SYSLIB
concatenation.
b. The following control statement for the linkage editor:

INCLUDE SYSLIB(KOCFIN00)

Save a copy of the IDMSINTC source prior to making any changes.

3. Specify NAME=IDMS for DATABASE_COLLECTION in the Global Data Area.
Note: IDMS support does not cover UCF, non-Data-Manipulation-Language (DML) queries through the
IDMS Dedicated Mode facility, because no DML requests are issued from the CICS region.

Chapter 5. Reference 199

 Installing Millennium support
To install Millennium support, you must define the user event monitoring point OMEGBSC to your MCT.
You must also add USER_EVENT_MONITORING and STARTUP_CONTROL to specify the name of the user
event monitoring point.
To install Millennium support, follow these steps:
1. Change the Millennium program M2X000:
a. Add the following lines to the working storage section:

01 OMEG-WORK AREA.
05 OMEG-REQ PIC S9(8) COMP VALUE +7.
05 OMEG-SCRID PIC X(5) VALUE SPACE.

b. Add the following lines after the label L000-Process-Security.

MOVE TS-SCR-SCREEN TO OMEG-SCRID.

CALL KOCRMCLL USING OMEG-REQ OMEG-SCRID.

2. Recompile and re link M2X000, in the following way:

a. Add the rhilev.RKANMOD library to the SYSLIB statement of the link-edit step.
Note: If your RTE uses the SMP libraries, include thilev.TKANMOD in the SYSLIB concatenation.
b. Add the statement INCLUDE SYSLIB(KOCRMCLL) to the link-edit SYSIN.
3. Examine the output of the compile and link-edit for any error messages. Be sure that the KOCRMCLL
reference was resolved during link-editing.

Installing NATURAL support

The OMEGAMON for CICS NATURAL support runs as an exit to the NATURAL Review Data Collector.
Both the NATURAL Review Data Collector and the OMEGAMON for CICS NATURAL support exit must be
link-edited into a NATURAL Shared Nucleus (NSN).
The OMEGAMON for CICS NATURAL support exit is a TP-specific module for the CICS environment, and,
as such, must be included as part of a Single-Environment Shared Nucleus for CICS. Refer to the NATURAL
Operations Manual for more information regarding the NATURAL Shared Nucleus, TP-specific modules,
and Single-Environment Shared Nuclei.
To install NATURAL support, follow these steps:
1. Verify that the OMEGAMON for CICS NATURAL support exit is available. This is program KOCATL00
found in the rhilev.RKANMOD library.
2. It is important to follow the instructions found in the NATURAL Operations Manual for the creation of
an NSN as a Single-Environment Shared Nucleus. OMEGAMON exit RDCOMON must be defined as a
user exit for the Natural Data Collector, for example:

NTRDC ON,EXIT=(RDCOMON),SIZE=2

3. Follow the instructions for link-editing the NATURAL Review Data Collector, NATRDC, into an NSN as
provided by the vendor.
4. Add the following DD statement for the OMEGAMON for CICS load library to the job used to link-edit
the NSN:

//RKANMOD DD DISP=SHR,DSN=rhilev.RKANMOD

Note: If your RTE uses the SMP libraries, add the following DD statement instead:

//RKANMOD DD DISP=SHR,DSN=thilev.TKANMOD

5. Add the following linkage-editor control statement to the linkage-editor input stream after the
INCLUDE statement for NATRDC:

200 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 INCLUDE RKANMOD(KOCATL00)

Installing PCS support

To install PCS support follow these steps. You must also add USER_EVENT_MONITORING and
STARTUP_CONTROL to specify the name of the user event monitoring point
1. Make the following changes to the PCS program DOCSCMAN:
a. Locate the statement

PERFEMP SENTER

b. After the instruction

MVC WKASCNAM,TWASCAM

Add the following instructions if you have PCS V1R2:

ST 13,DFHEIR13
LA 13,DFHEISA
MVC WKAFNCID(4),=F’7’
LA 14,WKAFNCID
LA 15,WKASCNAM
CALL KOCRMCLL,((14),(15)),VL
L 13,DFHEIR13

Add the following instructions if you have PCS V1R3:

MVC WKAFNCID(4),=’7’
LA 14,WKAFNCID
LA 15,WKASCNAM
CALL KOCRMCLL,((14),(15)),VL

2. Assemble and link-edit DOCSCMAN.

a. Add the rhilev.RKANMOD library to the SYSLIB statement of the link-edit step.
Note: If your RTE uses the SMP libraries, include thilev.TKANMOD in the SYSLIB concatenation.
b. Add the statement to SYSIN

INCLUDE SYSLIB(KOCRMCLL)

3. Examine the output of the ASM.

a. Link-edit for any error messages.
b. Make sure the KOCRMCLL sub routine was resolved in the link-edit step.
4. Recycle your CICS region.

Installing SUPRA support

To install SUPRA 2.7 and higher support follow these steps:
1. Add KOCSU27B to CSTK0001 as detailed in sample KOCSU27B.
2. Add KOCSU27A to CSTK0002 as detailed in sample KOCSU27A.
3. Use the sample JCL in the SUPRA PDM Administrator Guide to assemble CSTK0001 and link edit
CSTEXT01 and assemble CSTK0002 and link edit CSTEXT02.
a. When link editing, include the thilev.TKANMOD library in the SYSLIB concatenation sequence and
add the following statement to SYSIN:

INCLUDE SYSLIB(KOCFIN00)

4. Use the sample JCL in the SUPRA PDM Administrator Guide to relink SUPRA PDM interface for the
CSTXCSMT CICS module.

Chapter 5. Reference 201

 Verify that the new CSTXCSMT CICS module is in use in the CICS region.

Installing UFO/Forms support

To install UFO/Forms support, follow these steps.
1. Add an entry to the PPT for KOCUFO00 with the attributes of assembler and resident.
2. Identify KOCUFO00 as an accounting exit to UFO/Forms. You can do this in one of the two following
ways:
• Use the CICS utility UFOINIT. (The change remains in effect only as long as is running.)
• Update the CICS UFMAINIT macro. (The exit is always available.)
For more information about installing UFO/Forms, see the section on Accounting Exits in the UFO/Forms
Customization and Operation Guide.

Umbrella transaction services

CICS business applications can run different functions under a single CICS transaction name. These
applications are often called umbrella applications and they enable you to analyze transactions from a
different perspective.
These applications typically display a general menu of choices or selections, but all their processing is
done under the single transaction name, which is used to call up the application's main menu. Although
efficient in some ways, important details, such as metrics and statistics about the application's functions
in task history and system performance reports, can be difficult to interpret. OMEGAMON for CICS on
z/OS and CICS each have an API feature for replacing the CICS tasks' original transaction names with
more meaningful transaction names.
OMEGAMON for CICS supplies the KOCRMCLL and KOCGLCLL subroutines; these subroutines modify
certain values associated with a transaction.

Using subroutines
This information describes the KOCRMCLL and KOCGLCLL subroutines and how to use them.
Use the KOCRMCLL and KOCGLCLL, subroutines to do the following tasks:
• Supply an additional transaction ID for task analysis, the response time collector, task history collector,
and SMF records
• Supply an additional program name for task analysis, the response time collector, task history collector,
and SMF records
• Supply a different resource name and resource type for task analysis and internal bottleneck analysis
• Supply an additional 32 bytes of data for each task record written to SMF
• Change the Resource Limiting status of the monitored transaction. You can turn resource limiting (RLIM)
off, or on, for the transaction which issues the request. This allows for a temporary suspension of RLIM
processing during the life of a transaction which you might not want RLIM to cancel at that point. Any
activity that occurs during this suspension of RLIM counts toward the totals used later in RLIM warn and
kill threshold calculation. An additional option allows you to query the status of RLIM monitoring for a
given transaction.
• Supply Web Service name and Operation name for SOAP requests processed in CICS to allow displaying
of the transactions related to CICS Web Services in OMEGAMON for CICS for z/OS.
The KOCRMCLL and KOCGLCLL subroutines replace the umbrella service facility from prior releases of
OMEGAMON for CICS. All programs using OMUMBSUB or UMBFIND must be converted to use these new
routines. OMUSEREC is no longer supported.
KOCRMCLL and KOCGLCLL provide similar functions. Their use depends on the CICS environment in which
they are called.

202 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

KOCRMCLL can run as part of any CICS application code, including a CICS task-related user exit. It cannot
be used in a CICS global user exit.
Prior to the call to KOCRMLL, you have to acquire a standard save area. Store register one (holding the
pointer to the parameter list for KOCRMLL) in the correct position in this save area (ST 1,24,(13) or STM
14,12,12(13), where register 13 addresses the new save area). Chain the new save area to the previous
one.
KOCGLCLL can run as part of any CICS application code and any CICS global user exit.
When either KOCRMCLL or KOCGLCLL is started, the fields that are changed stay in effect until a
subsequent call changes or clears them. A field is cleared at the end of a conversation if CONV=YES
is specified in the CICS monitoring control table (MCT). You can retain the field across conversations.
If you want to use these fields for the historical display panels such as the task history and response
time, you must define a user event monitoring point for the basic section. For task analysis and internal
bottleneck analysis, the event monitoring point is not required.
Note: If you want more information, see the KOCAPITX member in the thilev.TKANSAM library.

Subroutine call syntax and parameters

This is the syntax for calling the KOCRMCLL subroutine.

CALL KOCRMCLL,(request,parm),VL

These are the parameters for the KOCRMCLL subroutine call:

request
The full word containing the number of the requested operation. For the list of possible requests, see
Figure 17 on page 204.
parm
The area of storage used to move a value into or a field out of the transaction record. See Figure 17 on
page 204 for the required length, which depends on the request.
VL
The end of the list of parameters.
This is the syntax for calling the KOCGLCLL subroutine:

CALL KOCGLCLL,(workarea,rc,request,parm),VL

The parameters for the KOCGLCLL subroutine call are described in the following list:
workarea
The full word that must be initialized to hexadecimal zeroes the first time the KOCGLCLL subroutine is
used. Subsequent calls to the KOCGLCLL subroutine need to use the same field unaltered.
rc
The full word containing the return code. These are the possible return codes:
0
Normal completion.
4
Invalid request code.
8
OMEGAMON has not initialized in the CICS region. Verify that KOCOME00 is in the PLTPI or enter
the transaction OMEG INIT.
12
Incomplete parameter list provided.
A negative value in rc indicates that KOCOME00 is not available for task related user exit calls. For
example, it is not enabled or not started.

Chapter 5. Reference 203

 request
The full word containing the number of the requested operation. For the list of possible requests, see
Figure 17 on page 204.
parm
The area of storage used to move a value into or a field out of the transaction record. See Figure 17 on
page 204 for the required length, which depends on the request.
VL
The end of the list of parameters. For the KOCRMCLL subroutine, the return code is set in Register 15
for Assembler programs or in the appropriate variables for COBOL and PL1 programs. Figure 17 on
page 204 lists the possible types of requests.

REQUEST NUMBER DESCRIPTION PARAMETER FIELD LENGTH FIELD NAME

--------------------------------------------------------------------------------
2 READ FLAG FIELD 1 MN#FLAG4
3 WRITE FLAG FIELD 1 MN#FLAG4
4 READ UMBRELLA TRANSACTION PSEUDO 4 MN#UMBPTC
5 WRITE UMBRELLA TRANSACTION PSEUDO 4 MN#UMBPTC
6 READ UMBRELLA PROGRAM NAME 8 MN#UMBUSR
7 WRITE UMBRELLA PROGRAM NAME 8 MN#UMBUSR
8 READ WAITING RESOURCE NAME 8 MN#DEXFIL
9 WRITE WAITING RESOURCE NAME 8 MN#DEXFIL
10 READ WAITING RESOURCE TYPE 8 MN#DEXTYP
11 WRITE WAITING RESOURCE TYPE 8 MN#DEXTYP
12 READ USER DATA 32 MN#USRWK
13 WRITE USER DATA 32 MN#USRWK
14 TURN RLIM OFF FOR THIS TRANSACTION 0
15 TURN RLIM ON FOR THIS TRANSACTION 0
16 QUERY THE RLIM STATUS FOR THIS TRANSACTION 4 User Supplied
17 READ SOA DATA 96 MN#SOA
18 WRITE SOA DATA 96 MN#SOA

Note: Requests 14 and 15 do not require a user field. Request 16 requires that the user program provide
a 4 byte field. The results of the query are stored in the field, which you can then inspect. In the case,
where the KOCGLCLL subroutine is used to start requests 14 and 15 the user needs to provide a dummy
user field in the request.
Figure 17. List of Requests for the KOCRMCLL subroutine

Each field is described in the following list:

MN#FLAG4
This flag contains two indicators that you set if you want the values you supply for MN#UMBPTC,
MN#DEXFIL, and MN#DEXTYP to be carried over the end of a transaction conversation. Call the
KOCRMCLL sub routine to read the current field (REQUEST # = 2); set the bit corresponding to the
field you want carried across to 1; and call the KOCRMCLL sub routine to write the field (REQUEST #
=3). Refer to the dsects for the bit settings.
MN#UMBPTC
Set this field with an alternate transaction ID. The Task, Response Time, and History menu paths
display this ID name in place of the actual transaction ID. You can change the value several times
over the course of the task, but the response time collector and task history collector pick up only
the last setting. Changing the value does not cause an individual record to be written. Rather, it
allows you to highlight the phase of the task with the TASK menu option. One popular use of this
field is to supply a meaningful name to a CICS application that runs under a transaction ID used for
many programs. For example, many fourth-generation language packages use one transaction ID to
invoke many applications. By supplying a new transaction ID, you can get a clearer indication of the
application that was running as part of that transaction.
MN#UMBUSR
Set this field with an alternate program name. The Task Details panel (KC2C02D) and the Task History
Details panel (KC2T02D) displays the umbrella pushbutton. Selecting this button displays either panel
Task Umbrella Data (KC2C09D) or panel Task History Umbrella Data (KC2T06D). These panels display
MN#UMBUSR as the umbrella program ID.

204 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

MN#DEXFIL
This field is used in task display and internal bottleneck analysis and represents the resource name
that the task is waiting on. The resource name is normally supplied by CICS. Supplying a new resource
name can give you a clearer indication of the reason for the wait. For example, you might have a
transaction that issues requests to database products. While the transaction is waiting for a service to
complete, it normally appears to be waiting on an z/OS system ECB, which really gives no indication
of the type of wait. By calling the KOCRMCLL subroutine before the request, you can supply a name
that clearly identifies the type of wait, such as a database product name or function type. When the
transaction receives control back from the database product, you can call the KOCRMCLL subroutine
again to clear out this waiting resource name.
MN#DEXTYP
This field is used in task display and internal bottleneck analysis and represents the resource type
that the task is waiting on. The resource type is normally supplied by CICS. This field is used the same
way as MN#DEXFIL.
MN#USRWK
Use this field as a work area for user data.
MN#SOA
Use this field as a work area for SOA data.

Using umbrella services for Web service details

OMEGAMON for CICS on z/OS automatically records the Web service name and Operation name for Web
Service Provider transactions, with Version 4 or higher of CICS Transaction Server. If you are running an
older version of CICS or wish to override the values provided by CICS you can use umbrella services to set
these values.
The KOCRMCLL and KOCGLCLL subroutines are used to enable OMEGAMON for CICS on z/OS to
effectively monitor Web service transactions through the use of the Web Service Name and Operation
attributes. The details on how to use these subroutines are located in the KOCAPITX member of the
TKANSAM library.
To use umbrella services to inform OMEGAMON for CICS on z/OS of the Web service details, issue the
OC@API_SOA_WRITE request type that passes an area mapped by the KOCSOA macro provided in the
TKANMAC library.
The KOCSOA macro defines the Web Service Name as a 32 character field. This should contain the first 32
characters of the Web Service Name padded with blanks. The Operation name is a 64 character field and
should contain the first 64 characters of the Web Service Operation padded with blanks. See Figure 18 on
page 205 for an example how the KOCSOA macro defines these values.
You can use the following example to report these values to OMEGAMON for CICS on z/OS using the CICS
API in the KOCRMCLL subroutine to report SOA data. This example shows how to request the information
about the Web Services Name and Operation from CICS. This does require the DATAREG parameter on the
DFHEIENT macro is either set to register 13 or allowed to default to that value.
Figure 18. A request for information about Web Services Name and Operation from CICS

***------------------------------------------------------------***
*/* CICS STORAGE
***------------------------------------------------------------***
DFHEISTG DSECT
FUNCTION DS CL16
LENGTH DS F
REQUEST DS F
KOCCALL CALL ,(0,0),MF=L
KOCSOA ,
EJECT
***------------------------------------------------------------***
*/* PROGRAM START
***------------------------------------------------------------***
OMEGPROG DFHEIENT
***------------------------------------------------------------***
*/* GET THE FIRST 32 BYTES OF WSNAME
***------------------------------------------------------------***

Chapter 5. Reference 205

 MVC MN#WSNAME,SPACES
MVC LENGTH,=A(L'MN#WSNAME)
EXEC CICS GET CONTAINER('DFHWS-WEBSERVICE') *
INTO(MN#WSNAME) FLENGTH(LENGTH) *
NOHANDLE
CLC EIBRESP,DFHRESP(NORMAL)
BE GETOPER
CLC EIBRESP,DFHRESP(LENGERR)
BNE EXIT
***------------------------------------------------------------***
*/* AND THE FIRST 64 OF THE OPERATION
***------------------------------------------------------------***
GETOPER DS 0H
MVC MN#OPERATION,SPACES
MVC LENGTH,=A(L'MN#OPERATION)
EXEC CICS GET CONTAINER('DFHWS-OPERATION') *
INTO(MN#OPERATION) FLENGTH(LENGTH) *
NOHANDLE
CLC EIBRESP,DFHRESP(NORMAL)
BE TELLOMEG
CLC EIBRESP,DFHRESP(LENGERR)
BNE EXIT
***------------------------------------------------------------***
*/* NOW REPORT TO OMEGAMON
***------------------------------------------------------------***
TELLOMEG DS 0H
MVC REQUEST,=A(OC@API_SOA_WRITE)
CALL KOCRMCLL,(REQUEST,MN#SOA),VL,MF=(E,KOCCALL)
EXIT DFHEIRET
***------------------------------------------------------------***
*/* STATIC DATA
***------------------------------------------------------------***
SPACES DC CL64' '

OMEGAMON for CICS on z/OS also provides the KOCSOAP sample pipeline handler program. Use this
program to report SOA data without having to change any application code. It does require that you
assemble and link the KOCSOAP member found in the TKANSAM library and change the pipeline handler
program.
The following pipeline definition file shows how to ensure the provided handler is started for the Web
Services provided by this pipeline configuration file:

<?xml version='1.0" encoding="EBCDIC-CP-US"?>

<provider_pipeline xmlns="htp://www.ibm.com/software/htp/cics/pipeline"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ibm.com/software/htp/cics/pipeline provider.xsd ">
<service>
<service_handler_list>
<handler>
<program_name>KOCSOAP</program_name>
<handler_parameter_list> </handler_parameter_list>
</handler>
</service_handler_list>
<terminal_handler>
</cics_soap_1.2_handler>
</terminal_handler>
</service>
<apphandler.DFHPITP</apphandler>
</provider_pipeline>

OMEGAMON for CICS (3270) address space

This information describes the OMEGAMON for CICS (3270), which is an address space that is separate
from the CICS address space. OMEGAMON for CICS (3270) can accept commands from either a member
of its parameter library or a z/OS operator’s console.
With these commands you can do any of the following:
• Start the OMEGAMON for CICS (3270) monitoring sessions with a different set of startup parameters for
each session. For example, each session can pass the address of a different, dedicated, local 3270 to
use as its output device.

206 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

• Start the OBVTAM OMEGAMON for CICS (3270) VTAM application. When this program is running under
the OMEGAMON for CICS (3270), any 3270 terminal in your VTAM network (depending on authorization)
can log on to the program and have its own OMEGAMON for CICS (3270) session.
• Display all subtasks currently running under the OMEGAMON for CICS (3270).
• Stop any subtask running under the OMEGAMON for CICS (3270).

OMEGAMON for CICS (3270) operation

You can enter commands to the OMEGAMON for CICS (3270) interface using the CICM command by
performing the following steps.
1. Select U, UTILITIES, from the Main menu.
2. Select M, INTERFACE, from the Utilities menu.
The following panel is displayed on your console:

________________ ZUOCCI VTM CICSPROD V530./I SYSA collector 12:15: 21

> PF1 Help PF3 Back PF4 Main Menu PF7 Up PF8 Down

==============================================================================

> ISSUE COLLECTOR COMMAND

> To issue an OCCI command, replace the > preceding CICM with a hyphen and
> replace DISPLAY with the required OCCI command.

>CICM DISPLAY

> To display console output:

> - Blanks after CONS indicate the main terminal. You may enter a z/OS
> console ID after CONS.
> - Replace 10 after LINE with the number of lines at the end to display.

-CONS Main Console 6A2 ( Id=2 )

line10
+ - 087D0001
+ - 10.42.50 STC08737 IST895I CCCDRM26 08420000 CCCD00
. . . . .
. . . . .
. . . . .

> If a password is required, enter /PWD on the beginning line. At the prompt, enter
> the password.
===============================================================================

Figure 19. Issue Collector Command Menu Panel

3. Follow the instructions on the panel to enter OMEGAMON for CICS (3270) commands.

OMEGAMON for CICS (3270) interface commands

You can enter commands to control the OMEGAMON for CICS (3270) interface with the CICM command.
The CICM command formats the z/OS Modify (F) command allowing you to issue one of the following
DISPLAY, EXEC, HELP, LIST, LOG, START and STOP interface commands.
You can store commands as members in the rhilev.RKANPARU library, then issue:

CICM EXEC mmmmmmmm

where mmmmmmmm is the member name.

To use the stored interface commands, use the following steps:
1. Create a member in the rhilev .RKANPARU library.
2. Use the EXEC command to process the member. You can either enter this command by using MODIFY
or as a command in an EXEC member.
Note: All commands from the console must be preceded by the MODIFY command and the modify ID.

Chapter 5. Reference 207

 You can start the commands in the EXEC members of the rhilev.RKANPARU library in any column
as long as you complete the command word before column 72. (You can continue the command by
placing any character in column 72.)
The following list defines the commands that the OMEGAMON for CICS (3270) supports:
*
Comment, ignored by the OMEGAMON for CICS (3270), must begin in column 1.
DISPLAY
Shows active OMEGAMON for CICS (3270) sub tasks.
EXEC
Runs the commands in the specified member.
HELP
Shows help for all or specific OMEGAMON for CICS (3270) commands.
LIST
Alias of DISPLAY; shows active OMEGAMON for CICS (3270) sub tasks.
LOG
Sends a message to the z/OS console.
START
Starts a OMEGAMON for CICS (3270) subtask.
STOP
Stops a OMEGAMON for CICS (3270) subtask.

OMEGAMON for CICS (3270) comment

In members of the rhilev.RKANPARU library, use an asterisk (*) in column 1 of any line to comment out the
text to follow.
Use a non blank character in column 72 to continue the comment.

DISPLAY command
The DISPLAY command lists all tasks that are currently active. An internal ID is displayed along with the
program name of the task.
An example of an output from the DISPLAY command appears in the following figure.

F cccccccc,DISPLAY
CI0543: THE FOLLOWING TASK IDS ARE ACTIVE:
CI0594: ID=KOCBGR.subtask PROGRAM=KOCBGR
CI0594: ID=KOCRTA.subtask PROGRAM=KOCRTA
CI0594: ID=KOCDEX.subtask PROGRAM=KOCDEX
CI0594: ID=OCU772 PROGRAM=KOCCICS
CI0594: ID=OBVTAM PROGRAM=KOBVTAM
CI0594: ID=XMIT PROGRAM=KOCOCPR

Figure 20. DISPLAY Command Output

Each task has a unique ID. The ID of a subtask associated with a specific CICS region consists of the
program name combined with the CICS job name. That is, subtask in Figure 20 on page 208 is replaced
with the monitored job name. OMEGAMON for CICS (3270) sessions under OBVTAM do not have separate
IDs, and are controlled by the OBVTAM ID. In dedicated mode, OMEGAMON for CICS has the task ID of
OCUcuu, where cuu is the dedicated terminal address.

EXEC command
The EXEC command is used to run the commands in a specific rhilev.RKANPARU member.

F cccccccc,EXEC [mmmmmmmm]

Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) and
mmmmmmmm is the member name.

208 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

The EXEC member contains commands such as START, STOP, and even another EXEC command. When
an EXEC command is processed inside another EXEC member, it is as if all of the commands of the other
EXEC member were placed into the calling EXEC member in the same position as the calling command.
For example, consider the following command:

F cccccccc,EXEC MEMBERA

Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) during your
product configuration.
If MEMBERA contains the following commands:

START KOCCICS,CICS=CICSPROD,UNIT=560,LROWS=255
EXEC MEMBERB

And, if MEMBERB contains the following commands:

LOG * OM/CICS VTAM common interface START - APPL=KOCVTMnn *

START OBVTAM,OM=KOCCICS,CICS=CICSPROD,APPL=KOCVTMnn,UMAX=05

Then the effect of entering F cccccccc,EXEC MEMBERA is the same as if you entered the following
commands:

F cccccccc,START KOCCICS,CICS=CICSPROD,UNIT=560,LROWS=255
F cccccccc,LOG * OM/CICS VTAM common interface START - APPL=KOCVTMnn *
F cccccccc,START OBVTAM,OM=KOCCICS,CICS=CICSPROD,APPL=KOCVTMnn,MAX=05

Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) during your
product configuration. It is also the same effect if you use a single member that contains all of the
commands:

START KOCCICS,CICS=CICSPROD,UNIT=560,LROWS=255
LOG * OM/CICS VTAM common interface START - APPL=KOCVTMnn *
START OBVTAM,OM=KOCCICS,CICS=CICSPROD,APPL=KOCVTMnn,UMAX=05

The maximum number of EXEC commands that can be processed at one time is 10. This helps prevent
EXEC loops, where A EXECs B and B EXECs A.

HELP command
The HELP command displays help for the OMEGAMON for CICS (3270) commands.
You can use the HELP command without an operand to find out the names of all the commands that are
supported by the OMEGAMON for CICS (3270). Issue the command using this format:

F cccccccc,HELP

Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) using the
PARMGEN configuration method.
Figure 21 on page 210 shows the HELP command output.

Chapter 5. Reference 209

 LOG 'HELP' Command
Syntax: HELP command-name

Description: The 'HELP' command is used to display the

help information available on the commands that are used to
control the OMEGAMON interface.

HELP is available for all the commands below:

* - Comment (ignored by the Interface)

EXEC - Execute the commands in the member specified
DISPLAY - Display active Interface subtasks
LIST - Alias of DISPLAY - Display active Interface
subtasks
LOG - Send a message to the MVS Console
START - Start an Interface Subtask
STOP - Stop an Interface Subtask

Figure 21. HELP Command Output

You can use the HELP command to display information about any other command that the OMEGAMON
for CICS (3270) interface processes by following HELP with the name of a specific command. If the
command name is not specified, is unrecognized, or is the HELP command used by itself, OMEGAMON for
CICS displays the help text shown in Figure 21 on page 210.
Use the following format to request HELP for a specific command. For example, to request HELP for the
START command, issue the following statement:

F ccccccccc,HELP START

Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) during your
product configuration.

LIST command
LIST is an alternate name for the DISPLAY command. The LIST command shows all tasks that are
currently active.
The output from the LIST command is the same as that shown in DISPLAY Command Output. For a
complete description of this command, see “DISPLAY command” on page 208.

LOG command
The LOG command is used to send a message to the z/OS console.
The output from the LOG command looks exactly like its input. You can use LOG in an EXEC member to
indicate the name of a command as it is being processed. For example, if you use the LOG command
to enter the following message, that message is displayed at your system console when OMEGAMON is
processing the specified member.

F cccccccc,LOG *** Processing membername ***

Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) during your
product configuration.

START command
Use the START command to start a subtask under the OMEGAMON for CICS (3270).
These are the tasks that you can start:
• Dedicated sessions
• OBVTAM
• RTA
• ONDV
• DEX
• XMIT

210 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Most of the parameters that are specified have defaults taken from the OMEGAMON for CICS (3270) or
from the task being started. You can change some of these defaults by modifying the OMEGAMON user
data module.
If you stop OBVTAM, any OMEGAMON sessions running under it also stop, and you must restart them
manually.
This is the command to start the task history subtask from the z/OS console:

F cccccccc,START KOCBGR,CICS=cccccccc

Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) during your
product configuration.
A subtask can also be started by placing the START command in a member of the rhilev.RKANPARU library
and starting it using the EXEC command.
For examples of the START command for the internal bottleneck collector and response time collector,
see rhilev.RKANSAM(KOCIDEX) and rhilev.RKANSAM(KOCIRTA).
Use the following command to start a dedicated session: (See Table 60 on page 212 for a description of
the parameters.)

F cccccccc,START KOCCICS [,CICS=cccccccc]

[,COLS=nnn]
[,FSCR=cccccccc]
[,LROWS=nnn]
[,MODE=CN1]
[,ROWS=nn]
[,SYS=cccc]
[,UNIT=cuu]
[,USER=cc]

Where ccccccccc is the started task name you specified for the OMEGAMON for CICS (3270) during your
product configuration.
Note: Changes to the FSCR parameter can disable the OMEGAMON for CICS (3270).
An example is provided in rhilev.RKANSAM(KOCIDED).
Use the following command to start OBVTAM:

F cccccccc,START OBVTAM [,APPL=cccccccc]

[,AUP=YES/NO]
[,DATA=cc...cc]
[,LROWS=nnn]
[,MODE=IC1]
[,OM=KOCCICS]
[,PRTCT=cccccccc]
[,PSWD=cccccccc]
[,SYS=cccc]
[,UMAX=nn]
[,USER=cc]

Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) during your
product configuration.
An example is provided in rhilev.RKANPAR(KOCVTMnn).
The application ID specified with APPL=cccccccc must be defined to VTAM. To run multiple copies of
OBVTAM, use a unique APPLID for each copy.
The parameters specified with the START OBVTAM command become the defaults for any OMEGAMON
for CICS (3270) sessions created by OBVTAM in response to LOGON requests.
To change the default value or any other command at LOGON time, use the DATA keyword of the LOGON
command to override it. The CICS parameter (the job name of the target CICS) can be specified through
the DATA keyword at LOGON time, as in the following example.

LOGON APPLID(KOCVTMnn) DATA('CICS=CICSPROD,USER=01')

Chapter 5. Reference 211

 You can specify the items enclosed in brackets ([ ]), but many have defaults that need not be specified.
Table 60 on page 212 shows the START options for OMEGAMON for CICS (3270) and OBVTAM.

Table 60. START options for OMEGAMON for CICS (3270) and OBVTAM
Parameter Value Description Default
APPL cccccccc Up to eight character VTAM application name KOCVTMnn
to be used by OBVTAM. Name must match
the ACBNAME specified in rhilev.RKANPAR
member KOCVTMnn. Must also be specified
in SYS1.VTAMLST.
AUP YES or NO Specifies whether or not the OBVTAM NO
sessions are to be in automatic update
mode.
CICS cccccccc The name of the CICS to be monitored.
COLS 80, 132, or The number of columns on the screen; use Derived from VTAM or
160 for dedicated mode. CICS terminal definition
DATA YES or NO Specifies whether a log on data string is YES
used. DATA=NO allows logon with VTAM
interpret table names.
DC Y or N Specifies whether the OMEGAMON for CICS Y
(3270) compresses the 3270 data stream
before it is sent to the terminal.
FOLD Y or N Indicates whether the password should be Y
folded to uppercase or not.
FSCR cccccccc Specifies the first screen space to be
displayed. The default is ZMENUI.
If the command that you want to
run is a security protected command,
then the AUTHLIB= statement in
RKANPARU(KOMSUPDI) needs to be
commented out and pointed to the
authorized screen space library. This
option allows you to run protected
commands as part of the initialization
screen without entering a password. Verify
that the authorized screen space library
is concatenated into your hi.lev.PROC
DD statement. The authorized screen
space library is not an APF-authorized
data set, rather it is an AUTHLIB data
set. IMPORTANT: Changes to the FSCR
parameter can disable the OMEGAMON for
CICS (3270) user interface.

LROWS 99–9999 The number of logical rows. The LROWS 99

parameter is always larger than or equal to
the ROWS parameter.
MODE CN1 Indicates dedicated mode. Dedicated
IC1 Indicates OBVTAM mode.

OM KOCCICS The OMEGAMON module. KOCCICS

212 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 60. START options for OMEGAMON for CICS (3270) and OBVTAM (continued)
Parameter Value Description Default
PASSPHRASE passphrase Specifies the passphrase support setting. NO
Valid values are PARTIAL, MAX62, FULL, NO/
NONE.
PRTCT cccccccc The password of the VTAM application ID to User-specified
be used by the OMEGAMON VTAM collector.
(Required with VTAM mode if applid has a
password.)
PSWD cccccccc The password required to be entered by the User-specified
terminal user to be able to log on to the
OMEGAMON VTAM collector. If PSWD is not
specified, anyone can log on to it.
ROWS nn The number of rows on the screen; use for Derived from VTAM or
dedicated mode. CICS terminal definition
SAFAPPL secclass Specifies the name of the optional SAF CANDLE
application ID for OMEGAMON 3270 Classic
interface security.
SECCLASS secclass Specifies the name of the SAF security OMCANDLE
class for OMEGAMON 3270 Classic interface
security.
SYS cccc The four character system ID to be displayed sysid
on the INFO-line.
TIMEOUT nn Specifies the number of minutes until 0
OMEGAMON stops the idle VTAM mode
sessions. The value can be any number from
0 through 99. Specify 0 if you do not want
VTAM mode sessions to time out.
UMAX 01–99 The number of sessions the OMEGAMON 5
VTAM collector can have. The more sessions
that are specified, the more storage
required.
UNIT cuu The unit address of the OMEGAMON terminal User-specified
(used for dedicated mode).
USER cc The user profile identifier. /C

STOP command
Use the STOP command to stop an OMEGAMON for CICS (3270) subtask.
To stop an OMEGAMON for CICS (3270) subtask such as OBVTAM, you must specify a task ID with the
STOP command. Find this ID by using the DISPLAY command (described in “DISPLAY command” on page
208), or the LIST command (described in “LIST command” on page 210).
This is an example of the STOP command to stop OBVTAM:

F ccccccccc.STOP OBVTAM

Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) during your
product configuration.
If you stop OBVTAM, any OMEGAMON for CICS (3270) sessions running under it also stop.

Chapter 5. Reference 213

 To stop a subtask, for example, KOCBGR, that is associated with a specific CICS region, issue the
following command:

F cccccccc,STOP KOCBGR.CICS_jobname

Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) during your
product configuration.
Note: You can also stop tasks such as ONDV from the Control Options path, or by entering a fast path; see
Starting and stopping the historical collector. Additionally, in the Classic interface, you can enter a STOP
command from any line, for example:

ONDV STOP

In the e3270UI, you can stop the historical collector from the Task History Status panel, by overtyping the
current Task History Status with Inactive.

Installing multiple OMEGAMON address space pairs

OMEGAMON consists of a pair of address spaces; there is one OMEGAMON for CICS (3270) address
space.
One OMEGAMON for CICS (3270) address space can support approximately 40 to 80 sessions; this
number varies, depending on the region size and other environmental factors. If you experience virtual
storage constraints in OMEGAMON due to the number of concurrent sessions, you can generate multiple
address pairs for a z/OS operating system. If you are a new OMEGAMON user, begin by generating only
one pair of addresses.
OMEGAMON for CICS (3270) associates each CICS address space with a particular OMEGAMON for CICS
(3270) session when you add the following DD statement to both the JCL for the collector and the JCL for
CICS:

//RKC2XMnn DD DUMMY

Where nn is a two digit number from 00 through 15. The default setting is 00.
OMEGAMON for CICS associates any CICS without an RKC2XMnn DD statement with the collector that
either has no RKC2XMnn DD statement or has the RKC2XM00 DD statement.
Note: The RKC2XMnn DD statement is required only when running two or more collector address spaces
of the same version number.
When installing a new version of OMEGAMON for CICS with the existing version, choose which regions are
to be monitored by the new version. These regions need to have the new RKANMOD data set in their JCL.
References to the old RKANMOD data set need to be removed. Also confirm there are no duplicate started
task names or VTAM APPLIDs that conflict with the old version.

Virtual terminal pool considerations

This information describes virtual terminal pool considerations for the OMEGAMON for CICS (3270)
interface.
For the OMEGAMON for CICS (3270) interface, this section describes how to perform the following tasks:
• Modify your virtual terminal pool definitions
• Support OMEGAMON sessions under more than one TSO

Modifying the default virtual terminal pool definition

If you use TSO or ISPF mode and your runtime environment is not sharing libraries with other runtime
environments or with SMP/E, this is the procedure to modify virtual terminal pool definitions.
Note: The procedure in this section applies only to the OMEGAMON for CICS (3270).

214 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Do the following.
1. Review the comments in the following members of the &rtehilev.RKANSAMU library to ensure you
understand the contents and purpose of each member. These are the library members:
• KOBVTPL
• KOBVTPLX
• KOBVT1AP
2. Define your virtual terminals and LOGMODE names to the VTM1 program by updating the KOBVTPL
member in the &rtehilev.RKANSAMU library.
3. Assemble and link edit the KOBVTPL source to create the KOBVTPL load module using the JCL in the
KOBVTPLX member of the &rtehilev.RKANSAMU library. The resulting KOBVTPL load module is stored
in the &rtehilev.KANMODU library.
Note: The &rtehilev.RKANSAMU(KOBVTPLX) job is file tailored and created through PARMGEN.
4. If you modified the terminal definitions (the number of terminals or their names) do the following
tasks:
a. Update the KOBVT1AP VTAM node list member, in the &rtehilev.RKANSAMU library
b. Update your VTAMLST controls accordingly.

Determining when to change virtual terminal pool definitions

The default definition might need to be changed because of any of the following conditions:
• The size of the virtual terminal pool does not meet your needs.
• The names of the virtual terminals do not meet your site’s naming conventions.
• The VTAM LOGMODE name defaults are not appropriate.
Before you make any changes to the number of virtual terminals in the pool, consider the needs of all
OMEGAMON for CICS (3270) users running the same copy of the KOBVTPL load module. Because virtual
terminal pool definitions can be shared by multiple VTAM hosts, consider the maximum expected number
of concurrent TSO and ISPF sessions as you determine the size of the virtual terminal pool.

Sharing virtual terminal pool definitions

To provide support for OMEGAMON for CICS (3270) sessions under more than one TSO (or ISPF), you
must install VTM1 in every VTAM domain that controls a TSO address space.
VTM1 uses a virtual terminal for each OMEGAMON session; KOBVTPL defines this virtual terminal pool.
Normally, each installation of VTM1 includes a virtual terminal pool definition.
The samples in this section assume the following:
• There are two VTAM domains in the network:
– Host Subarea A (HSAA) which runs OMEGAMON and TSO (TSOA)
– Host Subarea B (HSAA) which runs OMEGAMON and TSO (TSOA)
• OMEGAMON users who use ISPF or TSO mode must use the local TSO. This means that users whose
terminals are controlled by VTAM domain HSAA must log on to TSOA and users whose terminal are
controlled by VTAM domain HSAB must log on to TSOB.

Defining the virtual terminal pool to VTM1

The following information describes how multiple VTM1 installations can share a single virtual terminal
pool definition.
In the sample network, if you described that a pool of 10 virtual terminals is required for each host
subarea, the following $VTAPPL statement defines this virtual terminal pool to VTM1.

$VTAPPL APPL#=10,VTAPPL=OBVTM1

Chapter 5. Reference 215

 Specifying network names
The VTAM APPL definition statement permits you to specify a network name and an ACB name.
The network name can differ from the ACB name, which can be useful in situations in which you must
support multiple VTAM hosts.

Specifying ACB names

KOBVTPL defines the ACB names to VTM1, so the VTAM definitions in the KOBVT1AP member must
reflect these names.
The $VTAPPL definition statement determines the ACB names of the virtual terminals, as follows:
• The first portion of each name (up to six characters) is taken from the value of the VTAPPL keyword.
• The two-character suffix is based on the value of the APPL# keyword, which can range from 01–99,
inclusive.
Example:
If a $VTAPPL statement is coded with VTAPPL=OBVTM1 and APPL#=25, a combination of the two
keyword values results in 25 ACB names, OBVTM101 through OBVTM125.

Defining the virtual terminal pool to each domain

After defining virtual terminal pools to VTM1, you must define the virtual terminals to each VTAM domain.
To do so, you can define the local name and the network name separately.
The local name is defined by the ACBNAME keyword in the VTAM APPL definition statement.
The network name is defined by the name field in the VTAM APPL definition statement. In the sample
VTAM APPL definitions that follow, the HSAA network names differ from those of HSAB, but the local
names for each virtual terminal are the same in both host subareas.
Figure 22 on page 216 shows the definition statements for Host Subarea A that correspond to the
$VTAPPL definition statement.

HSAAVTM1 VBUILD TYPE=APPL

HSAAVT01 APPL ACBNAME=OBVTM101,EAS=1
HSAAVT02 APPL ACBNAME=OBVTM102,EAS=1
HSAAVT03 APPL ACBNAME=OBVTM103,EAS=1
HSAAVT04 APPL ACBNAME=OBVTM104,EAS=1
HSAAVT05 APPL ACBNAME=OBVTM105,EAS=1
HSAAVT06 APPL ACBNAME=OBVTM106,EAS=1
HSAAVT07 APPL ACBNAME=OBVTM107,EAS=1
HSAAVT08 APPL ACBNAME=OBVTM108,EAS=1
HSAAVT09 APPL ACBNAME=OBVTM109,EAS=1
HSAAVT10 APPL ACBNAME=OBVTM110,EAS=1

Figure 22. HSAA VTAM Definition Statements

Figure 23 on page 216 shows the definition statements for Host Subarea B that correspond to the
$VTAPPL definition statement.

HSABVTM1 VBUILD TYPE=APPL

HSABVT01 APPL ACBNAME=OBVTM101,EAS=1
HSABVT02 APPL ACBNAME=OBVTM102,EAS=1
HSABVT03 APPL ACBNAME=OBVTM103,EAS=1
HSABVT04 APPL ACBNAME=OBVTM104,EAS=1
HSABVT05 APPL ACBNAME=OBVTM105,EAS=1
HSABVT06 APPL ACBNAME=OBVTM106,EAS=1
HSABVT07 APPL ACBNAME=OBVTM107,EAS=1
HSABVT08 APPL ACBNAME=OBVTM108,EAS=1
HSABVT09 APPL ACBNAME=OBVTM109,EAS=1
HSABVT10 APPL ACBNAME=OBVTM110,EAS=1

Figure 23. HSAB VTAM Definition Statements

216 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 Virtual terminal pool access summary
VTM1 selects virtual terminals from KOBVTPL at run time when OMEGAMON for CICS (3270) session in
TSO or ISPF modes is started. Any changes you make to the default KOBVTPL must be assembled and
link-edited.
Install VTM1 execution time modules (including KOBVTPL) in both host subareas. The most convenient
method is to place these modules in a load library shared by both systems; this allows TSOA and TSOB
users access to OMEGAMON for CICS (3270).

Interfacing with other products for transaction tracking support

OMEGAMON for CICS on z/OS enables you to monitor all the components that a CICS application consists
of. OMEGAMON for CICS on z/OS interfaces with IBM Tivoli Composite Application Manager (ITCAM) for
CICS, V7 and higher and ITCAM for Transactions V7 and higher to correlate these transactions.
ITCAM for CICS is used to track Dynamic Program Link (DPL) requests to or from a CICS program;
it can track requests through CICS Transaction Gateway. ITCAM for CICS provides a correlation for
Service-oriented architecture (SOA) and WebSphere MQ traffic into CICS. ITCAM for CICS also provides
the capability to track CICS transaction routing and function shipping requests.
ITCAM for Transactions helps you determine all the components of a complex transaction.

Starting ITCAM for CICS in a CICS region

OMEGAMON for CICS on z/OS can automatically start ITCAM for CICS in a CICS region.
This is controlled by the TRANSACTION_TRACKING=AUTO value in the <STARTUP_CONTROL> section of
the Global Data Area for OMEGAMON for CICS:

*
<STARTUP_CONTROL>
*
TRANSACTION_TRACKING=AUTO| NOAUTO

The default setting is NOAUTO.

When you specify the TRANSACTION_TRACKING=AUTO value, OMEGAMON for CICS on z/OS attempts to
link to the ITCAM for CICS component and initialize it in the CICS region. You only specify one program in
the CICS PLT (program list table). If the ITCAM for CICS component is installed in the same SMP/E CSI as
OMEGAMON for CICS on z/OS, then no JCL changes are required to CICS to enable ITCAM for CICS. The
JCL that is required for OMEGAMON for CICS on z/OS is sufficient.

Using OMEGAMON for CICS to start or stop ITCAM for CICS in a specific
region
OMEGAMON for CICS on z/OS provides the capability to dynamically start or stop ITCAM for CICS in a
specific region.
This is achieved through the OMEGAMON for CICS (3270) interface. Use the O.X menu option to view the
status of ITCAM in a specific CICS region.

Chapter 5. Reference 217

 ________________ ZCTRK VTM CICSR37L V530./C SYS 11/05/12 14:35:02
> PF1 Help PF3 Back

> A-RTA On B-RTA Off C-RTA Status D-RTA Intervals E-RTA Scaling
> F-ONDV On G-ONDV Off H-ONDV Status I-Bottleneck Ctl J-Wait Reasons
> K-INTR Ctl L-IANL On M-IANL Off N-IANL Settings O-IANL Groups
> P-Collection Q-Shutdown R-RLIM On S-RLIM Off T-RLIM Status
> U-SMF Status V-ATF Filters W-ATF Status X-ITCAM Status
================================================================================
> Transaction Tracking (ITCAM) status

> The current status of ITCAM in the CICS region, The current Global setting
> for transaction tracking and an indication as to whether ITCAM will be
> stopped when OMEGAMON is stopped in the CICS region.

> Changing the command to TRKU allows authorized users to modify status of
> ITCAM in the CICS region and the global setting for transaction tracking.

TRKS
+ Transaction Tracking Control Information
+ TRKSTATE ITCAM for CICS status . : Active
+ TRKGLOB ITCAM started in Global : Yes
+ TRKOMEG Stopped on OMEG SHUT. . : Yes

Figure 24. The OMEGAMON for CICS (3270) interface provides the capability to dynamically enable or
disable ITCAM for CICS in a specific region.

You can use the following commands for the OMEGAMON for CICS (3270) interface:
TRKS
Displays the status of the transaction tracking. The default security level is internal, level=0.
TRKU
Modifies the status from the value that is used in the global data area. The default security level is
internal, level=03.

Default DD Names
This section contains the standard DD names for data sets.

Standard DD names for the OMEGAMON for CICS (3270) address space
The following definitions apply to the DD names found in the OMEGAMON for CICS files for the
OMEGAMON for CICS (3270) address space.
These are standard throughout all Tivoli-supplied JCL, PROCs, and CLISTs.
RKOCPROC
The data sets where OMEGAMON for CICS (3270) screen spaces are read. A data set in the
RKOCPROC concatenation is treated as read-only.
RKOCPCSV
The data set where a site’s OMEGAMON for CICS (3270) screen spaces are written. RKOCPCSV cannot
be concatenated.
RKOCPROF
The data sets where user profiles are read. A data set in the RKOCPROF concatenation is treated as
read-only.
RKOCPFSV
The data set where a site’s user profiles are written. RKOCPFSV cannot be concatenated.
RKANHENU
The data sets that contain the OMEGAMON for CICS (3270) command help panels.
RKANPAR
The data set that contains the commands to start the collector subtask.

218 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

RKLVSNAP
The data set that formatted dumps or summary dumps are directed to in the event of an abend. The
default configuration assigns this to SYSOUT. The value of the SDUMP() parameter determines if these
dumps are used: The SDUMP(N) parameter directs a formatted dump to this dataset; the SDUMP(S)
parameter directs a summary dump; the default value is the SDUMP(Y) parameter, which directs the
dump to a system dump data set (SYS1.DUMPxx).
These are specific to OMEGAMON for CICS on z/OS:
RKC2GLBL
The data set that contains the Global Data Areas, which control the monitoring options for CICS
regions.
RKC2XMnn
This DD DUMMY name is only required if you have more than one OMEGAMON for CICS (3270)
address space; the nn value identifies the OMEGAMON for CICS (3270) . The nn value can be 00 to 15
and defaults to 00 so the RKC2XM00 DD statement is not required.

Chapter 5. Reference 219

220 IBM Z OMEGAMON for CICS: Planning and Configuration Guide
Appendix A. Enabling security for OMEGAMON XE
and OMEGAMON for CICS
The security options you decide to employ can determine tasks you must complete in advance, such as
arrangements you must make with security administrators or accounts you must set up. Your security
decisions can also dictate certain choices during configuration, such as the selection of secure protocols
when configuring communication between components.
Tivoli Management Services and the OMEGAMON XE monitoring agents offer several security options:
• Secure communication between components
• Authorization and authentication of Tivoli Enterprise Portal users (including single sign on capability)
• Authentication of OMEGAMON enhanced 3270 user interface, OMEGAMON for CICS (3270) user
interface
• Authentication of SOAP server users
• Authentication of IBM Tivoli Monitoring Service Console users
• Authorization of z/OS Take Action commands by NetView
For information about enabling security, see "Decision 9: Which security options to enable" which is in the
Planning section of OMEGAMON shared documentation Version 6.3.0 Fix Pack 2.

Securing OMEGAMON for CICS on z/OS Take Action commands

The OMEGAMON for CICS on z/OS has the capability to use Take Action commands against specific CICS
resources. These Take Action commands might be as a result of requests from an OMEGAMON enhanced
3270 user interface request, a Tivoli Enterprise Portal user request, or a defined situation using the Tivoli
Enterprise Portal.
These Take Action commands can be secured using the RTE_SECURITY_CLASS parameter, which is
defined for the OMEGAMON enhanced 3270 user interface. When you specify this class and it is not set to
the reserved name, OMEGDEMO, the OMEGAMON for CICS on z/OS agent uses this class to validate a users
authority to issue commands. The RTE_SECURITY_CLASS parameter is described in OMEGAMON shared
documentation Version 6.3.0 Fix Pack 2.

Resource names used for Take Action commands by the agent

The OMEGAMON enhanced 3270 user interface will validate against the following resource name for Take
Action commands directed at the CICS resource to see if users are authorized to issue the request:

KCP.smfid.cicsname.TAKEACTION

Where smfid and cicsname refer to the location and name of the CICS region that is being acted upon. The
OMEGAMON for CICS on z/OS agent builds upon this name to further qualify the request.
A Take Action command is automatically invoked when a situation becomes TRUE, and is run under the
userID that last created or modified it.
The resource names for the AIDK (KILL AIDS), ICEK (KILL ICES), RLIM, TRACE, and WTO Take Action
commands have no predictable values.
These are the resource names:
• KCP.smfid.cicsname.TAKEACTION.KILL.AIDS
• KCP.smfid.cicsname.TAKEACTION.KILL.ICES
• KCP.smfid.cicsname.TAKEACTION.RLIM
• KCP.smfid.cicsname.TAKEACTION.TRACE

© Copyright IBM Corp. 2004, 2022 221

 • KCP.smfid.cicsname.TAKEACTION.WTO
The CEMT SET Take Action command has many different options. You can define specific profiles to
provide finer granularity for selected options; specify a profile for each individual option.
For example:

KCP.smfid.cicsname.TAKEACTION.SET.CEMT.option

Where option is FILE or PROGRAM.

• KCP.smfid.cicsname.TAKEACTION.SET.CEMT.FILE
• KCP.smfid.cicsname.TAKEACTION.SET.CEMT.PROGRAM
This format forces users to always specify the full command syntax in the Take Action commands. (No
attempt is made to use the CICS abbreviation when building the resource name.)
To provide maximum flexibility in specifying the CEMT SET command and to prevent errors, use a profile
with the CICS abbreviation for these options:
• KCP.smfid.cicsname.TAKEACTION.SET.CEMT.FI*
• KCP.smfid.cicsname.TAKEACTION.SET.CEMT.PROG*
No attempt is made to use the CICS abbreviation for the option when building the resource name, and no
attempt is made to validate that the option you specify is valid for your version of CICS Transaction Server.
Use this generic profile to control all SET commands unless more specific profiles exist:

KCP.smfid.cicsname.TAKEACTION.SET.CEMT.*

When deleting transient data and temporary storage queues, the resource generated contains the name
of the queue being deleted.
The value is the queuename in character form, for the TDDL (TDQ DELETE) Take Action command:
• KCP.smfid.cicsname.TAKEACTION.DELETE.TDQ.queuename
• KCP.smfid.cicsname.TAKEACTION.DELETE.TDQ.*
However, for the TSQD (TSQ DELETE) Take Action command, the value is still the queuename, but it can
be specified in either hexadecimal or character form.
To prevent bypassing of your security environment, you should specify a profile for both forms as in the
following examples:
• KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.HEXhexqueuename
• KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.HEX.*
• KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.queuename
• KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.*
where hexqueuename is the name of the queue in hexadecimal form and queuename is in character form.
When you attempt to delete a temporary storage queue using the hexadecimal queue ID, the request is
first validated using the hex queue ID; if that is allowed or no security decision can be made, the request
is then validated again using the character form of the queue ID. If that is allowed or no decision can be
made, then access is allowed or denied in the following order:
• Hex Queue ID=permitted and Queue ID=permitted → delete request allowed
• Hex Queue ID=no decision and Queue ID=permitted → delete request allowed
• Hex Queue ID=permitted and Queue ID=no decision → delete request allowed
• Hex Queue ID=no decision and Queue ID=no decision → delete request not allowed
Note: If either access is denied or either access query returns an error, the delete request is not allowed.
You enter the following Take Action command:

222 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 CP:TSQD ID=D6D4C5C7C1D4D6D5F1F2F3F4F5F6F7F8 HEX

This command is first validated against the following resource:

KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.HEX.D6D4C5C7C1D4D6D5
F1F2F3F4F5F6F7F8

If that is allowed or no decision can be made, it would be validated against the following resource:

KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.OMEGAMON12345678

These are examples of profile or user permission combinations that allow the command:
• KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.OMEG* ACC(READ)
The first result is no decision and the second is allowed.
• KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.HEX.* ACC(READ)
The first result is allowed, and the second is no decision.
• KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.HEX.* ACC(READ)
KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.OMEG* ACC(READ)

The first and second results are allowed.

These are examples of profile or user permission combinations that would deny the command:

KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.HEX.* ACC(READ)
KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.OMEG* ACC(NONE)
KCP.smfid.cicsname.TAKEACTION.DELETE.TSQ.HEX* ACC(NONE)

In the first example, the first result is allowed and the second is not allowed.
In the second example, no profile and the first and second results are no decision.
In the third example, the first result is allowed and the second result is not validated.
If the character form of the queuename contains special characters (blank, ampersand, asterisk, percent),
these are changed to a question mark for profile comparisons.

Updating CICSplex rules

The resource name that is generated when you update a CICSplex rule is slightly different. The
OMEGAMON enhanced 3270 user interface validates your authority to issue a Take Action command
against a specific CICS region, however, the agent will validate your authority against the CICSplex name
as follows:

KCP.cicsplexname::CICSplex.TAKEACTION.RULES

where cicsplexname is the name of the CICSplex being monitored.

Using generic profiles to define resources

The verification of the resource names allows for the specification of generic profiles. For example:

KCP.smfid.*.TAKEACTION.** ACCESS(READ)

This example enables you to issue Take Action commands against all the CICS regions for a specific LPAR.
Conversely, you could specify:

KCP.*.CICSP*.** ACCESS(READ)

This example, you access to all CICS regions beginning with the letters CICSP on any LPAR.

Appendix A. Enabling security for OMEGAMON XE and OMEGAMON for CICS 223
 If you want access to all CICS resources you would specify:

KCP.** ACCESS(READ)

Security defined in Version 4.2.0

If you specified FTA Security in Version 4.2.0, then OMEGAMON for CICS on z/OS allowed for the use of
Take Action security. If you have specified FTA security using the Configuration Tool in previous releases,
then FTA security would be active, and the parameters used are inherited for releases after V4.2.0. In
this case, however, the format of the resource name will match what was used for the prior version. The
resource names will be the same as described previously except that the format will change from:

KCP.smfid.cicsname.TAKEACTION....

to

cicsname.KCP...

To allow access for the OMEGAMON enhanced 3270 user interface, configure a resource profile as
follows:

KCP.smfid.cicsname.TAKEACTION ACC(READ)

Security considerations
The only consideration for security would be whether or not to continue using the OMEGAMON for CICS
on z/OS FTA security, if it was enabled, or to enable the new Global SAF security for CP: common Take
Action command processing. See “Securing OMEGAMON for CICS on z/OS Take Action commands” on
page 95.

Adding the NetView CNMLINK library to the Tivoli Enterprise

Monitoring Server or agent started task
The NetView for z/OS CNMLINK data set is required to connect to NetView for z/OS.
PARMGEN generates the applicable started task with the following lines commented out. Uncomment the
DD card in the RKANMODL that points to the NetView for z/OS CNMLINK data set:

//******************************************************************
//* RKANMODL DD: CNMLINK
//******************************************************************
//* Uncomment this DD card to specify the IBM Tivoli NetView for z/OS
//* CNMLINK dataset. This dataset is required for the "Forward Take
//* Action commands to NetView for z/OS" support which is enabled.
//* The CNMLINK library must be APF-authorized. Contact your NetView
//* for z/OS system programmer for the dataset name.
//* DD DISP=SHR,
//* DSN=NETVIEW.V5R2M0.CNMLINK
//*

If you are doing a reconfiguration and you did uncomment the DD card that points to the CNMLINK library,
refresh the Tivoli Enterprise Monitoring Server started task in PROCLIB from the RKANSAMU library. The
CNMLINK library must be APF-authorized.

Securing the OMEGAMON for CICS (3270)

The OMEGAMON for CICS component provides an OMEGAMON for CICS (3270) interface security facility.
This section covers implementing security for OMEGAMON for CICS (3270).
To prevent unauthorized use of commands, the OMEGAMON for CICS (3270) is shipped with the internal
security feature as the default. For an added level of security, however, you can set up an interface

224 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

between OMEGAMON for CICS (3270) and an external security package, for example, RACF, CA-ACF2, or
CA-TOP SECRET.
These are the ways to implement OMEGAMON for CICS (3270) security:
• External security for logon and internal security for commands
• External security for logon and external security for commands
• External security for logon and both internal security and external security for commands (using internal
security with the locking feature)
Note: Passphrase support for the OMEGAMON 3270 Classic interface was introduced with APAR
OA57133 (PTF UA98944). When passphrase support is enabled, OMEGAMON implements the
OMEGAMON 3270 Classic interface external security without the use of security exits. For more
information, see OMEGAMON 3270 Classic interface security and How to: Configure passphrase and MFA
support in the OMEGAMON 3270 Classic interface.
Whether you use internal security, external security, or a combination of the two, you can customize the
OMEGAMON for CICS (3270) security table to the needs of your installation.
This section describes the customization procedure and uses the following terms:
Control Statements
Locate and edit the KCIJPSEC job. The RTE_X_SECURITY_EXIT_LIB parameter in the LPAR
configuration profile is pointing to the location. The default is RKANSAMU. The needed control
statements are found in the KCIJPSEC job. Edit this job and change the defaults for internal security or
to specify external security. For more information about this job, see How to: Use KOBSUPDT security
exits with PARMGEN in the OMEGAMON shared documentation.
Update Program
When you have edited the control statements and pressed F3, you are presented with the JCL that
starts the KOBSUPDT program, which updates the OMEGAMON for CICS (3270) security table.
Exit Routine
At initialization, OMEGAMON for CICS (3270) accesses the user security exit routine, which provides
the interface to the external security package. The name of this routine must be specified by the user.
The following samples are provided:
• KOCARACF and KOCBRACF for RACF
• KOCAACF2 for CA-ACF2
• KOCATOPS for CA-TOPSECRET.
When OMEGAMON for CICS (3270) is initialized, it determines whether an exit routine has been installed
for an external security package.
If the exit routine exists, it gets control for those commands that have been marked for external security
and determines authorization through the external security package.
If external security allows the command, OMEGAMON for CICS (3270) does not check internal security.
If external security is not used for the command, internal security takes effect. The OMEGAMON for CICS
(3270) is shipped with certain authorized commands which require an internal security password for
execution.
Note: In this section, the term authorized means allowed to access; it does not refer to APF authorization.

Using internal security for commands

All OMEGAMON for CICS (3270) commands (major, minor, immediate, and INFO-line) have a security
level of 0, 1, 2, or 3. Level 3 provides the highest degree of protection. A setting of 0 means that any user
can run the command.
To activate internal security, you must run the KCIJPSEC JCL job.

Appendix A. Enabling security for OMEGAMON XE and OMEGAMON for CICS 225
 Important: Until you run the KCIJPSEC JCL job, OMEGAMON for CICS (3270) commands are protected
only by the default command table security.
All authorized commands are shipped with a default security level of 3, and all others with a level of 0.
You can change the security level of any OMEGAMON for CICS (3270) command to suit the needs of your
installation. “Updating the security table” on page 108 describes how to do this.
Each security level can have its own password. The level 3 password accesses all levels; the level
2 password accesses levels 2 and 1; the level 1 password accesses only the lowest level. Level 0
commands run without a password.
If you enter a command that requires higher authority than yours, OMEGAMON for CICS (3270) responds
with this message:
OB0921 Security check failed (Internal)

To gain access to the authorized commands, use the /PWD command in this way:
1. Type /PWD on the INFO-line. When you press Enter, OMEGAMON for CICS (3270) responds with this
password prompt:

_ <=== Please enter password

2. Type your password on the INFO-line. The password does not display as you type it.
3. Press Enter. If the PASSWORD ACCEPTED message is displayed, press Enter again. You will then have
access to all authorized commands associated with that password, as well as the less command
levels.
If you are using OMEGAMON for CICS (3270) with an external security package, you can prevent the
use of the /PWD command. See “Using the locking feature” on page 226 for more information.
4. Type the /PWD command on the INFO-line and press Enter. The password prompt is displayed.
5. Do not enter a password; just press Enter; you will see the following text:

_________________ Password level reset

Access to authorized commands is restricted until the password is entered again.

Using the locking feature

The locking feature is a form of external security designed to prevent users from changing their internal
security level with the /PWD command. Their level of authority is set once and only at logon; it can be
fixed to one of four levels (level 0, 1, 2, or 3).
Consider the following when using the locking feature:
• Although the locking feature is implemented in the external security exit routine, it is designed to lock
the user's internal security level. Therefore, it affects only those commands marked as EXTERNAL=NO.
• You must define a user security level in CA-ACF2, RACF, or CA-TOP SECRET as an INITIALn resource,
where n is a number from 0–3, and assign corresponding values to commands in the security update
program (using the LEVEL keyword of the COMMAND control statement).
• The locking feature only disables the /PWD command for supplying internal passwords. You can still use
the /PWD command to logon again to a new external user ID.
• Users assigned INITIAL authority (no value of 0 to 3 attached) are allowed to change their internal
security level by using the /PWD command.
• The locking feature starts checking INITIALn resources at the highest level. If you define INITIAL3 and
INITIAL2, the user is locked to level 3.

RACF routine
To validate a user, the user exit routine checks on the RACF resource class that is defined by the
ICHERCDE macro.

226 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

The resources that allow OMEGAMON for CICS (3270) startup include INITIAL, INITIAL0, INITIAL1,
INITIAL2, and INITIAL3, as shown in the following example:

<Allows /PWD to work>

RDEFINE cccccccc INITIAL UACC(READ)

<Defines security level 0 as unaccessible>

RDEFINE cccccccc INITIAL0 UACC(NONE)

<Defines security level 1 as unaccessible>

RDEFINE cccccccc INITIAL1 UACC(NONE)

<Defines security level 2 as unaccessible>

RDEFINE cccccccc INITIAL2 UACC(NONE)

<Defines security level 3 as unaccessible>

RDEFINE cccccccc INITIAL3 UACC(NONE)

<Locks USER02 to level 2 power>

PERMIT INITIAL2 CLASS(classnme) ID(USER02) ACC(READ)

The variable classnme is the resource class name you defined in “Modifying RACF rules” on page 229.

CA-ACF2 routine
The user exit routine checks the CA-ACF2 resource class to validate a user.
The resources that allow OMEGAMON for CICS (3270) startup include INITIAL, INITIAL0, INITIAL1,
INITIAL2, and INITIAL3. To allow users to change their authorization level with the /PWD command, use
INITIAL. Here are sample definitions:

<Allows /PWD to work for USER01>

ACFNRULE KEY(INITIAL) TYPE(cls) ADD(UID(****************USER01) ALLO

<Locks USER02 to security level 0 commands>

ACFNRULE KEY(INITIAL0) TYPE(cls) ADD(UID(****************USER02) ALLO

<Locks USER03 to security level 1 commands>

ACFNRULE KEY(INITIAL1) TYPE(cls) ADD(UID(****************USER03) ALLO

<Locks USER04 to security level 2 commands>

ACFNRULE KEY(INITIAL2) TYPE(cls) ADD(UID(****************USER04) ALLO

<Locks USER05 to security level 3 commands>

ACFNRULE KEY(INITIAL3) TYPE(cls) ADD(UID(****************USER05) ALLO

The variable cls is the generalized resource class name you defined in “Modifying CA-TOP SECRET rules”
on page 231.
The UID operand is installation-specific in format and content. For information about UID, contact your
security administrator.

CA–TOP SECRET routine

Use the INITIAL n resource to define a internal security level if you are using CA–TOP SECRET.

Using external security

OMEGAMON for CICS (3270) supports external security for all modes of operation. For information on the
implementation, see “Using internal security for commands” on page 225.
External security is supported for both logon and command use. When using external security, you
can logon to OMEGAMON for CICS (3270) only if they are allowed to access the INITIAL resource
name. A resource name of INITIAL0, INITIAL1, INITIAL2, or INITIAL3 might be used to allow logon to
OMEGAMON for CICS and set the internal security level to 0, 1, 2, or 3, respectively.
When you issue a command, OMEGAMON for CICS (3270) performs an external security check if the
following conditions are met:

Appendix A. Enabling security for OMEGAMON XE and OMEGAMON for CICS 227
 • The user exit module name is specified in the security table.
• An external security exit routine is located and loaded.
• External security is specified for the issued command in the security table (using the COMMAND control
statement with the keyword setting EXTERNAL=YES ).
• For VTAM, ISPF, or TSO modes, the library that contains the KOBVTAM load module is APF-authorized.
If any commands are specified for external security checking and an exit routine is not found,
OMEGAMON for CICS (3270) recognizes a possible security exposure and disables those commands
with an internal security level of 0 for the session. Those commands with a level of 1, 2, or 3 are allowed
to run after you enter the internal password, as described in “Using internal security for commands” on
page 225.

Logging on using external security

This section explains special considerations for logging on to OMEGAMON for CICS (3270) using external
security.

VTAM, TSO, or ISPF mode logon panels

When you logon through VTAM, OMEGAMON for CICS (3270) presents a logon panel for the OMEGAMON
VTAM application program, KOBVTAM. The VTAM logon panel also is displayed for ISPF and TSO modes,
because OMEGAMON for CICS (3270) uses the VTAM application program for these modes as well. The
copyright panel you normally see at logon time has additional fields for USERID, PASSWORD, GROUP, and
NEW PASSWORD.
These are the advantages of using the KOBVTAM logon panel:
• The exit routine can cause OMEGAMON for CICS (3270) to stop an unauthorized logon.
• The exit routine makes all security checks based on the user's logon ID and not on the OMEGAMON for
CICS (3270) address space's authority.
If you are in an active VTAM session and you want to alter the external security level of authorization, you
can use the relogon feature discussed in “Accessing security from an active session” on page 228.

Dedicated mode logon

Security in dedicated mode differs from the other modes because, at startup time, there is no user ID or
password associated with the session. Therefore, the only security available by default is internal security.
You must enter the /PWD command, using the re logon feature discussed in the following section in order
to access external security.

Accessing security from an active session

The re logon feature is a function of the /PWD command that enables you to enter your user ID and
password for the external security package from an active OMEGAMON for CICS (3270) session. It is the
facility used in dedicated mode to log on to external security. In VTAM mode, it enables you to alter the
security level without having to bring down a current VTAM session.
Type in the /PWD INFO-line command and your user ID as in this example:

/PWD user01_____OCINIT00;
DED CICSPROD; V300./C SYSA; 05/19/06; 1

Press Enter and type in your external security password at the prompt.
Note these points regarding the re logon feature:
• Do not mark the /PWD command as EXTERNAL=YES in the security table because, in dedicated mode,
you must use /PWD to log on to external security.

228 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

• You can determine in your user exit what the default action will be when the user ID or logon password
supplied is not valid. For example, you can specify the disabling of all OMEGAMON for CICS (3270)
commands marked as EXTERNAL=YES, or you can specify that the session reverts to the previous user
ID. The available options are explained in the sample exit routines.
• If you use the re logon feature and your password has expired, you cannot enter a new one using
the /PWD command.

Implementing external security

To implement external security, follow these steps:
1. Modify the rules in the external security package to interface with OMEGAMON for CICS (3270). See
“Modifying RACF rules” on page 229, “Modifying CA-ACF2 rules” on page 230 or “Modifying CA-TOP
SECRET rules” on page 231.
2. Customize the sample exit routine provided in &rhilev.&rte.RKANSAMU according to the procedure
in “Using OMEGAMON for CICS (3270) security exit routines” on page 232. See “Optional external
security features” on page 117 for a description of the options you can use.
3. Modify and update the security table to specify the commands to be verified by RACF, CA-ACF2, or
CA-TOP SECRET and the name of the module that contains the exit routine. (No default setting is
supplied for the module name.) Follow the steps in “Updating the security table” on page 108.

Modifying RACF rules

This section explains the necessary steps for modifying the RACF rules to interface with OMEGAMON for
CICS (3270).
To modify the RACF rules to interface with OMEGAMON for CICS (3270), follow these steps:
1. Update the resource class description table to define a class name (for example, OC;TIVOLI) using the
ICHERCDE macro call. (Use the same name when you define the resource class in the security exit
routine.) Code the ICHERCDE macro in the following manner:

ICHERCDE CLASS=classnme,
ID=nnn,
MAXLNTH=24,
FIRST=ALPHANUM,
OTHER=ANY,
POSIT=nnn,
DFTUACC=NONE

Values for classnme and nnn are determined by your installation. Additional operands for this macro
might also be required at your installation.
2. Activate the newly defined resource class.
3. Define a resource profile for logging on to OMEGAMON for CICS (3270). Use the TSO RDEFINE
command with a resource of INITIAL. Here is an example of a definition that allows all users to sign
onto OMEGAMON for CICS (3270) and use the /PWD command for internal security (that is, it allows
access only to those commands marked EXTERNAL=NO):

RDEFINE classnme INITIAL UACC(READ)

This definition is the minimum required for logon.

4. Define resource profiles for the commands you want to protect using external security
(EXTERNAL=YES commands). If you want to restrict the use of the /PWD command, see “Using the
locking feature” on page 226.
a. Use the TSO RDEFINE command and specify the OMEGAMON for CICS (3270) command as
the resource. Be certain to specify that only specific users can run the command by setting
UACC(NONE).
b. Use the PERMIT command to define those users who can access the resource (run the command).
Give them READ access.

Appendix A. Enabling security for OMEGAMON XE and OMEGAMON for CICS 229
 The following example shows how to authorize a user to run the PEEK command with RACF:

RDEFINE classnme PEEK UACC(NONE)

PERMIT PEEK CLASS(classnme) ID(USER01) ACCESS(READ)

Note: If the command you want to secure begins with a slash (/) or period (.), the RACF rule you
define must start with a dollar sign ($) instead of the slash (/), or an at sign (@) instead of the period
(.). For example, the command /LOGOUT requires a rule for $LOGOUT.
5. The class name in KOCARACF or KOCBRACF (default is OMCANDLE) is defined on this instruction:

MVC U#CHCLSD,=CL8'OMCANDLE' RESOURCE CLASS NAME

If you change it in the KOCARACF or KOCBRACF module, be sure to also use that name for classnme.
6. Include macro libraries in the assembly of the security exit routine. Use SYS1.MACLIB and
SYS1.AMODGEN as the macro libraries for RACF. In addition, you must include the thilev.TKANMAC
macro library.

TSO/ISPF APF authorization requirements

APF authorization is required for TSO and ISPF modes to initialize with RACF. If this is not done, then a
S282-10 abend code occurs.

Modifying CA-ACF2 rules

To modify the CA-ACF2 rules to interface with OMEGAMON for CICS (3270), follow these steps:
1. If you are running OMEGAMON for CICS (3270) in dedicated or VTAM mode, define the name of the
OMEGAMON for CICS (3270) started task to CA-ACF2.
The started task name you use to run OMEGAMON for CICS (3270) in VTAM mode can have the
MUSASS attribute assigned. This allows CA-ACF2 to verify the individual user authorization rather than
using the OMEGAMON for CICS (3270) address space ID. If STC(NO) is specified, you must run the
OMEGAMON for CICS (3270) in batch with a job name that has the MUSASS attribute.
2. After you install the exit, you must set up a resource class for CA-ACF2 to enable OMEGAMON for CICS
(3270) to make the security checks. Define a generalized resource class name, for example OMS. This
name will be three characters long for generalized resources, but will be prefixed with the letter R
within the security exit. (Use the same name when you define the resource class in the security exit
routine.)
The class name in KOCAACF2 (default is ROMS) is defined on this instruction:

A#ACFCLS DC CL4'ROMS' CHANGE CLASS IF NEEDED

3. Define a CA-ACF2 rule for the INITIAL resource to allow VTAM users to log on to OMEGAMON for CICS
(3270), as in the following example:

ACFNRULE KEY(INITIAL) TYPE(OMS) ADD(UID(****************uid)ALLOW)

The OMS must match the resource class name that you defined. The uid is a user ID or user ID mask. If
you want to restrict the use of the /PWD command, see “Using the locking feature” on page 226.
4. Use the CA-ACF2 rule compiler to define resource rules for the command you want to protect. Specify
the command with the KEY operand.
The following example shows how to authorize a user to run the PEEK command with CA-ACF2. See
your security administrator for information on the format of the string.
Note: If the command you want to secure begins with a slash (/) or period (.), the CA-ACF2 rule you
define must start with a dollar sign ($) instead of the slash (/), or an "at" sign (@) instead of the period
(.). For example, the command /LOGOUT requires a rule for $LOGOUT.
5. Include the CA-ACF2 macro library in the assembly of the routine. In addition, you must include the
thilev.TKANMAC macro library.

230 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Modifying CA-TOP SECRET rules
The following section explains the procedure for modifying the CA-TOP SECRET rules to interface with
OMEGAMON for CICS (3270).
To modify CA-TOP SECRET rules use these steps:
1. Define the OMEGAMON for CICS (3270) address space as a started task in the CA-TOP SECRET STC
record, along with the related main facility ID:

TSS ADD(STC) PROC(cccccccc) ACID(MAIN FACILITY ACID)

Where cccccccc is the started task name you specified for OMEGAMON for CICS (3270) in PARMGEN.
2. Define the OMEGAMON for CICS (3270) a facility to CA-TOP SECRET in the facility matrix table:

FACILITY(USER3=NAME=cccccccc)
FACILITY(cccccccc=MODE=FAIL,ACTIVE.SHRPRF)
FACILITY(cccccccc=PGM=KOB,NOASUBM,NOABEND,NOXDEF)
FACILITY(cccccccc=ID=3,MULTIUSER,RES,WARNPW,SIGN(M))
FACILITY(cccccccc=NOINSTDATA,NORNDPW,AUTHINIT,NOPROMPT,NOAUDIT)
FACILITY(cccccccc=NOTSOC,NOMRO,LOG(INIT,SMF,MSG,SEC9))

Where cccccccc is the started task name you specified for OMEGAMON for CICS (3270) in PARMGEN.
3. Define the OMEGAMON for CICS (3270) facility:

TSS ADD(ACID) FACILITY(cccccccc)

Where cccccccc is the started task name you specified for OMEGAMON for CICS (3270) in PARMGEN.
4. Define a Resource Descriptor Table entry:

TSS ADD(RDT) RESCLASS(OCCANDLE) RESCODE(XX)

The RESCODE is a hexadecimal value of 01–3F. The class name in KOCATOPS (default is OCCANDLE) is
defined on this instruction:

MVC U#CHCLSD,=CL8'OCCANDLE' ALTERNATE RES/CLASS NAME

If you change it in the KOCATOPS module, be sure to also use that name for RESCLASS.
5. To permit access to the OMEGAMON for CICS (3270) command level, enter the following command:

TSS PERMIT(userid) OCCANDLE (INITIAL0)

TSS PERMIT(userid) OCCANDLE (INITIAL1)
TSS PERMIT(userid) OCCANDLE (INITIAL2)
TSS PERMIT(userid) OCCANDLE (INITIAL3)
TSS PERMIT(userid) OCCANDLE (‘INITIAL ‘)

6. Enter the following to enable CA-TOP SECRET to validate commands:

TSS PERMIT(userid) OCCANDLE(XXXX)

Where xxxx is an OMEGAMON for CICS (3270) command that has been defined with EXTERNAL=YES
in the OMEGAMON for CICS (3270) command table.
If you use CA-TOP SECRET to define an initial access to OMEGAMON for CICS (3270), you can specify
EXTERNAL=NO in the control statements.
7. You must also specify the CA-TOP SECRET KOCATOPS interface module to enable the CA-TOP SECRET
interface. Use the TSS PERMIT command to define those users who can access the resource by
running the OMEGAMON command.
The following example shows how to authorize a user to run the PEEK command with CA-TOP SECRET:

TSS PERMIT(userid) OCCANDLE(PEEK)

Appendix A. Enabling security for OMEGAMON XE and OMEGAMON for CICS 231
 Note: If the command you want to secure begins with a slash (/) or period (.), the CA-TOP SECRET rule
you define must start with a dollar sign ($) instead of the slash (/), or an at sign (@) instead of the period
(.). For example, the command /LOGOUT requires a rule for $LOGOUT.

Using OMEGAMON for CICS (3270) security exit routines

The exit routine provides an interface between OMEGAMON for CICS (3270) and the security product.
You can specify any unique name for your routine, but that name must also be specified in the control
statements that update the security table. The exit routine can be shared between systems.
The KOCARACF, KOCBRACF, KOCAACF2, and KOCATOPS are members of the &rhilev.&rte.RKANSAMU
data set that contain models of RACF, CA-ACF2, and CA-TOP SECRET routines. Many installations use
these members without modification, but because security procedures are installation-dependent, they
have been documented with comments to enable you to modify them. They are supplied as examples
only.
Verify that the resource class you define in the exit routine has the same name as the resource class
you defined when modifying RACF, CA-ACF2, or CA-TOP SECRET rules. The &rhilev.&rte.RKANSAMU data
set contains members, KOCJACF2, KOCJRACF, and KOCJTOPS, which supply sample JCL to help you
assemble and link-edit your routine.
You can use the same exit routine to define security for multiple OMEGAMON for CICS (3270) images. Use
the same name on the MODULE= statement for each OMEGAMON for CICS (3270). You can use the value
of the B#DDPRFX field in the $BIA data area as part of a resource name to be used for the OMEGAMON
for CICS (3270) currently in use.
Use the KOCBRACF sample to create resource names that include the CICS Jobname.
If you have a security system other than RACF, CA-ACF2, or CA-TOP SECRET, you can still implement a
security interface using these models. Use the sample RACF, CA-ACF2, or CA-TOP SECRET exits as guides
to see what information is passed to the exit routine and what information is returned to OMEGAMON for
CICS (3270).

Using OMEGAMON for CICS (3270) calling conventions

OMEGAMON for CICS (3270) uses the $UCHECK control block to pass information to the exit routine. The
exit routine also uses $UCHECK to pass information back to OMEGAMON for CICS (3270). The $UCHECK
control block is mapped by the $UCHECK macro. The macro is defined in the KOBGMAC member of
thilev.TKANMAC library.
The U#CHPIA field in the $UCHECK control block points to the address of a 16-byte control block. The
KOCPIA macro, defined in the thilev.TKANMAC library, maps this control block and gives you the CICS job
name the user requested at logon. OMEGAMON for CICS (3270) maintains the control block for the entire
life of the session and gives the installation a 512-byte work area for its own use.
Note: The $UCHECK work area is limited to 512 bytes. If your installation requires a larger work area,
GETMAIN the additional storage required and place the pointer to this GETMAIN area in $UCHECK.
An attempt to enlarge this work area beyond its 512-byte limit in any other way causes an overlay of
essential OMEGAMON for CICS (3270) control blocks, and results are unpredictable. If you modify the
RACF RACROUTE macro, you must GETMAIN at least 512 bytes for use as the WORKA work area.
The user exit module is called by OMEGAMON for CICS (3270) using the following conventions:

Table 61. The naming conventions for the user exit module called by OMEGAMON for CICS (3270)
Name Description
Register 1 Address of parameter list.
Register 13 Address of a standard save area.
Register 14 Return address.
Register 15 Entry point address (in).

232 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 61. The naming conventions for the user exit module called by OMEGAMON for CICS (3270)
(continued)
Name Description
Register 15 Return code (out).

The Parameter list contains Word 1 – Address of control block.

Reviewing OMEGAMON for CICS (3270) calling flow

The following procedure describes the flow for calls from OMEGAMON for CICS (3270) to your user
security exit routine at initialization, during command verification, and at termination:
1. At initialization, when OMEGAMON for CICS (3270) passes control to your user exit routine, the
initialization call is indicated by an I in the U#CHTYP field. This indicates that OMEGAMON for CICS
(3270) requires a logon validation.
a. If the user ID field length is non zero, the user ID and password information are available.
b. If additional information or some form of retry is required, the routine can request a reshow of the
screen, and reset any field lengths to indicate that no data is present (user ID, password, group, or
new password).
To perform a reshow in VTAM mode:
• Set a message into the U#CHMSG field (120 bytes maximum length)
• Set the U@CHRSHO bit in U#CHRESP
• Return to the caller.
The message appears under the panel. Appropriate fields are filled in (original user ID and
password), unless overridden (length = 0).
a. When validation is complete, a return code of 0 from the user exit indicates that the user can be
allowed to log on. Any other return code will cause the session to be aborted.
b. Upon successful logon acceptance, the validation routine might perform resource validation and
optionally assign a command security level (0, 1, 2, or 3) to the user. The default setting is 0.
Place the appropriate number into the U#CHAUT4 field. To force the user to use only this level,
also set the U@CH1LOK bit in U#CHAUT1.
2. During command verification, OMEGAMON for CICS places a C in the U#CHTYP field. At this point,
the user authorization is verified. The decision to allow or not allow a command on the first encounter
cannot be changed on subsequent attempts by the same user unless security is reset with the /PWD
command. However, on each attempt, the user exit is notified, an audit record might be written, and a
customized error message might be issued.
These might be the return codes:
RC = 0
Indicates that the command is allowed (RACF and CA-ACF2).
RC = 4
Indicates that the command is unknown to RACF (RACF only). OMEGAMON for CICS (3270)
allows the command to run. See “Modifying RACF rules” on page 229 for instructions to define
a command to RACF.
RC = 8
Indicates that the command is known to the security package and access is denied (RACF and
CA-ACF2).
3. At re-logon, OMEGAMON for CICS (3270) places an R in the U#CHTYP field to indicate a logon
validation. The processing is the same as at initialization time, except that users cannot enter a new
password or group because OMEGAMON for CICS (3270) does not display a logon panel.

Appendix A. Enabling security for OMEGAMON XE and OMEGAMON for CICS 233
 4. At termination, OMEGAMON for CICS (3270) passes a T to the user's exit routine. You can then do any
termination cleanup required, such as freeing user control blocks and FREEMAINing any GETMAINed
areas.

Modifying the security table

This section describes how to update the security table for both external and internal security and
includes the following topics:
• A review of format rules for control statements
• Detailed explanations of each control statement
• An example of using control statements to update the security table
Security tables are compatible with versions 300 and up. For version 120 and earlier versions, you must
customize your table and rerun the security update utility program.
Table 62 on page 234 is a summary of the available options:

Table 62. Available control statements for updating the security table
Control statement Description
AUTHLIB Specifies an authorized screen space (PROC)
library for initialization that bypasses the security
check.
COMMAND Sets the internal security levels of commands,
marks them for external security, and requests an
audit.
LIST Specifies whether a listing of the current security
settings is to be produced on this run.
MINOR Specifies the security options for minor commands.
MODULE Specifies the name of the module containing the
user's external security exit routine.
PASSWORD Specifies the internal passwords
RESET Clears current settings.
UPDATE Specifies whether OMEGAMON for CICS (3270) is
to perform updating on this run.
SMFNUM Specifies the record number for SMF audit
requests.

Updating the security table

To update the security table, use the Configuration Tool and perform these steps:
1. Access the Modify menu system command security option on the Configure OMEGAMON for CICS
panel.
To change an existing setting for a parameter, you must specify a new setting rather than just blanking
out the old setting. For example, to remove a command from external security checking, change
EXTERNAL=YES to EXTERNAL=NO.
If you are implementing external security, you must enter the MODULE command statement naming
the load module that will contain the exit routine. You must also indicate which commands are to use
external security with the EXTERNAL=YES setting on the COMMAND control statement.

234 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 To remove control from external security, blank out the value of the MODULE= keyword. Remember,
that if you do not change commands marked EXTERNAL=YES to EXTERNAL=NO, those with an internal
security level of 0 are non executable.
2. Submit the job to run KOBSUPDT, the security update utility program.
KOBSUPDT performs the updates to the security table, and generates a list of the edits and, if
requested, a complete list of security information. Successful completion of the job produces this
message:
OB9147 LOAD MODULE TEXT SUCCESSFULLY UPDATED

If the update program flags statements as being in error during an update run, correct the statements
and submit them again.
3. To update the security table, perform either one of the following steps:
a. Recycle the address space for the OMEGAMON for CICS (3270).
b. To update the security table without recycling OMEGAMON for CICS (3270), end the current
session and begin a new one.
Changes made to the security table are effective only after the security update job completes
successfully and a new OMEGAMON for CICS (3270) user session is started. Because the security
table is part of a reentrant load module, all OMEGAMON for CICS (3270) user sessions in an address
space must be stopped before security tables are effective. For example, if five VTAM mode sessions
are active, all of them must stop before new sessions can use the updated security tables.
You must ensure that any changes introduced to a runtime environment's command security table
through the Configuration Tool's KC2XSECU member in INSTDATA are synchronized with any command
security table changes for the same runtime environment done through PARMGEN using the KOCSUPDI
member in the RKANSAMU library, or with the sample job KC2JSEC in the TKANSAM library. See
“Configuring the OMEGAMON for CICS (3270) component” on page 28 for an explanation of the
KOCSUPDI sample security table member in the TKANSAM library.

Reviewing format rules for control statements

These general format rules apply to all control statements:
• Control statements can begin anywhere in the input record, but cannot extend beyond column 72.
• Statements can be in any order in the input stream. The update program processes the statements as
it encounters them, with the exception of the LIST and UPDATE statements, which take effect after all
other input is processed.
• All information for a particular control statement must fit in a single line.
• All input must be in uppercase letters.
• Statements must be in this format:

CONTROLSTATEMENT=CCCCCCCC,KEYWORD1=CCCCCCCC,KEYWORD2=CCCCCCCC

There can be no intervening blanks. The update program treats data that follows a blank as a comment.
The data prints on the edit listing, but is ignored for processing purposes.
• To insert comment lines anywhere in the input stream, place an asterisk (*) in column 1 of the input
record.
• If the update program flags statements as being in error, correct the statements and submit them
again. To change a setting, you must specify a new setting rather than blank out the old setting. This is
especially important to remember when changing a command from EXTERNAL=YES to EXTERNAL=NO.
• OMEGAMON for CICS (3270) does not recognize changes to control statements until the update job
successfully ends and a new OMEGAMON for CICS (3270) user session is started. The control statement
edit listing can indicate successful completion of the update.

Appendix A. Enabling security for OMEGAMON XE and OMEGAMON for CICS 235
 Using control statements to modify the security table
Control statements and their keywords are shown in the following list. Keyword defaults are shown in bold
face type.

AUTHLIB
This control statement specifies the data set name of an authorized screen space library that contains
commands to invoke at OMEGAMON for CICS (3270) address space initialization, bypassing any security
checks. This option lets you run protected commands as part of the initialization screen without entering a
password.
Because all security checking for screens coming from the AUTHLIB data set is bypassed, WRITE access
to this data set might be restricted.
Security checking resumes when any of the following occurs:
• OMEGAMON for CICS (3270) retrieves a screen from an unauthorized library
• OMEGAMON for CICS (3270) retrieves a screen that has been loaded into memory
• You enter any keystroke, including a cursor movement
If you create an authorized screen library and use the OMEGAMON for CICS (3270), security checking
causes initialization to fail when the following items occur:
• OMEGAMON for CICS (3270) pulls a screen containing an authorized command. If you use the
OMEGAMON for CICS (3270), you must leave the .FGO and .VAR commands unprotected.
• OMEGAMON for CICS (3270) pulls a screen space that has been loaded into memory. @ZSCRNDF is the
screen that loads screen spaces into memory.
This is the format of the AUTHLIB control statement:

AUTHLIB=dsname,VOL={volume|NOVOLUME}

Where dsname is the name of the authorized screen library you have created.
AUTHLIB accepts the following keyword:
VOL
Specifies the volume serial where the specified data set is located. This acts as an additional security
measure. You must specify a volume serial number even if the data set is cataloged. The AUTHLIB
statement always requires the VOL keyword. If you do not want the additional volume serial number
checking to be performed, specify NOVOLUME.
Concatenate the data set containing the authorized screens in your RKOCPROC DD statement.
Do not APF-authorize the data set that contains the authorized screens.

COMMAND
This control statement specifies the name of an OMEGAMON for CICS (3270) major, immediate, or
INFO-line command to be protected. Minor commands are protected at the major command level unless
the MINOR control statement is specified.
When you update an INFO-line command, you must use the actual command name and not its alias.
OMEGAMON for CICS (3270) automatically assigns the same protection attributes to all aliases of the
command.
OMEGAMON for CICS (3270) does not check for multiple COMMAND statements for the same command
in the same run. The last COMMAND statement for the command is the one that OMEGAMON for CICS
(3270) processes.
This is the format of the COMMAND control statement:

COMMAND=
{cccc|.ccc|/cccccc}

236 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 [,LEVEL={0|2|3|DISABLE}]
[,EXTERNAL={YES|NO}]
[,AUDIT={ ...}]
WTO
SMF
BOTH
NONE

Where cccc, .ccc, or /cccccc is the name of the OMEGAMON for CICS (3270) command to be protected.
To have the control statement edit listing show the current security settings for a command, enter a
COMMAND=cccc, =.ccc, or =/cccccc statement with no additional operands
COMMAND accepts the following keywords:
LEVEL
Specifies the internal security level to be associated with this command.
Level 0 allows the command to run without an internal security check
Levels 1, 2, and 3 specify that the command runs only if you have previously entered the
corresponding password for that level (or for a higher level) through the /PWD INFO-line command.
DISABLE specifies that OMEGAMON for CICS (3270) is never to run the command.
You can audit attempts to run the command for the session, but you cannot specify internal or
external security.
EXTERNAL
Specifies whether an external security package checks this command. If you specify
LEVEL=DISABLE, OMEGAMON for CICS (3270) ignores the EXTERNAL keyword. If you code
EXTERNAL=YES for a command and no exit routine is available, OMEGAMON for CICS (3270) stops
the command for the session if it has an associated security level of 0, or defaults to internal security
if the command has a security level of 1, 2, or 3. After you specify EXTERNAL=YES, you can change it
only if you specify EXTERNAL=NO and rerun the security update program.
AUDIT
Specifies whether OMEGAMON for CICS (3270) is to audit the command each time a user starts it.
These are the possible values:
WTO
Produces a one-line message on the main console.
SMF
Specifies that OMEGAMON for CICS (3270) write an SMF record. The SMF record number must be
specified in the SMFNUM control statement. If the SMF audit cannot be performed, OMEGAMON
for CICS (3270) defaults to a WTO audit. This option requires APF authorization.
BOTH
Specifies that OMEGAMON for CICS (3270) issue a WTO message to a console and write an SMF
record.
NONE
Specifies no auditing. This is the default setting. If you specify an audit for a disabled command,
you are notified of attempts to run it.

LIST
This control statement specifies whether the update program produces a security file listing. A security
file listing is a complete record of the security table that shows the name of the authorized screen library,
its volume serial number, the name of the user exit module, and all command names along with their
corresponding security information.
It does not list the internal security passwords. If you also specify UPDATE=NO, the listing shows what the
control statements and security information can look like if the update had taken place.
To generate the security file listing independent of edits to the control statements, you can submit
LIST=YES as the only control statement in the input stream.

Appendix A. Enabling security for OMEGAMON XE and OMEGAMON for CICS 237
 Only one LIST statement is allowed per run. The default setting is LIST=NO.
This is the format of the LIST control statement:

LIST={YES|NO}

MINOR
This control statement specifies the name of an OMEGAMON for CICS (3270) minor command to protect.
OMEGAMON for CICS (3270) protects the minor commands independent of the majors. Therefore, any
changes to minor commands apply to all minors with the same name and attributes, regardless of their
major commands.
Access to a minor command requires access to the appropriate major command. If you do not specify an
EXTERNAL keyword, the associated major controls access to this minor command.
No verification is made for multiple MINOR statements for the same minor command in the same run. The
last MINOR statement for the minor takes effect.
This is the format of the MINOR control statement:

MINOR=cccc
[,LEVEL={1|2|3|DISABLE}]
[,EXTERNAL={YES|NO}]
[,AUDIT={WTO|SMF|BOTH|NONE}]

Where cccc is the name of the minor command to be protected.

Refer to the COMMAND control statement for explanations of the keywords.

MODULE
This control statement specifies the name of the module that contains your external security exit routine.
You must specify this parameter for an external security check to take place. There is no default setting.
This is the format of the MODULE control statement:

MODULE=cccccccc

Where cccccccc is the name of the module that contains your external security exit routine. Verify that this
name matches the load module name you specified in the KOCJACF2, KOCJRACF, or KOCJTOPS members
of the &rhilev.&rte.TKANSAM library.
To remove control from external security, blank out the value of MODULE=, run the security update job,
and restart the OMEGAMON for CICS (3270) address space.

PASSWORD
This control statement specifies the 1–8 character password for each internal security level, to be
used with the /PWD command. Use a separate PASSWORD control statement for each security level.
Use unique passwords for each security level. When you enter a valid password for one security level,
OMEGAMON for CICS (3270) allows access to commands secured at that level, and commands secured at
levels less than that.
OMEGAMON for CICS (3270) checks the password for a match in this order:
• Level 1
• Level 2
• Level 3
If you assign the same password to more than one level, OMEGAMON for CICS (3270) matches it only at
the lowest level, and denies access to commands protected at higher levels.
This is the format of the PASSWORD control statement:

238 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 PASSWORD=password,LEVEL={1|2|3}

Where password is the unique password for this level.

The PASSWORD control statement accepts the following keyword:
LEVEL
Specifies the security level associated with this password. Levels 1, 2, and 3 specify that the
command runs only if you have previously entered the corresponding password for that level (or
for a higher level) through the /PWD INFO-line command. A LEVEL statement is always required for a
password.

RESET
This control statement clears the current settings of the other control statements. Reset commands
remain unprotected unless you specify new settings with the appropriate control statements and rerun
the update program.
Only one RESET statement is allowed per run.
This is the format of the RESET control statement:

RESET=cccccccc

Where cccccccc is one of the following arguments:

ALL
Clears settings for all control statements and all keywords in the OMEGAMON for CICS (3270) security
table.
AUTHLIB
Clears the name and volume serial number of the authorized screen library.
INFO
Clears settings for all INFO-line commands (on the COMMAND control statement). For example, if you
do not want to use the default security levels for INFO-line commands and want to start over, enter
RESET=INFO. For INFO-line commands, this resets all LEVEL settings to security level 0 and also
clears any existing EXTERNAL and AUDIT settings.
MAJOR
Clears settings for all major and immediate commands (on the COMMAND control statement). See
INFO for an example.
MINOR
Clears settings for all minor commands.
MODULE
Clears the name of the user exit routine module.
PASSWORD
Clears the internal passwords.
SLASH
Same as INFO.
SMFNUM
Clears the record number for SMF audits.
YES
Same as ALL.

SMFNUM
This control statement indicates the ID number of the SMF record that OMEGAMON for CICS (3270) can
use for its audit.

Appendix A. Enabling security for OMEGAMON XE and OMEGAMON for CICS 239
 This is the format of the SMFNUM control statement:

SMFNUM=nnn

Where nnn is the SMF record ID number. This ID number assigned to OMEGAMON for CICS (3270) audit
must be from 128 through 255, and must be different from that used by any other application. There is no
default setting.

UPDATE
This control statement indicates the ID number of the SMF record that OMEGAMON for CICS (3270) can
use for its audit.
This is the format of the SMFNUM control statement:

SMFNUM=nnn

This control statement specifies whether OMEGAMON for CICS (3270) updates the control statements
during this run. The UPDATE=NO statement specifies that this run of the security update program might
be a trial run.
Only one UPDATE statement is allowed per run. The default setting is UPDATE=YES.
This is the format of the UPDATE control statement:

UPDATE={YES|NO}

Using control statements to update the security table

This section provides a list of control statements you can use to update the security table and a detailed
explanation of how each control statement causes particular checks to happen.
The following figure shows an example of using control statements to update the security table:

*
*
* Update: USER01: SYSTEMS GROUP
*
COMMAND=PEEK,LEVEL=1
COMMAND=.DSA,LEVEL=3,EXTERNAL=YES,AUDIT=WTO
COMMAND=MLST,EXTERNAL=YES
COMMAND=XMZP,LEVEL=DISABLE,AUDIT=BOTH
COMMAND=XMLS,LEVEL=2
MINOR=JOBS,LEVEL=2
COMMAND=/SAVE,LEVEL=1,AUDIT=NONE
MODULE=MYSECURE
SMFNUM=233
LIST=YES
UPDATE=NO

Explaining control statement settings

The command control statements in the previous figure result in the following settings for the
OMEGAMON for CICS (3270) commands:

Table 63. Explaining control statement settings

Control statement Result
PEEK A user who has specified the internal security level
1 or higher password can run the PEEK command
and its minors. OMEGAMON for CICS (3270) does
not perform external security checking.

240 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 63. Explaining control statement settings (continued)
Control statement Result
.DSA OMEGAMON for CICS (3270) performs external
security checking and writes a message on the
main console each time .DSA is invoked. If external
security is unavailable, only a user who specified
the internal security level 3 password can run .DSA.
MLIST OMEGAMON for CICS (3270) performs external
security checking, but no auditing.
XMZP The command cannot be run. OMEGAMON for CICS
(3270) writes a message on the main console and
writes an SMF record when XMZP is issued. There
is no external security checking.
XMLS A user who has specified either the level 2 or level
3 internal security password can run XMLS.
JOBS JOBS is a minor of the PEEK command is a level
1 authorized command; however, the LEVEL=2
setting on JOBS specifies that only level 2 or 3
users can access it.
/SAVE A user who has specified either the level 1, level 2,
or level 3 password can run the /SAVE command;
it is not audited.
MODULE The name of the module that contains the security
exit routine.
SMFNUM The SMF ID is set as 233.
LIST YES indicates that OMEGAMON for CICS (3270)
produces a listing.
UPDATE NO indicates that OMEGAMON for CICS (3270)
does not update the security table. This is a trial
run.

Security update program listing

The security update program produces a listing of the control statement modifications. If you specify the
LIST=YES control statement, an additional report is produced that includes all security information.
The security update program listing consists of these parts:
• Header
• Control statement edit listing
• Security file listing
• Security update program trace
The Header part contains the following information:
• Data set name where the load module resides
• Module name of the security table (OICMDccc)
• OMEGAMON for CICS (3270) version number (nnn) in the format VnnnCOM
• Messages indicating successful completion of the job or error conditions, for example, a failure to open
the SYSLIB data set or read the security table

Appendix A. Enabling security for OMEGAMON XE and OMEGAMON for CICS 241
 The Control statement edit listing part contains the update report, which has a listing of the control
statements that have been edited. The listing shows the previous contents (except for previous
passwords), as well as the new contents. If you specified UPDATE=YES, OMEGAMON for CICS (3270)
reports the date and time of the previous update.
This is a typical control statement listing:

OBSECUP 1.2-- SECURITY UPDATE PROGRAM----

*** CONTROL STATEMENT

EDIT ***

AUTHLIB=rhilev.RKOCPROC,VOL=NOVOLUME
PREVIOUS CONTENTS =
NEW CONTENTS = rhilev.RKOCPROC
NOVOLUME

* CHANGE THE PASSWORD FOR LEVEL 3 COMMAND ACCESS

PASSWORD=TIVOLI3,LEVEL=3
PREVIOUS CONTENTS = ********
NEW CONTENTS = TIVOLI3

* DISPLAY SECURITY INFORMATION FOR THE PEEK COMMAND

COMMAND=PEEK
PREVIOUS CONTENTS = 3 B NEW CONTENTS = 3
B

* DISPLAY SECURITY INFORMATION FOR MINOR JOBS

MINOR=JOBS
PREVIOUS CONTENTS = 0EW NEW CONTENTS = 0EW

* PROTECT MZAP COMMAND

The codes for the PREVIOUS CONTENTS and NEW CONTENTS of commands are positional. There are
three positions:
1. The first position shows the number of the internal security level or an asterisk (*) if the command has
been DISABLED.
2. The second position shows the external security option:
E
Use external security for this command.
b
Blank specifies no external security.
3. The third position shows the auditing option:
W
Audit this command through WTO.
S
Audit this command through SMF
B
Audit this command through WTO and SMF
b
Blank specifies no auditing
If you specify the LIST=YES statement anywhere in the input stream, the Security file listing generates
a complete listing of the security information, including the name of the authorized screen library and its
volume serial number, the name of the external security user exit module, the SMF record number, and
all of the commands along with their security information. The listing does not show the internal security
passwords.
TYPE specifies the following types of OMEGAMON for CICS (3270) commands:

242 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 Table 64. TYPE specifies these commands
Command type Description
C Major
I Immediate
S Slash (info line)

The security level follows the command. An asterisk (*) indicates that a command has been disabled.
Minor commands are listed underneath their corresponding majors.
The Security update program trace part indicates whether an update has successfully completed.
The following example shows a typical trace:

OBSECUP
1.2-- SECURITY UPDATE PROGRAM--

OB9145 OBSELW00 CALLED TO WRITE cccccccc.

OB9148 SYSLIB DCB CLOSED SUCCESSFULLY
OB9147 LOAD MODULE TEXT SUCCESSFULLY UPDATED
OB9150 SYSLIB DCB CLOSED
OB9269 OBSECUP ENDED

Optional external security features

This section explains the options you have for implementing external security packages, for example,
RACF or ACF2.
It contains the following items:
• Customization of error messages
• Password updating
• Audit suppression
• Supplement command tracking
You can set up your user exit routine to use any of the options we discuss in this section. Remember
that you can also use the control options that the security package supplies, such as SHIFT validation
and SOURCE validation. Mark the commands, EXTERNAL=YES, and implement the option as the security
package directs.

Customizing error messages

To suit your individual requirements, your site can create custom error messages to display when a user
has insufficient authority, or enters an invalid user ID or password.
Restrictions: The user security message can be up to 120 bytes long, except for INFO-line messages (for
example, /PWD re-logon messages), which can be a maximum of 60 bytes.

Giving password update capability

You can give the user the capability of interactive communication when logging on to external security.
Example: For example, if a user logs on with an expired password, the security exit might prompt the user
for a new password and update the security database.
Restrictions: Password update capability is not available when logging back on with the /PWD command.

Suppressing auditing
OMEGAMON for CICS (3270) gives you the flexibility of suppressing WTO or SMF auditing.

Appendix A. Enabling security for OMEGAMON XE and OMEGAMON for CICS 243
 Example: At initialization or re-logon, your exit routine might set a flag in the $UCHECK control block to
indicate WTO or SMF suppression.
Restrictions: There are no restrictions.

Supplement command tracking

In addition to the WTO and SMF audits available with OMEGAMON for CICS (3270), you can use the audit
features of the external security package to supplement command tracking.
Examples: The RACF Report Writer and ACF2 ACFRPT utility programs are examples of this supplemental
audit capability.
Restrictions: There are no restrictions.

Customizing profiles and security

The OMEGAMON for CICS (3270) profiles control the characteristics of an active OMEGAMON for CICS
(3270) user session. Both the installer and the general user community can create and save these
customized profiles. This section describes the types of profiles, how to create them, and how to use
profile security.

Types of profiles and suffixes

These are the types of OMEGAMON for CICS (3270) interface profiles:
• The IBM Tivoli-supplied profile contains session configuration defaults and default exception analysis
thresholds. It enables you to easily install the OMEGAMON for CICS component without customization
and assures you can always initialize the OMEGAMON for CICS (3270) user session, even if no other
profiles are defined.
• The installation-defined profile enables you, the customizer, to define default settings that are different
from the IBM Tivoli-supplied profile settings. This customized profile becomes the default for all
OMEGAMON for CICS (3270) user sessions at your installation. It takes precedence over the IBM
Tivoli-supplied profile.
• The user-defined profile allows individual OMEGAMON for CICS (3270) users to create one or more
profiles to customize their individual OMEGAMON for CICS (3270) user sessions. It takes precedence
over the installation and IBM Tivoli supplied profiles.
Each profile has a unique two character suffix. These are the suffixes for the three types of menu system
interface profiles:
• /C - IBM Tivoli-supplied profile.
• /I - Installation-defined profile.
• cc - User-defined profiles—any two alphanumeric characters.
The profile suffices are used in the following locations:
• On the INFO-line display. The current session's profile suffix appears on the INFO-line next to the
product version number:

______________ ZMENU
VTM LOG OC V510./I SYSA; 05/10/06; 0:3 2:22 5 AB

• On the USER= parameter in your OMEGAMON for CICS (3270) startup JCL or CLIST. For example, if you
want to start a session with the user profile cc, enter USER=cc.
• On the USER=cc option on the ISPF Invocation Menu.
• The user profile-defined suffix (cc) is specified in the Save/Delete option on the Profile menu in the
OMEGAMON for CICS (3270), which saves and deletes user-defined profiles.

244 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Profile search order
When OMEGAMON for CICS (3270) is initialized, it always loads the IBM Tivoli supplied profile, as well
as the installation-defined profiles and user-defined profiles, if they exist. To see which profile to use,
OMEGAMON for CICS (3270) verifies the value on the USER start parameter.
If a user-defined profile (cc) is specified, and OMEGAMON for CICS (3270) is not able to find the user
member, it searches for the /I profile.
If no installation-defined profile is found, it defaults to /C.
If no user-defined profile is specified, OMEGAMON for CICS (3270) uses the installation-defined profile
(/I). If no installation-defined profile is found, the profile defaults to /C, the IBM Tivoli supplied profile.
If /C is specified, OMEGAMON for CICS (3270) uses the IBM Tivoli supplied profile.

Profile storage
The IBM Tivoli supplied profile is stored in the load library and cannot be changed. Therefore, the IBM
Tivoli supplied values are always available as shipped.
OMEGAMON for CICS (3270) stores the installation-defined and user-defined profiles in your site's profile
data set (rhilev.RKC2PFnn), which is referenced by ddname RKOCPFSV.
The installation-defined profile is stored as member OCINSTAL in rhilev.RKC2PFnn. The user defined
profiles are stored as member names in the form OCUSERcc, where cc is the user-defined profile suffix.

Creating an installation defined profile

You can change some or all of the IBM Tivoli supplied profile defaults to customize OMEGAMON for
CICS (3270) for your installation. Customization includes determining, selecting, and saving appropriate
options and thresholds to create an installation-defined profile. It also includes specifying this profile as
the default for your installation.
The Profile Options and Maintenance menu guides you through the customization process. This menu is
available by selecting Profile from the Main Menu of the OMEGAMON for CICS (3270) interface.
You can use some or all of the following profile options to select the defaults for the installation session
and exception analysis options:
• To set global performance options, choose Configure from the Profile Options and Maintenance menu,
and then select OMEGAMON II Performance.
• To set display options, select Configure or Color.
• To control session logging or automatic update mode, select the appropriate session control option
(Background, Auto On or Off, or Logging).
• To set or display exception analysis thresholds, select Exceptions.

Saving an installation defined profile

You can change the setting of any installation defined profile option at any time during the OMEGAMON
for CICS (3270) user session. OMEGAMON for CICS (3270) uses the changed setting for the duration of
the current session. The only exception is the Page fix option. A change to this option does not take place
until the next OMEGAMON for CICS (3270) user session.
If you want to use the changed profile after your OMEGAMON for CICS (3270) user session ends, you
must save the profile by selecting the Save/Delete option of the Profile Options and Maintenance menu.
The saved profile picks up not only the settings you changed, but all of the current settings for all profile
options on the Profile Options and Maintenance menu. Verify that you have changed only those settings
you want to keep in the new profile before saving the profile.
To specify this new profile as the default for your installation, enter USER=/I in your OMEGAMON for CICS
(3270) startup JCL or CLIST.

Appendix A. Enabling security for OMEGAMON XE and OMEGAMON for CICS 245
 If you want to change or delete a profile, select the Save/Delete option on the Profile Options menu also.

Creating a user-defined profile

Individual users might want to create their own profiles to use when they are monitoring CICS with the
OMEGAMON for CICS (3270). For information on creating user-defined profiles, see the IBM OMEGAMON
for CICS on z/OS: OMEGAMON for CICS User's Guide and Reference.

Profile Security
OMEGAMON for CICS (3270) is shipped with the IPRF and IOPT commands unsecured, so that you can
easily install and modify the installation-defined profile. These commands control installation-defined
profiles. After you create an installation-defined profile, you might want to protect it from inadvertent
damage or modification by the general user community. Because each user can create a unique user-
defined profile to override the installation-defined profiles and IBM Tivoli-supplied profiles, he or she has
no need to access the installation-defined profile.
To protect the installation-defined profile, you can use either OMEGAMON for CICS (3270) default internal
security or OMEGAMON for CICS (3270) external security packages, such as RACF or CA-ACF2. The
internal security of this product requires a password for authorization to issue a command. An external
security package checks authorization through the user ID and logon password.

The System Management Facilities audit

This section explains how to generate the System Management Facilities (SMF) audit.
When you generate the SMF audit, verify that both of the following actions occur:
• SMF record exits (IEFU83 and IEFU84) do not suppress the ability of OMEGAMON for CICS (3270) to log
the audit activity records.
• The SMF system parameters specifications (SMFPRMcc) do not suppress the ability of OMEGAMON for
CICS (3270) to log the audit activity records.
Note: The SMF audit has a high overhead, so you should use the audit only with sensitive commands,
such as those that could disrupt the system (for example, OCMD and MZAP).

Understanding the System Management Facilities and audit records

The SMF record contains the following items:
• IBM header (IFASMFR maps)
• Common Header ($CANHDR maps)
You define these maps in the KOBGMAC member of the thilev.TKANMAC library.
• Security audit record ($AUDIT maps)
You define these maps in the KOBGMAC member of thilev.TKANMAC library.
The audit record contains the following items:
• The date/time/system stamp
• The User ID/jobname associated with the session
• The actual command text as you entered it on the OMEGAMON for CICS (3270) panel
Records of minor commands also reference their associated major commands.

Generating the System Management Facilities report

To generate the SMF report, follow these steps:
1. Copy thilev.TKANSAM(KOCASRPT) to rhilev.RKANSAMU(KOCASRPT). Modify the
rhilev.RKANSAMU(KOCASRPT) member as necessary to meet your environmental requirements.

246 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

2. Assemble and link rhilev.RKANSAMU(KOCASRPT).
3. Using IFASMFDP, extract SMF records matching the SMFNUM specified in the Command security table.
4. Use the program linked in step 2 to process the SMF data extracted in step 3.

Appendix A. Enabling security for OMEGAMON XE and OMEGAMON for CICS 247
248 IBM Z OMEGAMON for CICS: Planning and Configuration Guide
Appendix B. Configuring historical data tables
This section discusses historical data and includes information that you can use to determine the disk
space required to support historical data files.
The installation documentation for your OMEGAMON XE products describes the basic disk space
requirements for the Tivoli Enterprise Monitoring Server and the Tivoli Enterprise Portal. These basic
disk space requirements do not include additional space that is required for maintaining historical data
files. Because of the variations in client distributed systems, system size, number of managed systems,
and so on, it is difficult to provide actual additional disk space requirements necessary for historical data
collection. This section provides the system administrator with basic record sizes for the tables available
for historical data collection in the OMEGAMON enhanced 3270 user interface and it also provides sample
space estimates.

Historical data collection

Historical data collection involves the periodic sampling of selected attribute groups to support
investigation of past problems and performance analysis. This is an optional feature that is enabled
through the Tivoli Enterprise Portal or the OMEGAMON enhanced 3270 user interface.
The following historical data collection facilities are available for all OMEGAMON XE agents:
• Short-term or near-term history: recently sampled data stored in the persistent data store at the
monitoring agent on z/OS
• Long-term or warehoused history: an optional feature that stores older data in the Tivoli Data
Warehouse on a Windows, Linux, or UNIX system. The Summarization and Pruning agent can be used to
manage this data
There is also an historical data collection (Task History Data) that is available for the OMEGAMON for CICS
agent only. The data for the Task History Data collection is stored separately. See “Configuring task history
data” on page 126 for more information about storing task history data.
The persistent data store (PDS) is a set of physically sequential files used for storing and retrieving near-
term historical data. When the active PDS file becomes full, persistent data store processing switches to
the next empty file and checks to see if any empty PDS files remain. If there are no more empty files,
processing empties the file that contains the oldest data. You can configure the number of PDS files used
and the amount of storage allocated to them if the default settings are not sufficient for your environment.
Sample estimates are provided in “Determining PDS sizes for near-term history collection” on page 122.
Near-term historical data is written to the PDS files by the monitoring agent using its CPU cycles.
Additional CPU cycles are used when the Warehouse Proxy extracts data from near-term history and
transfers it to the Tivoli Data Warehouse. If you have collected a large amount of data in near-term history,
the extraction process will significantly increase the monitoring agent's CPU usage. Deciding how often
to migrate data to the Data Warehouse and when to schedule it is dependent on the amount of data
collected and how much space has been allocated to the PDS for storing near-term history. Data that is
not warehoused by the time the persistent data store becomes full will be discarded.
Information to help you understand the persistent data store and help you decide whether you want to
collect historical data is provided in Decision 8: Whether to collect historical data and how to manage it
which is in the Planning section of OMEGAMON shared documentation Version 6.3.0 Fix Pack 2. Additional
information about the persistent data store is available in Maintaining the persistent data store located in
the Reference section of OMEGAMON shared documentation Version 6.3.0 Fix Pack 2.

© Copyright IBM Corp. 2004, 2022 249

Enabling historical data collection in the enhanced 3270UI
The OMEGAMON enhanced 3270 user interface (enhanced 3270UI) is designed for investigation of
current problems or those that have occurred in the recent past. Therefore, only near-term historical data
can be displayed in the enhanced 3270UI workspaces.
In addition, only a subset of OMEGAMON for CICS on z/OS and OMEGAMON for CICS TG on z/OS attribute
groups are available to configure for historical data collection in the enhanced 3270UI. Historical data
configuration is limited to the subset of groups that can typically be used for problem solving.
Attribute groups that you enable historical collection for using the enhanced 3270UI are also available for
viewing and configuration in the Tivoli Enterprise Portal.
Refer to Decision 8: Whether to collect historical data and how to manage it which is in the Planning
section of OMEGAMON shared documentation Version 6.3.0 Fix Pack 2 for more information about
collecting historical data. Refer to Near-term History in OMEGAMON shared documentation Version 6.3.0
Fix Pack 2: OMEGAMON Enhanced 3270 user interface for more information about viewing and configuring
near-term history in the enhanced 3270UI.

Enabling historical data collection in the Tivoli Enterprise Portal

The Tivoli Enterprise Portal can display historical data stored in the persistent data store and the Tivoli
Data Warehouse. In addition, all attribute groups eligible for periodic sampling can be configured for
historical collection within the Tivoli Enterprise Portal.
An attribute group that you enable historical collection for using the Tivoli Enterprise Portal is available
for viewing and configuration using the OMEGAMON enhanced 3270 user interface (enhanced 3270UI) if
that attribute group is part of the subset of groups available for viewing near-term history in the enhanced
3270UI.
Refer to Decision 8: Whether to collect historical data and how to manage it which is in the Planning
section of OMEGAMON shared documentation Version 6.3.0 Fix Pack 2 for more information about
collecting historical data. Refer to IBM Tivoli Monitoring: Tivoli Enterprise Portal User's Guide for
information about creating historical collections in the Tivoli Enterprise Portal.

Determining PDS sizes for near-term history collection

If the settings for the persistent datastore (PDS) are not sufficient for your environment, you can change
them using PARMGEN. You can adjust the number of files in the PDS and also adjust the amount of
storage allocated to the PDS.
Use the runtime environment parameter RTE_PDS_FILE_COUNT, described in "Common parameters"
in OMEGAMON shared documentation Version 6.3.0 Fix Pack 2: Reference, to set the number of files
in the PDS. Changing this value affects all monitoring agents within the runtime environment. Refer
to OMEGAMON shared documentation Version 6.3.0 Fix Pack 2: Configuring for more information about
configuring your environment.
Use the KC5_PD_CYL parameter to update the PDS storage allocation for OMEGAMON for CICS on z/OS.
Use the KGW_PD_CYL parameter to update the PDS storage allocation for OMEGAMON for CICS TG on
z/OS.
The amount of storage that is required is unique to each environment. The following list shows an
example of factors that may influence how much storage your PDS requires:
• Which attribute groups collect near-term history
• The frequency of collection
• How many days of near-term history you want to store
• The number of monitored CICS regions
• Transaction activity within each monitored region

250 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 At any given time, at least one file in the set of PDS files will be empty to ensure that there is at least one
empty file that can be switched to when the active PDS file becomes full. For estimation purposes, also
assume that, on average, the active PDS file will be approximately 50% full. As a result, on average, 1.5
PDS files contain no data.
To offset this effect, you need sufficient space in the remaining PDS files to support storing all near-term
historical data that you want to collect. Therefore, the Kpp_PD_CYL parameter should be over-specified
in order to ensure that there is an adequate amount of space in the PDS to accommodate the total DASD
space requirement for your near-term history.
To determine an appropriate Kpp_PD_CYL value for your environment, calculate the cylinder space
needed for each available PDS file by dividing the number of available PDS files into the total number of
cylinders required to hold all of the historical data that you want to collect, for example, three days of
near-term history. Then multiply this value by the number of files in the PDS to obtain the Kpp_PD_CYL
value. The calculation is represented in this formula:

((Daily Space CYL x Number of Days to Store) / Number of Available PDS Files) x Number of PDS
Files

where Number of Available PDS Files = Number of PDS Files - 1.5.

Sample estimates are shown in the following information.

Sample PDS estimates for OMEGAMON for CICS on z/OS

This information provides sample estimates for the DASD space required to collect near-term history for
OMEGAMON for CICS on z/OS. Factors in your environment will affect how much space you require.
Table 65 on page 251 shows a sample estimate for the total persistent data store (PDS) disk space
required to support three days of history data, collected at 5 minute intervals for various numbers of
monitored CICS regions. A sample value for KC5_PD_CYL is derived based on the estimates, assuming the
following:
• Six PDS files are allocated.
• The PDS files must be able to contain three days of near-term history.
• The collection interval is every 5 minutes, which is 288 collections each day.
• Near-term history is collected for the attribute groups listed in Table 66 on page 252 and assume the
specifications in that table.
• One cylinder of DASD space can hold approximately 830KB of data.
The Daily Space amounts listed in Table 66 on page 252 are totaled and used to calculate the sample
space estimates in Table 65 on page 251. Numbers were rounded up.

Table 65. Total DASD Space estimates for a varied number of CICS regions
Number of Daily space Total space Total DASD Space per KC5_PD_CYL
monitored (KB) (KB) for 3 days space (CYL) available PDS value for 6 PDS
CICS regions file files
1 16660 49980 61 13.6 82
10 166600 499800 603 134.0 804
20 333200 999600 1205 267.8 1607
50 833000 2499000 3011 669.2 4016

The estimated number of rows and agent row size are dependent on the attribute groups that have been
chosen to be collected and, depending on the attribute group, how much workload has been performed
during the collection interval. Table 66 on page 252 shows the attribute groups selected for this sample
and the estimated number of rows each will provide for one CICS region in one collection interval. The

Appendix B. Configuring historical data tables 251

 space required for a 24 hour period, assuming the collection interval is 5 minutes, is also shown. The Daily
Space amounts are totaled and used to calculate the figures in Table 65 on page 251.
Your environment and which attribute groups you collect near-term history for will affect the amount of
data you collect.

Table 66. OMEGAMON for CICS on z/OS near-term history tables

Attribu Attribute group Agent Estimate Space Per Daily Estimated number of
te name Row Size d Rows Collection Space rows per monitored
group (bytes) (bytes) (bytes) address space each
ID collection interval
CICSB CICSplex Bottleneck 210 11 2310 665280 1 row per detected
NA Analysis wait reason
CON CICSplex Connection 201 20 4020 1157760 1 row per connected
Analysis system
CICSCO CICSplex 136 1 136 39168 1 row
S Connections
Summary
CICSDS CICSplex DB2 118 1 118 33984 1 row
2 Summary
CICSDL CICSplex DBCTL 160 1 160 46080 1 row
S Summary
CICSCD CICSplex Dispatcher 148 1 148 42624 1 row
S Summary
CICSCD CICSplex Dispatcher 148 21 3108 895104 1 row per TCB mode
M TCB Modes
CICSCD CICSplex Dispatcher 152 5 760 218880 1 row per TCB pool
P TCB Pools
CICSCS CICSplex Dynamic 236 15 3540 1019520 15 rows
D Storage Details
CICSIP CICSplex 189 2 378 108864 2 rows
C IPConnection
Analysis
CICSLP CICSplex LSR Pool 162 5 810 233280 1 row per defined LSR
S Status pool, with a maximum
of 8 per interval
MQCON CICSplex MQ 143 1 143 41184 1 row
N Connection Details
KCPPL CICSplex Overview 142 3 426 122688 1 row per CICSplex
X
CICSPP CICSplex Pagepool 311 1 311 89568 1 row
H Summary
KCPWS CICSplex Plex Service 275 100 27500 7920000 1 row per class per
S Class Analysis CICSplex
CICSR CICSplex Region 187 1 187 53856 1 row
OV Overview

252 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 Table 66. OMEGAMON for CICS on z/OS near-term history tables (continued)
Attribu Attribute group Agent Estimate Space Per Daily Estimated number of
te name Row Size d Rows Collection Space rows per monitored
group (bytes) (bytes) (bytes) address space each
ID collection interval
WSS CICSplex Service 283 20 5660 1630080 1 row per class
Class Analysis
CICSST CICSplex Storage 124 15 1860 535680 1 row per storage area
OR Analysis
TRAN CICSplex Transaction 263 20 5260 1514880 1 row per active
Analysis transaction at the
time of each interval
sample
VSAM CICSplex VSAM 240 10 2400 691200 1 row per VSAM file
Analysis

Sample PDS estimates for OMEGAMON for CICS TG on z/OS

This information provides sample estimates for the DASD space required to collect near-term history for
OMEGAMON for CICS TG on z/OS. Factors in your environment will affect how much space you require.
Table 67 on page 253 shows a sample estimate for the total persistent data store (PDS) disk space
required to support three days of history data, collected at 5 minute intervals for various numbers of
monitored CICS TG address spaces. A sample value for KGW_PD_CYL is derived based on the estimates,
assuming the following:
• Six PDS files are allocated.
• The PDS files must be able to contain three days of near-term history.
• The collection interval is every 5 minutes, which is 288 collections each day.
• Near-term history is collected for the attribute groups listed in Table 68 on page 254 and assume the
specifications in that table.
• One cylinder of DASD space can hold approximately 830KB of data.
The Daily Space amounts listed in Table 68 on page 254 are totaled and used to calculate the sample
space estimates in Table 67 on page 253. Numbers were rounded up.

Table 67. Total DASD Space estimates for a varied number of CICS TG address spaces
Number of Daily space Total space Total DASD Space per KGW_PD_CYL
monitored (KB) (KB) for 3 days space (CYL) available PDS value for 6 PDS
CICS TG file files
address
spaces
1 374 1122 2 0.5 3
10 3740 11220 14 3.2 20
20 7480 22440 28 6.3 38
50 18700 56100 68 15.2 92

The estimated number of rows and agent row size are dependent on the attribute groups that have been
chosen to be collected and, depending on the attribute group, how much workload has been performed
during the collection interval. Table 68 on page 254 shows the attribute groups selected for this sample
and the estimated number of rows each will provide for one CICS TG address space in one collection

Appendix B. Configuring historical data tables 253

 interval. The space required for a 24 hour period, assuming the collection interval is 5 minutes, is also
shown. The Daily Space amounts are totaled and used to calculate the figures in Table 67 on page 253.
Note: Some attribute groups are only available for collection if the address space is a Gateway daemon.
Your environment and which attribute groups you collect near-term history for will affect the amount of
data you collect.

Table 68. OMEGAMON for CICS TG on z/OS near-term history tables

Attribu Attribute group Agent Estimate Space Per Daily Estimated number of
te name Row Size d Rows Collection Space rows per monitored
group (bytes) (bytes) (bytes) address space each
ID collection interval
CTGCM CICSTG Connection 110 1 110 31680 1 row (Gateway
S Manager Threads daemon only)
CTGCS CICSTG CICS TS 468 1 468 134784 1 row per connected
D Region Details CICS region (Gateway
daemon only)
CTGCS CICSTG CICS TS 176 1 176 50688 1 row per monitored
S Regions address space
(Gateway daemon
only)
CTGGD CICSTG Gateway 146 1 146 42048 1 row (Gateway
S Daemon daemon only)
CTGRO CICSTG Region 164 1 164 47232 1 row
V Overview
CTGRT CICSTG Transaction 162 1 162 46656 1 row
S Response Time
Summary
CTGWT CICSTG Worker 102 1 102 29376 1 row (Gateway
S Threads daemon only)

254 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Appendix C. Configuring task history data
This material provides post configuration information for OMEGAMON for CICS (3270) task history data.

Collecting OMEGAMON for CICS (3270) task history data

OMEGAMON for CICS on z/OS collects OMEGAMON for CICS (3270) task history data that can be
displayed from the Online Data Viewing panel. To retain historical task records for a CICS region across
OMEGAMON for CICS (3270) sessions, you must create a task history data set for that CICS region. For
each region where you want to allocate a task history data set, enter the CICS region name, primary
cluster allocation (in cylinders), and a description. To use a VSAM linear file for storing task history data,
ensure the global data parameter for the ONLINE_VIEWER option specifies:

DATA_STORE_FILE_NAME=&rhlev..*.RKC2HIST

Multiple CICS regions can share a single global data area module if you supply an asterisk (*) in the data
set name. In this case, the job name of the CICS region is substituted for the asterisk when the task
history collector is started. The task history data set is a VSAM linear data set and can be up to four
gigabytes.
You can use PARMGEN to generate the JCL job that allocates the OMEGAMON for CICS (3270) historical
data set. See the IBM Z OMEGAMON for CICS: Parameter Reference for the parameters associated with
OMEGAMON for CICS (3270) historical data set allocation.
For any CICS region where you do not want to retain historical task records across OMEGAMON for CICS
(3270) sessions, you can bypass this step and use a dataspace for the task history feature. The dataspace
is cleared when CICS stops processing or the task history collector is stopped. To use a dataspace, ensure
the global data area parameter for the ONLINE_VIEWER option specifies:

DSPACE: DATA_STORE_TYPE=DSPACE

© Copyright IBM Corp. 2004, 2022 255

256 IBM Z OMEGAMON for CICS: Planning and Configuration Guide
Appendix D. Detailed procedures for managing the
OMEGAMON for CICS (3270) Global Data Areas
This section contains information about specifying monitoring options for OMEGAMON for CICS (3270).
Updates to the global field helps are maintained in the context help member, KC256DG1, in the
&hilev.TKANCUS library. The values documented in this section were the most current when this
information was created, but the KC256DG1 member always contains the most current descriptions of
the Global Data Area and the standard defaults. You can use ISPF, or a similar interface, or partitioned
data set utility, to list and print this help member.

Overview of the Global Data Area

The Global Data Area sets the values for the monitoring options for OMEGAMON for CICS (3270)
These values are generated during configuration and apply to all OMEGAMON for CICS sessions that are
monitoring the same CICS region. The Global Data Area enables you to set options for OMEGAMON for
CICS features, such as:
• The task history collector
• The historical reporter
• The interval record collector
• The response time collector
To update these values, a CICS system programmer edits a source dataset and runs a verify job.
Furthermore, you can specify whether the CICS regions using this Global Data should deliver transaction
data to the Service Level Analysis feature of the OMEGAMON for CICS agent.
The KC2_CLASSIC_KC2GLB_SRCLIB PARMGEN parameter specifies where the global members are kept.
Global data areas set up performance monitoring collections, such as historical recording for a CICS
region or writing of performance records to SMS. You can update these values dynamically using the
enhanced 3270 user interface or OMEGAMON for CICS (3270); however, the updates will be lost when
you recycle the CICS address space. If you want the changes to be permanent, you must edit the values in
the data set specified by the KC2_CLASSIC_KC2GLB_SRCLIB parameter.
The global data areas, KC2GLBxx, are members of a typical partitioned data set. You can create your own
version by updating the sample provided, then storing it in the same or a separate dataset and copying it
to your selected runtime environments (RTE).
For new PARMGEN-created RTEs (ones not converted from an existing Configuration Tool environment),
specify a common KC2_CLASSIC_KC2GLB_SRCLIB library to store the customized KC2GLB* globals
that can be copied to the different RTEs' RKANPARU libraries referenced in the RKC2GLBL DD of the
KC2_CCnn_CLASSIC_STC. If you are a first time user, you can create your own data set by running a JCL
job provided in the RKANSAMU data set.
For existing RTEs (those created using the Configuration Tool and converted to PARMGEN), the
WKANSAMU(KC2GLBCP) KC2GLB* copy job may be used to copy the customized globals from the
KC2GLB source library specified in the KC2_CLASSIC_KC2GLB_SRCLIB parameter (INSTDATA by default),
to the RKANPARU library referenced in the RKC2GLBL DD of the KC2_CCnn_CLASSIC_STC.
OMEGAMON for CICS is shipped with a pre-defined set of defaults for the Global Data Area in the member
KC2GLB. This member becomes the default for the Global Data Area in the CICS region JCL.
When you configure OMEGAMON for CICS, you can update the monitoring options using the parameters in
the Global Data Area.

© Copyright IBM Corp. 2004, 2022 257

Determining the values for the monitoring options in IBM Z
OMEGAMON for CICS
Use the following tables to determine the values to specify for the monitoring options. The tables list the
groups of tasks and shows the options available for that task.
These task groups are as follows:
• “Global Options” on page 259
• “Startup Controls” on page 261
• “Exception Analysis Intervals” on page 269
• “Database Collection” on page 269
• “Program Tracking” on page 271
• “Bottleneck Options” on page 272
• “User Excluded Transactions” on page 274
• “User Event Monitoring” on page 274
• “CPU Monitoring” on page 277
• “Group Definitions” on page 278
• “Group Elements” on page 279
• “Interval Collector” on page 281
• “Online Viewer” on page 281
• “Resource Limiting” on page 284
• “Resource Limiting Interval” on page 289
• “Response Time collection” on page 290
• “Dedicated Sessions” on page 292
• “Service Level Analysis” on page 292
• “Enabling outbound API request monitoring” on page 293

258 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Global Options
Table 69. Global options information
Parameter to use Definition Default
CONVERSE_TIME Enables you to include or exclude terminal I/O NOIOWAIT,IRWAIT
and/or IRC wait time in calculating the total
response times for conversational transactions.
This value enables MRO users to more
completely isolate total transaction response
times from I/O-related wait time.
Note: CONVERSE_TIME affects only
OMEGAMON for CICS data. It does not
adjust the response time collected by CICS
monitoring.
CONVERSE_TIME accepts one or two
parameters. The default values for the
parameters are indicated.
IOWAIT
Specifies that CICS monitoring include the
time that conversational tasks wait for
terminal input when reporting the total
response time for that task.
NOIOWAIT
Removes the I/O wait time from the
transaction response time, including output
wait time.
IRWAIT
Specifies that CICS monitoring include the
time that tasks wait for IRC-link-related
processing.
NOIRWAIT
Removes the IRC wait time from the
transaction response time.
Note: For RUNTIME and ELAPSED, this global
option impacts statistics and functionality. If
NOIOWAIT is enabled (which it is, by default),
a task running workload for RUNTIME testing
might show lower values in statistics and
warning, but a kill will be performed anyway.

ETE_INTERVAL Specifies the ETE response history sampling 1

interval in minutes. Values range from 1-7200
(5 days).
ETE_FREQUENCY Determines how often End-to-End (ETE) 1
response time monitoring occurs for each LU
monitored. ETE_FREQUENCY=n specifies that
one count takes place every n occurrences of
LU activity (1-255).
MAX_GROUPS Specifies the maximum number of groups 30
(1-30) that you can define for internal
bottleneck collection, the response time
collector, and the interval record collector.

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas 259
 Table 69. Global options information (continued)
Parameter to use Definition Default
MAX_IDS Specifies the maximum number (1-2000) of 50
transaction IDs, program names, LUs, and
terminal IDs for internal bottleneck collection,
the response time collector, and the interval
record collector.
SHUT_OPTIONS Specifies whether IBM Z OMEGAMON for CICS NOPURGE
will purge conversational tasks waiting on
terminal I/O when a non-immediate shutdown
of CICS is performed. KOCOME00 must be
present in the PLT as a shutdown entry.
Possible values are:
PURGE
Causes IBM Z OMEGAMON for CICS
to purge conversational tasks waiting
on terminal I/O when a non-immediate
shutdown of CICS is performed. KOCOME00
must be present in the PLT as a shutdown
entry.
NOPURGE
Does not purge any tasks
OPER
Indicates that the console operator
specifies PURGE or NOPURGE in response
to a WTO.
You can control the purging of tasks during
CICS shutdown through the CICS Shutdown
Purge Option of the IBM Z OMEGAMON for CICS
Classic (3270) interface (fastpath O.Q).

XM_BUFFER_RECORDS Specifies the number of records 100

(1-2,147,483,648) in the buffer that IBM Z
OMEGAMON for CICS uses to accumulate
transaction records within CICS before they
are sent to the response time collector
and the task history collector. This amount
should correspond to the average number
of transactions within a 2-second period.
The default value should be sufficient
unless you see the message "OC0014 XMCR
communication buffer has wrapped for ..." in
the CICS SYSLOG.

260 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Startup Controls
Table 70. Startup controls information
Parameter to use Definition Default
BOTTLENECK_ANALYSIS Specifies whether or not internal bottleneck AUTO
collection starts automatically.
Possible values are:
AUTO
Start internal bottleneck collection
automatically.
NOAUTO
Do not automatically start internal bottleneck
collection. If you specify NOAUTO, you
can start internal bottleneck collection for
the current region through the Bottleneck
Analysis Control panel of the OMEGAMON for
CICS (3270) interface (faspath O.I).
Note: NOAUTO cannot be specified if you also
specify INTERVAL_RECORDING=AUTO.

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas 261
 Table 70. Startup controls information (continued)
Parameter to use Definition Default
CPU_THRESHOLDING Determines whether or not the MAXR exception AUTO
is tripped when CPU consumption exceeds the
MAXCPU threshold. The MAXR exception takes
effect only if you use MAXCPU to specify a
CPU consumption threshold greater than 0. In
addition, CICS version 3.x users must specify
CPU=YES in the MCT to instruct CICS to monitor
CPU consumption.
Possible values are:
AUTO
The MAXR exception is automatically tripped
when the MAXCPU threshold is exceeded.
ENABLE
This setting allows you to activate the
MAXR exception during an OMEGAMON for
CICS session. You can display or change
the global resource limit CPU threshold in
the OMEGAMON for CICS (3270) system.
Select the MAXR option (K) on the Exception
Settings path (under the Profile menu) or
enter fastpath P.A.K. from any panel.
DISABLE
The MAXR exception cannot be activated
during an OMEGAMON for CICS (3270)
session, regardless of CPU consumption
monitoring.
Note: Once a transaction has tripped the MAXR
exception, that transaction will continue to
appear on the Tasks Exceeding Global CPU
Time Limit panel of the OMEGAMON for CICS
(3270) interface, even if you increase the CPU
consumption threshold. Use the more powerful
features of resource limiting instead of MAXR.

DB2_CLOCKS_AND_COUNTERS Specifies whether the DB2 data collector starts AUTO

up automatically. DB2 collector accumulates
elapsed times and counts of DB2 commands for
each CICS transaction.
Possible values are:
AUTO
Specifies that the DB2 data collector starts up
automatically.
NOAUTO
Do not automatically initialize collection.
If you specify NOAUTO, you can dynamically
start and stop DB2 collection through the Control
Database Collectors panel of the OMEGAMON for
CICS (3270) interface (fastpath O.P).

262 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 70. Startup controls information (continued)
Parameter to use Definition Default
DLI_CLOCKS_AND_COUNTERS Specifies whether the DL/I data collector starts AUTO
automatically. The DL/I collector accumulates
elapsed times and counts of DL/I commands for
each CICS transaction.
Possible values are:
AUTO
Specifies that the DL/I data collector starts
automatically.
NOAUTO
Do not automatically initialize collection.
NO
Disable DL/I collection.
Specifying AUTO or NOAUTO enables the
XDLIPRE and XDLIPOST global user exits. You can
dynamically start and stop DL/I collection through
the Control Database Collectors panel of the
OMEGAMON for CICS (3270) interface (fastpath
O.P).
If you specify NO, however, you cannot activate
DL/I collection dynamically.

INTERVAL_RECORDING Specifies whether the interval record collector NOAUTO

starts automatically.
Possible values are:
AUTO
Specifies that the interval record collector
starts automatically.
NOAUTO
Do not start the interval record collector.
You can start the interval record collector through
the Control Interval Recording Collector panel
of the OMEGAMON for CICS (3270) interface
(fastpath O.K).
Note: AUTO requires that
BOTTLENECK_ANALYSIS=AUTO also be specified
in the STARTUP_CONTROL component.

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas 263
 Table 70. Startup controls information (continued)
Parameter to use Definition Default
ONLINE_DATA_VIEWING Specifies whether the task history collector starts AUTO
up automatically.
Possible values are:
AUTO
Indicates that the task history collector starts
up automatically.
NOAUTO
Do not start up the task history collector.
You can start the task history collector through
the Start Online Historical Transaction Viewing
Collector panel in the OMEGAMON for CICS
(3270) interface (fastpath O.F).

RESOURCE_LIMITING Specifies whether OMEGAMON for CICS NOAUTO

automatically monitors tasks for resource limiting
once it is initialized.
Possible values are:
AUTO
Specifies that OMEGAMON for CICS
automatically monitors tasks for resource
limiting once it is initialized.
NOAUTO
Specifies that OMEGAMON for CICS does
not monitor tasks until you explicitly start
resource limiting from an OMEGAMON for
CICS session.
You can start resource limiting through the START
RESOURCE LIMITING panel of the OMEGAMON
for CICS (3270) interface (fastpath O.R).

264 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 70. Startup controls information (continued)
Parameter to use Definition Default
RESOURCE_LIMITING_MSG_DEST Specifies the destination for RLIM messages TDQ
OC8902 and OC8903. Following is a list of
possible resource message destination values:
TDQ
Specifies that RLIM messages OC8902 and
OC8903 are only written to transient data
destination CSSL.
LOG
Specifies that RLIM messages OC8902 and
OC8903 are written to the System Console.
No messages will be written to transient data.
TDL
Specifies that RLIM messages OC8902 and
OC8903 are written to the transient data
destination CSSL and the System Console.
(LOG,WARN)
Specifies that RLIM message OC8902 is
written to the System Console. No messages
will be written to the transient data
destination CSSL.
(TDL,WARN)
Specifies that RLIM messages OC8902 and
OC8903 are written to the transient data
destination CSSL. RLIM message OC8902 is
also written to the System Console.
The current settings may be viewed on the
OMEGAMON for CICS (3270) system's RESOURCE
LIMITING STATUS panel (fastpath O.T).

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas 265
 Table 70. Startup controls information (continued)
Parameter to use Definition Default
RESOURCE_LIMITING_SYSTEM_TASK This parameter allows you to use the WARN NO
S thresholds specified in Resource Limiting to
alert you to any system tasks which exceed
the WARN threshold. It also allows you to
KILL tasks using IBM-provided programs, these
might include CEMT or CICS mirror transactions.
CICS transaction manager determines which
transactions are system tasks.
Possible values are:
NO
Resource Limiting will not KILL or WARN a
transaction which is marked as a system task
or is running a program which begins with
DFH, EYU, DSN, or CSQ.
YES
Resource Limiting will WARN transactions
marked as a system task. It will WARN and
KILL transactions which are currently running
a program which begins with DFH, EYU, DSN,
or CSQ if the limit is exceeded.
Note:
It is not possible to KILL a system task using
Resource Limiting.

RESOURCE_LIMITING_ABEND_CANC Specifies whether the CANCEL option is used by YES

EL RLIM when KILLing a transaction
Possible values are:
YES
Specifies that the CANCEL option is used by
RLIM when KILLing a transaction. This means
that the HANDLE ABEND routine will not be
invoked. Typically this is the desired behavior
as RLIM is designed to prevent excessive
resource consumption and a HANDLE ABEND
routine could, for example, continue the
transaction.
NO
Specifies that the CANCEL option is not used
by RLIM when KILLing a transaction.
Note: RLIM will attempt to KILL a task only once.
If a task continues to process and exceeds other
limits RLIM will take no action for this task.

266 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 70. Startup controls information (continued)
Parameter to use Definition Default
RESOURCE_LIMITING_TRACE_WARN Specifies whether transactions that are warned by YES
ED RLIM will have Application Trace activated for the
task automatically
Possible values are:
YES
Specifies that transactions that are warned by
RLIM will have Application Trace activated for
the task automatically. This will enable the
trace to be viewed from the Task display or
from Online Data viewing once the transaction
ends. This will not affect other Application
Trace settings or filters.
NO
Specifies that Application trace will not be
enabled when RLIM warns a task.

ENABLE_APPLICATION_TRACE Specifies whether OMEGAMON for CICS will be NOAUTO

able to record Application Trace for transactions
running in CICS.
Possible values are:
AUTO
Specifies that OMEGAMON for CICS will
be able to record Application Trace for
transactions running in CICS. This does not
mean that all transactions will be traced. It
refers to the capability to enable trace for a
task from the OMEGAMON for CICS (3270)
system or via Resource Limiting.
NOAUTO
Specifies that OMEGAMON for CICS will not
trace transactions until you explicitly enable
Application Trace from an OMEGAMON for
CICS session.
You can enable Application Trace through the
Application Trace Facility Status panel of the
OMEGAMON for CICS (3270) interface (fastpath
O.W).

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas 267
 Table 70. Startup controls information (continued)
Parameter to use Definition Default
ENABLE_FILE_CONTROL_EXIT Specifies whether global user exits XFCFRIN and NO
XFCFROUT will be initialized. These exits enable
OMEGAMON for CICS to collect file level data for
transactions which access VSAM files.
Possible values are:
NO
Do not enable global user exits XFCFRIN and
XFCFROUT.
YES
Global user exits XFCFRIN and XFCFROUT
are enabled, and OMEGAMON for CICS GLUE
code is enabled at exit points. YES should
typically be specified only in a File Owning
Region.

RESPONSE_TIME_ANALYSIS Specifies whether the response time collector AUTO

starts up automatically.
Possible values are:
AUTO
Specifies that the response time collector
starts up automatically.
NOAUTO
Do not start up the response time collector.
You can start the response time collector during
a session using the START RESPONSE TIME
MONITOR panel of the OMEGAMON for CICS
(3270) interface (fastpath O.A).

AUTO_RESTART Specifies whether, after the OMEGAMON for CICS NO

address space is restarted, OMEGAMON for CICS
is not restarted in the CICS region
Possible values are:
NO
Specifies that after the OMEGAMON for CICS
address space is restarted OMEGAMON for
CICS is not restarted in the CICS region.
YES
Specifies that following a restart of
the OMEGAMONfor CICS address space,
OMEGAMON for CICS will attempt to start
the Online Data Viewing (ONDV) component
to collect information contained within the
OMEGAMON buffers. It will then perform an
OMEG REMOVE and an OMEG INIT to refresh
the OMEGAMON code in the CICS region and
restart the required features.

268 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 70. Startup controls information (continued)
Parameter to use Definition Default
HISTORY_CATCHUP_TIME Specifies the maximum time in seconds (0-300) 0
after a restart of the OMEGAMON for CICS
address space that OMEGAMON will wait for the
Online Data Viewing component to retrieve the
data in the OMEGAMON buffers before starting
the recycle of the code in the CICS region. If
a value of 0 is coded (the default), no attempt
is made to start history prior to recycling the
OMEGAMON code in the CICS region.
TRANSACTION_TRACKING Specifies whether the Transaction Tracking API NOAUTO
will be initialized when the OMEGAMON for CICS
address space is started.
Possible values are:
AUTO
Specifies that the Transaction Tracking API
will be initialized when the OMEGAMON for
CICS address space is started.
NOAUTO
Do not initialize the Transaction Tracking API
when the OMEGAMON for CICS address space
starts. You can also initialize the Transaction
Tracking API through the OMEGAMON for
CICS (3270) system.

Exception Analysis Intervals

Table 71. Exception analysis intervals information
Parameter to use Definition Default
VSAM_MONITORING_INTERVAL Specifies the interval of time for which statistics 15 minutes
concerning VSAM CA splits, CI splits and extents
are collected. Possible values for this field
are 1-1440 minutes. A value of zero means
statistics are collected and evaluated every time
the Region Status or VSAM panels are refreshed.
DUMPS_MONITORING_ Specifies the interval of time for which statistics 15 minutes
INTERVAL concerning system dumps and transaction
dumps are collected. Possible values for this
field are integers from 1-60 minutes.
VIOLATIONS_MONITORING_ Specifies the interval of time for which statistics 15 minutes
INTERVAL concerning storage violations are collected.
Possible values for this field are 1-60 minutes.

Database Collection
In this section of the Global Data Areas values, you can select database products to be monitored. You
can specify ADABAS, Db2, DATACOM, DLI, IDMS, SUPRA, VSAM, MQ, or USREVNT1 for monitoring to get
file I/O statistics by transaction.
VSAM statistics are derived from only EXEC-level file control requests.

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas 269
 To capture DL/I statistics at OMEGAMON for CICS startup, you must specify
DLI_CLOCKS_AND_COUNTERS=AUTO on the STARTUP_CONTROL component. DL/I statistics are from
EXEC-level or CALL-level requests. For local or remote PSBes, the statistics are captured by DBD name.
For DBCTL, the statistics are captured by PSB name.
For ADABAS, CA-DATACOM, IDMS, and SUPRA, you must carry out the installation process as described in
“Installing third-party support” on page 196
If you wish to monitor an event other than the supported Files or Databases, specify the USREVNT1
sub-component.
Selecting the database types also affects the global user exits that will be enabled during this execution of
CICS. The OMEGAMON for CICS code, which runs at XMNOUT and XEIOUT, is activated by default (unless
the CICS_CMF_MONITORING parameter is set to NO). The OMEGAMON for CICS GLUE code is activated
as follows:
• DLI=YES will enable XDLIPRE and XDLIPOST.
• MQ=YES will enable XRMIOUT.
• TRACE=YES will enable XRMIOUT and XPCABND.
Each of the databases previously discussed can be set with the following values:

Table 72. Database collection values information

Parameter to use Definition Default
AUTO_START Specifies that collection starts up automatically. YES
ONDV_WRITE Specifies that statistics are to be available for YES
the task history collector.
SMF_WRITE Specifies whether to write statistics to SMF for NO
batch reporting.
Possible values are:
YES
Writes statistics to SMF for batch reporting.
NO
Does not write to SMF.
TRACE data cannot be written to SMF. If
you select this option the SMF_WRITE=YES
parameter card will be discarded.

DETAIL Specifies report formatting option for ADABAS NO

clock and counter statistics.
Possible values are:
YES
Appends the command code to Database ID
and causes the file number to display the
name of an ADABAS database accessed by a
CICS transaction.
NO
Does not alter the database name.

The following options are also available when USREVNT1 is specified:

270 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 73. Additional database collection options available when USREVNT1 is specified
Parameter to use Definition Default
EVENT Defines a 1-8 character name. This operand None
is used only when USREVNT1 is specified. It
denotes an in-house database name, a user
program name, or any other user event.
FUNCTION Defines a list of 1 to 10 names. Each name None
represents a pair of buckets used to hold
the clock and count statistics related to the
previously defined EVENT. A FUNCTION name
must be between 1 and 8 characters long.

Note: The following example shows EVENT and FUNCTION specifications.

EVENT=MYDBASE
FUNCTION=(BROWSE,ADD,UPDATE,DELETE)

Program Tracking
Table 74. Program Tracking information
Parameter to use Definition Default
ENABLE Specifies whether Program Tracking is enabled. NOAUTO
AUTO: Start Program Tracking automatically.
NOAUTO: Do not automatically start Program
Tracking.
AGGREGATE This option will allow you to see the metrics for NOAUTO
program usage across the entire CICS region.
These metrics are accumulated as of when the
task ends. Looking at programs used within
a CICS region, the Used tab will show the
collective metrics for all programs which have
had data collected since the region started or
program manager statistics were reset.
WRITE_TO_HISTORY This option will record the collected program YES
data for a task to Task History. This will provide
the Programs tab when looking at the details for
a task. This tab will provide information about
all programs used during the time covered by
the history record.
SMF This option will record the collected information NO
to SMF. The data can then be processed offline
by utilities such as IBM CICS Performance
Analyzer.

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas 271
 Bottleneck Options
Table 75. Bottleneck options information
Parameter to use Definition Default
CLEAR_INTERVAL_LONG Specifies (in minutes) the default CLEAR 30
interval for long-term accumulators (0-999). To
disable this automatic reset, specify 0.
CLEAR_INTERVAL_SHORT Specifies (in minutes) the default CLEAR 10
interval for short-term accumulators (0-999).
Zero (0) resets the short-term accumulators
every internal bottleneck collection cycle.
SAMPLE_INTERVAL Specifies (in tenths of a second) the sample 23
interval for internal bottleneck collection
(1-99).
Note: The relationship between
SAMPLE_INTERVAL and CPU usage is not linear.
For example, changing the interval from 2 to 4
seconds does not yield a 50% reduction.

VARIABLE_BUCKETS Specifies the maximum number of variable 1000

buckets that internal bottleneck collection can
allocate. The value can range from 0-32767.
Whenever the allocated storage overflows, the
Bottlenecks panel in the OMEGAMON for CICS
(3270) interface displays a new line that shows
the wait reason sub-ID of *OVERFLW* and also
the percentage of waits that used the overflow
area.
Note: Use the following formula to compute the
amount of storage required for each variable
bucketset.

(12*X) + 92

Where X is the maximum number of groups

coded on the MAX_GROUPS operand of the
GLOBAL_OPTIONS component.

EXCLUDE_SYSTEM_TASKS Specifies whether system tasks waiting on NO

resources are excluded from Bottleneck
Analysis.
Possible values are:
YES
Specifies that system tasks waiting on
resources are excluded from Bottleneck
Analysis.
NO
Specifies that system tasks waiting on
resources are not excluded from Bottleneck
Analysis

272 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 75. Bottleneck options information (continued)
Parameter to use Definition Default
EXCLUDED_TRANS Specifies transactions to be excluded from None
Bottleneck Analysis. This can be the actual 1-
to 4-character transaction ID(s) or a generic
specification using wildcard characters. You can
use the question mark (?) wildcard character for
single-character substitution and the asterisk
character (*) as a trailing character only.
The following are examples of wildcarding:
• EXCLUDED_TRANS=(ABCD,E*): Excludes the
ABCD transaction(s) and all transaction IDs
that begin with E.
• EXCLUDED_TRANS=F?: Excludes all 2-
character transaction IDs where the first
character is F.
• EXCLUDED_TRANS=G??H: Excludes all 4-
character transaction IDs starting with G and
ending with H.
The following transaction IDs are always
excluded from Bottleneck Analysis:
• CSSY System Task
• CSJC Journal Control
• CVST VSAM Subtasking
• CSSX IRLM Abend Recovery
• CSGX IRLM Global Command
• CSNC Cross Region Support
• DSNC DB2 Support
Note: If the list of transactions will not fit
on one line, use additional EXCLUDED_TRANS
statements.

BOTTLENECK_ANALYSIS Specifies whether internal bottleneck collection AUTO

starts automatically.
Possible values are:
AUTO
Start internal bottleneck collection
automatically.
NOAUTO
Do not automatically start internal
bottleneck collection. If you specify
NOAUTO, you can start internal bottleneck
collection for the current region through the
BOTTLENECK ANALYSIS CONTROL panel of
the OMEGAMON for CICS (3270) interface
(faspath O.I).
Note: NOAUTO cannot be specified if you also
specify INTERVAL_RECORDING=AUTO.

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas 273
 User Excluded Transactions
To simplify your user-defined situations, you can specify a list of transactions that you want to exclude
from being counted toward a situation. This user excluded list of transactions will reside in the
OMEGAMON for CICS global data member.
To exclude transactions, specify the USER_EXCLUDED_TRANS parameter, with the TranID(s) you want to
exclude.
A user-defined situation can then check for the TranID value(s) you specified. If a transaction has a name
that matches the value of USER_EXCLUDED_TRANS, that transaction will not be included in the situation.
You can use the question mark (?) and asterisk (*) wildcard characters in the transaction list; the asterisk
can only be used as a trailing character.
Note: With PTF UJ01596, the CPU_EXCLUDED_TRANS section in the global data member was
repurposed as USER_EXCLUDED_TRANS for use with situations. If you refresh your global data
member or perform a Reformat (KC2GLBVR Job) , the CPU_EXCLUDED_TRANS section will be renamed
USER_EXCLUDED_TRANS. When the TRAN attribute group formats a row, it will check if the TranID, as
displayed, matches an entry in the USER_EXCLUDED_TRANS list. If so, the new excluded attribute is set
to YES. If the TranId is not in the list, the excluded attribute is set to NO. There are two other conditions
where the agent cannot make a determination. In these cases, a specific value is used for the attribute:
• If the KOCCI is not active. The attribute value O (No_KOCCI) is used.
• If the global data member is not loaded. The attribute value G (No Global) is used.

Table 76. User excluded transactions

Parameter to use Definition Default
EXCLUDED_TRANS The transactions you want to exclude from None
situations.

The exclude list may contain the actual 1-

to 4-character transaction ID(s) or a generic
specification using wildcard characters. You can
use the question mark (?) wildcard character for
single-character substitution and the asterisk (*)
as a trailing character only. The following are
examples of wildcarding:
EXCLUDED_TRANS=(ABCD,E*)
Excludes the ABCD transaction(s) and all
transaction IDs that begin with E.
EXCLUDED_TRANS=F?
Excludes all 2-character transaction IDs where
the first character is F.
EXCLUDED_TRANS=G??H
Excludes all 4-character transaction IDs starting
with G and ending with H.

User Event Monitoring

Defines and tailors user-event monitoring to OMEGAMON for CICS. OMEGAMON for CICS turns on
several global user exits and, if not already activated, CICS CMF performance monitoring. This allows
OMEGAMON for CICS to collect additional data about transaction execution.
This data is used by the response time collector, interval record collector, resource limiting, and task
history collector; and appears in SMF 112 and SMF 110 records written to SMF from the CICS address
space by both OMEGAMON for CICS and CICS. This additional data causes a slight increase in the

274 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

pathlength of CICS transactions and in the CPU usage of the monitored CICS address space, depending on
the transaction load.
OMEGAMON for CICS lets you limit the additional CPU utilization introduced by OMEGAMON for CICS into
CICS transaction execution path length.
CICS_CMF_MONITORING can be used to suppress the automatic activation of CICS CMF performance
monitoring.

Table 77. User event monitoring information

Parameter to use Definition Default
BASIC_SECTION=OMEGBSC Specifies the entry name of the event-monitoring OMEGBSC
point in the MCT for the BASIC section. This
name must match the ID operand of the
DFHMCT macro.
DB2_SECTION=OMEGDB2 Specifies the entry name of the event-monitoring OMEGDB2
point in the MCT for the DB2 section. This name
must match the ID operand of the DFHMCT
macro.
DLI_SECTION=OMEGDLI Specifies the entry name of the event-monitoring OMEGDLI
point in the MCT for the DLI section. This name
must match the ID operand of the DFHMCT
macro.
MQ_SECTION Specifies the entry name of the event-monitoring CANMQ
point in the MCT for the MQ section. This name
must match the ID operand of the DFHMCT
macro.
USREVNT1_SECTION Specifies the entry name of the event-monitoring CANUE1
point in the MCT for the USREVNT1 section.
This name must match the ID operand of the
DFHMCT macro.

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas 275
 Table 77. User event monitoring information (continued)
Parameter to use Definition Default
CICS_CMF_MONITORING Suppresses startup CMF performance YES
monitoring only if not already active.
Possible values are:
YES
Allows CMF performance monitoring and
XMNOUT CICS global user exit.
NO
Monitoring status inactive
Notes:
1. When CICS_CMF_MONITORING=NO is
specified, the following features of
OMEGAMON for CICS are not functional: Task
history, Application trace, Interval record
collector, Response time collection, SMF data
suppression, File statistics, Storage statistics,
Program compressions, Task CPU utilization,
TP I/O data. Resource limiting for the
following resources: CPU, DLI, DSA, EDSA,
VSAM
2. CICS_CMF_MONITORING=NO overrides any
DLI specification in the STARTUP_CONTROL
component.
3. CICS_CMF_MONITORING=NO disables
all global user exits.
CICS_CMF_MONITORING=YES enables all
global user exits required for data collection
in your environment.
4. Global user exits are not required for resource
limiting of the following resources: ADABAS,
DATACOM, Db2, ELAPSED, IDMS, SUPRA,
USREVNT1

CICS_CMF_WRITE Determines whether CMF is allowed to generate YES

and write SMF type 110 records.
Possible values are:
YES
Allows CMF to write SMF type 110 records.
Be sure that the SMF data sets are large
enough for these records.
NO
CMF is not allowed to write SMF type 110
records.
Note: If you specify CICS_CMF_WRITE=NO and
CICS_CMF_MONITORING=YES, OMEGAMON for
CICS turns on CMF in order to collect transaction
data about response time and task history, but
does not log this data to SMF (for batch reporting
by the historical reporter).

276 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 77. User event monitoring information (continued)
Parameter to use Definition Default
COMPRESS_SMF112_RECORDS Controls the compression of the OMEGAMON NO
for CICS SMF 112 (database) records during
XMNOUT processing.
Possible values are:
NO
OMEGAMON for CICS will write
uncompressed SMF records.
YES
Allows OMEGAMON for CICS to compress the
SMF buffer before it is written to SMF.
You can optionally write database performance
data to SMF.
The OMEGAMON for CICS SMF buffers may
contain data for multiple CICS transactions, and
will be written to SMF when the buffer fills.
Optionally the data can be compressed before
the write to SMF occurs. This compression is
performed using a standard compression utility,
CSRCESRV.

MCT_VALIDATION_MESSAGES OMEGAMON EMPs are required if data is to be NO

written to SMF. This field specifies whether the
MCT scan routine will display messages.
Possible values are:
NO
The MCT scan routine will not display
messages regarding OMEGAMON EMPs.
YES
The MCT scan routine will display messages
regarding OMEGAMON EMPs

CPU Monitoring
The parameter defines the threshold for monitoring internal CPU consumption by CICS transactions.

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas 277
 Table 78. CPU monitoring information
Parameter to use Definition Default
CPU_THRESHOLD Specifies the CPU-consumption threshold in 0
seconds (0-32,768). The default, 0, means that
the CPU-consumption exception (MAXR) will not
be tripped.
Note: The CPU_THRESHOLDING operand of
the STARTUP_CONTROL component determines
whether the MAXR exception is tripped when
the threshold is exceeded. Once a transaction
has tripped the MAXR exception, that transaction
will continue to appear on the Tasks Exceeding
Global CPU Time Limit panel, even if you
increase the CPU-consumption threshold.

Group Definitions
Group Definitions define transaction, terminal, and program groups for internal bottleneck collection.
You can also dynamically define groups through the Groups panel of the OMEGAMON for CICS (3270)
interface (fastpath,G.), but the changes remain in effect only temporarily.
Keep in mind the following group definition limits for a CICS region:
1. You can define as many as 30 groups.
2. Each group can contain one or more element names, such as a CICS transaction ID or terminal ID.
3. All the elements in a group must be of the same resource type.
4. You can define a maximum aggregate of 2000 elements across all groups.
5. The same element can appear in multiple groups.
Code one subentry for each group you define. Each entry must have a unique group number and group
name.

Table 79. Group Definitions information

Parameter to use Definition Default
GROUP_NUMBER Specifies the group number (01-30) or the 01
maximum number of groups allowed as
specified by the MAX_GROUPS operand of the
GLOBAL_OPTIONS component.
GROUP_NAME Specifies the name of this group (1-12 (TRAN GRP A* )
characters).
GROUP_TYPE Specifies the group type (PROG, TERM, or TRAN). TRAN

278 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 79. Group Definitions information (continued)
Parameter to use Definition Default
RESPONSE_TIME_THRESHOLD Specifies average response time thresholds for 20
this group (1-999 tenths of a second) for the
interval record collector and the response time
displays.
Note: OMEGAMON for CICS, uses the value
you specify as the Warning threshold for the
response time light. Also, OMEGAMON for
CICS doubles the RESPONSE_TIME_THRESHOLD
value to compute the critical threshold for the
response time light.

Group Elements
Group Elements define elements in one or more monitoring groups.
You can also dynamically define elements within groups through the Groups panel of the OMEGAMON for
CICS (3270) interface (fastpath G.).
Specifies information for an ID entry. You must specify at least one ID.TERM, TRAN, PROG, LU, and
TASKREQ are mutually exclusive. You must code a separate ID for each element that you wish to include
in a group.
You can use the PROG, TERM, and TRAN keywords with an asterisk (*) as a wildcard character to
represent all possible characters. For example, TERM=L* specifies all terminals beginning with the letter
L.

Table 80. Group Elements information

Parameter to use Definition Default
GRAPH_SCALE Specifies the height (1-99 seconds) of the 2
response time problems (RSP) graph. This entry is
for the response time collector only.
TIME_WINDOW Specifies the selection time window (1-10 10
minutes) for the RSP dynamic slot analysis (moving
time slots). This entry is for the response time
collector only.

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas 279
 Table 80. Group Elements information (continued)
Parameter to use Definition Default
ID Specifies the start of the ID entry. You must code a None
separate ID entry for each element that you wish to
include in a GROUP.
Possible values are:
TRAN
Specifies a 4-character transaction ID.
(Accepts the * wildcard character.)
PROG
Specifies the 8-character program name.
(Accepts the * wildcard character.)
TERM
Specifies a terminal ID, as defined in the CICS
terminal control table (TCT). (Accepts the *
wildcard character.)
TASKREQ
Specifies a 4-character special ID that
corresponds to a PA key, function key, light pen,
and so forth, as shown in this example:

#PAnPA keys (n = 1-3).

#FnnPF keys (nn = 01-36).
#LPALight pen attention.
#MAGMagnetic stripe reader.
#OCDOperator ID card

Note: TRAN, PROG, TERM, and TASKREQ are

mutually exclusive.

ELIGIBLE_GROUPS Specifies the GROUP or GROUPS with which (01)

the ID is associated. You can specify from 1
to the maximum number of groups allowed
according to the MAX_GROUPS operand of the
STARTUP_CONTROL component.
TOTAL_RESPONSE_THRESHOLD Specifies the response time threshold (0-999 20
tenths of a second) at which this ID appears in the
dynamic portion of the RSP display. This entry is for
the response time collector only.
HOST_RESPONSE_THRESHOLD Specifies the host response time threshold (0-999 None
tenths of a second). If an LU exceeds this
threshold, the ETE response time displays show
the host response time in red and record the
condition in the response history graph with a red
bar. This operand can be specified only for LU IDs.
NETWORK_RESPONSE_THRESHOLD Specifies the network response time threshold None
(0-999 tenths of a second). If an LU exceeds this
threshold, the ETE response time displays show
the network response time in red and record the
condition in the response history graph with a red
bar. You can use this operand only for LU IDs.

280 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 80. Group Elements information (continued)
Parameter to use Definition Default
FIXED_DISPLAY Indicates whether the ID should remain on the NO
graph presented by the RSP command in the
OMEGAMON for CICS (3270) system, regardless of
the response time.
Possible values are:
YES
The ID should always be displayed on the RSP
graph.
NO
The ID will only appear on the RSP graph
when the response time threshold has been
exceeded.

Interval Collector
This set of values defines interval record collector options. After the options are defined in the global data
area module, you can control the interval record collector options through the Control Interval Recording
Collector panel in the OMEGAMON for CICS (3270) system (fastpath O.K).

Table 81. Interval Collector information

Parameter to use Definition Default
NUMBER_DASD_DEVICES Specifies the number of internal queue 0
elements for the I/O sub-analysis routine (the
number of DASD devices allocated to the CICS
region). Valid values are 0-99. A value of
0 indicates that no I/O sub-analysis will be
conducted by Interval Recording.
RECORDING_INTERVAL Specifies the interval recording collection 1 minute
interval. This interval may be set to a value from
1-255 minutes.

Online Viewer
This section defines options for the task history collector. The following values are defined:

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas 281
 Table 82. Online Viewer information
Parameter to use Definition Default
DATA_STORE_TYPE Defines the way that data is saved. DSPACE

Possible values are:

DSPACE
Indicates that data for task history collection
is saved in a data space owned by the
OMEGAMON for CICS (3270) interface. This
data is saved until the task history collector
terminates.
FILEOCMP
Indicates that task history data is saved in a
VSAM linear dataset. No z/OS data space is
used. FILEOCMP is required if you have a very
large number of CICS transaction records
that you wish to access through the ONDV
command in OMEGAMON for CICS (3270)
interface.
The size of the VSAM file does not have
an impact on the amount of virtual storage
used in the OMEGAMON for CICS or CICS
address spaces. FILEOCMP causes data to be
compressed before it is written to the data
store.
The file should be allocated prior to restarting
the CICS address space using this FILEOCMP
monitoring option. Refer to the planning and
configuration guide for further information.
Auto
Indicates that the value of
DATA_STORE_TYPE could automatically be
switched between DSPACE and FILEOCMP.
The value FILEOCMP is used if the file which
is specified for a CICS region exists. If no file
matches the definition then the value DSPACE
is used.
Whether you use a data space or linear dataset,
the task history collector writes records using
a wraparound format. Once the data space or
dataset is full, the task history collector resumes
writing records from the beginning, overlaying the
previous data.

DATA_STORE_SIZE If you specify DSPACE, you must specify the size 956
of the data space in kilobytes. Each transaction
record requires about 808 bytes. The maximum
size is 2,097,148 kilobytes.

282 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 82. Online Viewer information (continued)
Parameter to use Definition Default
RESERVED_SIZE Specifies the portion of the data space (from 0 25
to 50 percent) reserved for file, database clock
and counter statistics, and Application Trace
records. See the Application Trace feature in the
OMEGAMON for CICS.
You must specify a number greater than 0 or
statistics by filename and/or Application Trace
records will not be available from the task history
collector.
The RESERVED_SIZE operand is not needed
when the DATA_STORE_TYPE=FILEOCMP is
specified. It will be ignored if it is supplied.
File and database clock and counter statistics
are always available in the FILEOCMP data store
when they are being collected in the CICS region
(through use of the DATABASE_COLLECTION
component).

DATA_STORE_FILE_NAME Specifies the name of a VSAM linear dataset None

when the DATA_STORE_TYPE=FILEOCMP or
DATA_STORE_TYPE=AUTO is specified.
You can share global data area modules (but not
VSAM data sets) across different CICS regions
even though a dataset name is specified in the
global data area module. To do this, you must
insert one wildcard character (*) somewhere in
the VSAM dataset name on this operand. When
the task history collector is running, the wildcard
character is replaced by the job name of the CICS
region being monitored. The wildcard character
may appear anywhere in the dataset name and
should occur only once.

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas 283
 Table 82. Online Viewer information (continued)
Parameter to use Definition Default
EXCLUDED_TRANS Indicates transactions to exclude from analysis. None
The list of transactions is limited to 63
transaction IDs. Transactions that start before
phase 3 of the PLTPI or end after phase 1 of
the PLTSD are not excluded. Any CICS-generated
transactions that initiate without going through
TRUE processing are not excluded either.
The exclude list may contain the actual 1-
to 4-character transaction ID(s) or a generic
specification using wildcard characters. You can
use the question mark (?) wildcard character
for single-character substitution and the asterisk
character (*) as a trailing character only. The
following are examples of wildcarding:

EXCLUDED_TRANS=(ABCD,E*)

Excludes the ABCD transaction(s) and all

transaction IDs that begin with E.

EXCLUDED_TRANS=F?

Excludes all 2-character transaction IDs where

the first character is F.

EXCLUDED_TRANS=G??H

Excludes all 4-character transaction IDs starting

with G and ending with H.
Note: If the list of transactions will not fit
on one line, use additional EXCLUDED_TRANS
statements.

Resource Limiting
Resource Limiting defines resources with their respective thresholds and identifies the action to be taken
when a resource threshold or limit has been exceeded.

284 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 83. Resource Limiting Parameters
Parameter to use Definition Default
Resource Specifies a resource for limiting usage: None

VSAM
EXEC-level file control requests.
DSA
HWM of storage from the DSA.
EDSA
HWM of storage from the UDSA and EUDSA.
GDSA
HWM of storage from the GUDSA.
CPU
CPU time limit.
ELAPSED
Elapsed time limit.
CONTAINR
HWM of Container storage used by the task.
CPUGP
Time spent on a General Processor CPU.
CPUQR
Time spent on the QR TCB.
DLI
EXEC DL/I and CALL DL/I requests.
ADABAS
ADABAS requests.
IDMS
IDMS requests.
DATACOM
DATACOM requests.
SUPRA
SUPRA requests.
DB2
DB2 requests.
MQ
Message queuing requests
RUNTIME
Time for tasks held due to MXT or Class
maximum. This is the time the task actually
ran excluding time spent waiting for MXT or
Class max tasks.
USREVNT1
Any user-defined requests.

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas 285
 Table 83. Resource Limiting Parameters (continued)
Parameter to use Definition Default
EXCLUDED_TRANS Specifies one or more transactions to exclude
from resource limiting. This can be the actual
1- to 4-character transaction ID(s) or a generic
specification using wildcard characters. You can
use the question mark (?) wildcard character
for single-character substitution and the asterisk
character (*) as a trailing character only.
The following are examples of wildcarding:

EXCLUDED_TRANS=(ABCD,E*)

Excludes the ABCD transaction(s) and all

transaction IDs that begin with E

EXCLUDED_TRANS=F?

Excludes all 2-character transaction IDs where

the first character is F.

EXCLUDED_TRANS=G??H

Excludes all 4-character transaction IDs starting

with G and ending with H.
Non-displayable transaction IDs are specified as
follows:

#PAnPA keys (n = 1-3).

#FnnPF keys (nn = 01-36).
#LPALight pen attention.
#MAGMagnetic stripe reader.
#OCDOperator ID card

Note: Neither KILL_LIMIT nor WARN_LIMIT can

be used with EXCLUDED_TRANS.
Exclude CICS system transactions by specifying
EXCLUDED_TRANS=C*.
If the list of transactions will not fit on one line,
use additional EXCLUDED_TRANS statements.

286 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 83. Resource Limiting Parameters (continued)
Parameter to use Definition Default
INCLUDED_TRANS Specifies one or more transactions for resource None
limiting. This can be the actual 1- to 4-character
transaction ID(s) or a generic specification using
wildcard characters. You can use the question
mark (?) wildcard character for single-character
substitution and the asterisk character (*) as a
trailing character only.
The following are examples of wildcarding:

INCLUDED_TRANS=(ABCD,E*)

Selects the ABCD transaction(s) and all

transaction IDs that begin with E

INCLUDED_TRANS=F?

Selects all 2-character transaction IDs where the

first character is F.

INCLUDED_TRANS=G??H

Selects all 4-character transaction IDs starting

with G and ending with H.
Non-displayable transaction IDs are specified as
follows:

#PAnPA keys (n = 1-3).

#FnnPF keys (nn = 01-36).
#LPALight pen attention.
#MAGMagnetic stripe reader.
#OCDOperator ID card

Note: If INCLUDED_TRANS is specified, either

KILL_LIMIT or WARN_LIMIT (or both) must also
be specified. See below for information on these
parameters.
If the list of transactions will not fit on one line,
use additional INCLUDED_TRANS statements.

KILL_LIMIT Specifies a threshold for limiting resource usage. None

Transactions that exceed this value are abended.
Thresholds can be set at the following values:

Resource Threshold
CPU and ELAPSED 1-32768 seconds
DSA 1-9999999 bytes
EDSA 1-999999999 bytes
File and DataBase 1-99999999 number
of requests
GDSA and CONTAINR 1-99999999 kilobytes

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas 287
 Table 83. Resource Limiting Parameters (continued)
Parameter to use Definition Default
WARN_LIMIT Specifies a threshold for limiting resource usage. None
OMEGAMON for CICS issues a warning message
for transactions that exceed this value. The value
must be lower than the KILL_LIMIT if specified.

A transaction executing under CEDF is not abended. Instead, a message is issued to the terminal and the
transaction continues normal execution. OMEGAMON for CICS writes messages, issued as a result of KILL
or WARN action, to the CICS Transient Data Queue (ID of CSSL, dataset MSGUSR) or via a WTO.
Transaction selection tips:
Since you might have some overlap in transaction codes if you use both EXCLUDED_TRANS and
INCLUDED_TRANS with wildcarding, OMEGAMON for CICS selects a transaction for resource limiting as
follows:
• If you do not specify the INCLUDED_TRANS operand or if you specify the INCLUDED_TRANS operand
that matches a specification in the list, OMEGAMON for CICS selects the transaction. If a transaction
ID qualifies for resource limiting under more than one rule, the most specific INCLUDED_TRANS
specification is used. For example:

Rule 1: Rule 2:
------------------- -------------------
<<DB2>> <<DB2>>
INCLUDED_TRANS=TST* INCLUDED_TRANS=TST1
KILL_LIMIT=100 KILL_LIMIT=50
WARN_LIMIT=80 WARN_LIMIT=40

When transaction TST1 executes, the limits attached to Rule 2 apply. To exclude a transaction from a
resource list, the EXCLUDED_TRANS specification must be at least as specific as the INCLUDED_TRANS
specification under which it applies for that resource limit. For example:

Rule 1: Rule 2:
------------------- -------------------
<<DB2>> <<DB2>>
INCLUDED_TRANS=TST1 EXCLUDED_TRANS=T*
KILL_LIMIT=100
WARN_LIMIT=80

When transaction TST1 executes, it will be subject to the resource limit because INCLUDED_TRANS=TST1
is more specific than EXCLUDED_TRANS=T*. If, however:

Rule 1: Rule 2:
------------------- -------------------
<<DB2>> <<DB2>>
INCLUDED_TRANS=TST* EXCLUDED_TRANS=TST1
KILL_LIMIT=100
WARN_LIMIT=80

Then transaction TST1 will be excluded from the resource limit.

RLIM versus ICVR tips:
The ICVR parameter, available through CICS, and the RLIM CPU option, available through OMEGAMON for
CICS, serve two separate functions:
1. The ICVR value allows you to set an upper limit for the amount of CPU time that a task may consume
within a single dispatch.
2. The RLIM CPU limit allows you to set an upper limit on the total amount of CPU time that a task may
consume across multiple dispatches.
You may consider RLIM and ICVR to be complementary tools you can use to prevent a task from
monopolizing the CPU.

288 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

When determining whether or not a task should be abended due to excessive CPU consumption, RLIM
compares the value in USRCPUT, DFHTASK_008 in the Transaction Monitoring Area, with the CPU limit
specified in the appropriate global data area module, KC2GLBnn.
The CICS Monitoring Facility updates the value in USRCPUT when a task issues a CICS command that
suspends the task and causes the dispatcher to be invoked. RLIM CPU usage checking is performed
whenever an EXEC CICS request is issued. Additionally, if you have installed support for a third-party
database product and are collecting clock and counter statistics for that database type, a request issued
to the database will cause the task's CPU usage to be checked.
Certain CICS commands usually do not drive the dispatcher and therefore the USRCPUT value may not be
incremented. Consequently, RLIM probably will not abend any task that only issues one or more of these
commands in a loop. The commands that rarely drive the dispatcher are:
• ASKTIME
• HANDLE
• ENQ
• DEQ
• FREEMAIN
• RELEASE
• TRACE ON/OFF
• XCTL
In addition, a READ request that can be satisfied from the buffer, as opposed to requiring physical I/O,
does not invoke the dispatcher. Other CICS commands may invoke the dispatcher, but only if the request
cannot be satisfied immediately and the task is suspended. Therefore, an application that, for instance,
repeatedly issues a GETMAIN and FREEMAIN for a small area may not give up control. In such a situation,
the task's CPU time value will not be updated and RLIM will not abend the task (see "External task
resource limiting," below). Conversely, because the USRCPUT value is updated only at the end of each
dispatch, the CICS runaway-task mechanism, controlled by the ICVR parameter in the SIT, does not use
it. To determine whether or not to abend the task, CICS refers to a timer that is reset each time the task is
redispatched. While dispatched, CICS decrements the timer at regular intervals. If the timer reaches zero,
the task is abended with code AICA.

External task resource limiting

When RESOURCE_LIMITING_MSG_DEST is specified as "LOG" or "TDL," RLIM runs an additional program
each second which monitors active tasks and, if needed, takes action against a task. This is done only if
limits were specified for resource types "CPU" or "ELAPSED" and is intended to handle tasks that are in
a long wait or actively using CPU but not issuing EXEC CICS requests. Message KCP8906I is issued and
serves as a notification that the task has exceeded the threshold even though RLIM cannot ABEND it. You
may use this message to automate actions to notify operators that external action may be required.

Resource Limiting Interval

The RESOURCE_LIMITING_INTERVAL specifies at what interval resource limiting should process user
defined rules. Once RLIM is active, the interval settings apply to all resources and their respective rules,
hence a global implication. There are two ways to specify an interval. Either, specify a TIME_INTERVAL or
specify EXEC_CALLS and/or DB_CALLS.
The values in the following tables can be used.

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas 289
 Table 84. Resource limiting interval information
Parameter to use Definition Default
TIME_INTERVAL Defines the amount of time, in units of seconds, which 0
must pass before existing resource limits or rules
could be processed. Default value of zero seconds
implies that RLIM processing will not be based on
time interval. Maximum allowable value is one week
or 604800 seconds.
EXEC_CALLS Defines the number of EXEC CICS commands which 0
must be issued by the application program before
existing resource limits or rules could be processed.
Default value of zero implies that RLIM processing will
not be based on the number of EXEC calls. Maximum
allowable value is 99999999.
DB_CALLS Defines the number of DataBase commands or EXEC 0
CICS SQL commands which must be issued by the
application program before existing resource limits
or rules could be processed. Default value of zero
implies that RLIM processing will not be based on
the number of DataBase or EXEC CICS SQL calls.
Maximum allowable value is 99999999.

Note: The default value of zero for all settings implies that RLIM processes the rules or limits, according
to their definition, on every invocation. By the same token, when an interval(s) is set the processing of
defined limits or rules only occurs within that interval.
Only those transactions which are started after the intervals were last refreshed, are eligible for
processing.

Response Time collection

The RESPONSE_TIME_COLLECTION value specifies the time intervals for the response time collector.
The values in the following table can be used.

Table 85. Response time collection information

Parameter to use Definition Default
TIME_INTERVALS Specifies the time intervals for the Average (5,10,30)
Response Times display. You must enter three
values:

short,mid,long

These are the three intervals for reporting RTA

data. In order to roll the values from one interval
to the other, OMEGAMON for CICS requires that
"long" be an integer multiple of "mid" and that
"mid" be an integer multiple of "short". The
values are in minutes within the range 1-999.

290 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 85. Response time collection information (continued)
Parameter to use Definition Default
EXCLUDED_TRANS Specifies transactions to exclude from analysis. None
The list of transactions is limited to 63
transaction IDs. Transactions that start before
phase 3 of the PLTPI or end after phase 1 of
the PLTSD are not excluded. Any CICS-generated
transactions that initiate without going through
TRUE processing are not excluded either.
The exclude list may contain the actual 1-
to 4-character transaction ID(s) or a generic
specification using wildcard characters. You can
use the question mark (?) wildcard character
for single-character substitution and the asterisk
character (*) as a trailing character only.
The following are examples of wildcarding:

EXCLUDED_TRANS=(ABCD,E*)

Excludes the ABCD transaction(s) and all

transaction IDs that begin with E.

EXCLUDED_TRANS=F?

Excludes all 2-character transaction IDs where

the first character is F.

EXCLUDED_TRANS=G??H

Excludes all 4-character transaction IDs starting

with G and ending with H.
Note: If a transaction is matched in the
EXCLUDED_TRANS list, OMEGAMON for CICS
excludes it from analysis, whether or not it
matches a GROUP_ELEMENTS component on
either terminal ID, program, transaction ID, LU
name, or TASKREQ.
If the list of transactions will not fit on one line,
use additional EXCLUDED_TRANS statements.

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas 291
 Table 85. Response time collection information (continued)
Parameter to use Definition Default
TIME_SLOT Specifies the time slot definitions (1-48 slots) for 0000,0800
the Today's Response Times display. It specifies 0800,0900
0900,1000
the start time (first entry) and end time (second 1000,1100
entry) of the slot. Enter the values in 24-hour 1100,1200
clock format using this syntax: 1200,1300
1300,1400
1400,1500
(hhmm,hhmm) 1500,1600
1600,1700
1700,2400
Where hh (hours) is a 2-digit number from 00
through 24 and mm (minutes) is a 2-digit number
from 00 through 59.
At least one slot must be defined; if more
than one slot is defined, the slots must be in
ascending order. The ending time value on one
slot may be the same as the beginning time
value on the next slot, but overlaps are not
allowed. (A shared minute is not an overlap.)
The default RTA TIME_SLOTs daily configuration
is one slot from 0000 to 0800, then contiguous
hourly slots until 1700, and one more slot from
1700 to 2400.

Dedicated Sessions
The DEDICATED_SESSIONS values define terminals for OMEGAMON for CICS dedicated mode sessions.
The values in the following tables can be used.

Table 86. Dedicated sessions information

Parameter to use Definition Default
UNIT Specifies the beginning of information for an None
external monitoring session. It is followed by the
other operands defining a session.
UNIT_ADDRESS Specifies the device address of the terminal. None
PHYSICAL_ROWS Specifies the number of physical rows (1-999) 24
on the terminal.
LOGICAL_ROWS Specifies the number of logical rows (1-999). 99
COLUMNS Specifies the number of columns (80, 132, or 80
160) on the terminal.
USER_PROFILE Specifies the user profile suffix (any two None
characters). Any session of OMEGAMON for
CICS can use a different profile by specifying a
different two-character suffix.

Service Level Analysis

The SERVICE_LEVEL_ANALYSIS value controls whether data will be written to the Service Level Analysis
subtask running in the CICS agent address space.
The value in the following tables can be used.

292 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 87. Service level analysis information
Parameter to use Definition Default
INCLUDE_REGION Specifies whether performance data collected by YES
OMEGAMON is sent to the SLA summarization
routines running in the OMEGAMON for CICS
agent address space and displayed in the Service
Level Analysis reports.
Possible values are:
YES
Performance data collected by OMEGAMON
is sent to the SLA summarization routines
running in the OMEGAMON for CICS agent
address space. Data for regions that use this
global data area is displayed in the Service
Level Analysis reports.
NO
Performance data collected by OMEGAMON
is not sent to the SLA summarization routines
running in the OMEGAMON for CICS agent
address space. Data for regions which use
this global data area is not displayed in the
Service Level Analysis reports.

Enabling outbound API request monitoring

The OUTBOUND_API_REQUEST_MONITORING parameter, AGGREGATE, controls whether file level
monitoring will be enabled, to collect data for outbound API request monitoring. The following table
gives the values that can be used.

Table 88. Outbound API Request Monitoring

Parameter to use Definition Default
AGGREGATE Specifies whether file level collection for NOAUTO
outbound API request monitoring is enabled.
AUTO
Start file level collection automatically.
NOAUTO
Do not start file level collection
automatically.

TRUE Monitoring
The TRUE_MONITORING values control whether data for Task Related User Exits (TRUE) will be collected,
written to task history, and written to SMF so that the data can be processed offline by utilities such as
IBM CICS Performance Analyzer.

Table 89. TRUE Monitoring information

Parameter to use Definition Default
ENABLE Specifies whether TRUE Monitoring is enabled. NOAUTO
AUTO: Start TRUE Monitoring automatically.
NOAUTO: Do not start TRUE Monitoring
automatically.

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas 293
 Table 89. TRUE Monitoring information (continued)
Parameter to use Definition Default
WRITE_TO_HISTORY This option will record the collected data for YES
a task to Task History. This tab will provide
information about all TRUEs used during the
time covered by the history record.
SMF This option will record the collected information NO
to SMF. The data can then be processed offline
by utilities such as IBM CICS Performance
Analyzer.

Refreshing the monitoring options

OMEGAMON for CICS uses the Global Data Area to load the information into z/OS storage in the
OMEGAMON for CICS (3270) interface address space on behalf of a monitored CICS region.
Each region that OMEGAMON for CICS monitors is represented by its own unique copy of the Global Data
Area in the address space. This is true even if you defined only one module for monitoring multiple CICS
regions. Each one of those regions has a separate, unique copy loaded for it at the time OMEGAMON for
CICS prepares to monitor it.
You can change the contents of a Global Data Area without stopping your CICS regions by creating a new
Global while the old one is being used.
You can delete a region's Global Data Area copy from storage for OMEGAMON for CICS (3270) and replace
it with your updated version by performing any one of the following:
• Stop the OMEGAMON for CICS collector address space and restart it.
• Stop the CICS address space and restart it.
• Stop OMEGAMON for CICS from monitoring the target CICS while the CICS address space continues
running normally.
To stop OMEGAMON for CICS monitoring, perform all of the following steps:
1. If KOCOME00 was run at the CICS PLTPI time or if the OMEG INIT command was issued in the CICS
region, issue the OMEG REMOVE command to reverse the process.
2. Stop task history collection, internal bottleneck collection, interval recording, and response time
collection for the target CICS region.
3. End all OMEGAMON for CICS sessions monitoring the target CICS region, including dedicated sessions.
When this procedure is completed, OMEGAMON for CICS deletes the Global Data Area copy used by
the target CICS region.
4. After completing the procedure, issue a new OMEG INIT command in the CICS address space to use
the new Global Data Area.
Note: Recycling the global module will only affect transactions started after the global module has been
recycled.

Additional Considerations
The following tables list CICS global exit names supported by EXIT_SUPPRESSION, the data gathered,
CMF performance monitoring possibilities, and OMEG INIT processing implications.

OMEG INIT processing for CICS_CMF_MONITORING

CICS_CMF_MONITOR is subordinate to the user-defined CMF environment. If you specify
CICS_CMF_MONITOR=NO at PLTPI time or in OMEG INIT processing, OMEGAMON for CICS takes action
depending on the state of CMF monitoring.

294 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

The following table describes the contingencies.

Table 90. OMEG INIT processing scenarios

If CMF monitoring
is . . . Then Tivoli OMEGAMON. . . And . . .
Not active Allows it to remain off The XMNOUT exit activation is bypassed.
Active Determines whether CMF • If performance class data gathering is
performance class data active, OMEGAMON activates the XMNOUT
gathering is active. exit so that CMF monitoring can use the data
CICS is already gathering.
• If performance class data gathering
is inactive, OMEGAMON allows CMF
monitoring to remain inactive and bypasses
the XMNOUT exit.

CMF monitoring possibilities

Several settings affect the monitoring and writing of CMF performance data:
• CMF performance monitoring parameters in your SIT (MN and MNPER SIT operands)
• CICS_CMF_WRITE in USER_EVENT_MONITORING (YES or NO)
• CICS_CMF_MONITORING in USER_EVENT_MONITORING (YES or NO)
• CEMT SET MONITOR command (ON or OFF)
The following three tables illustrate the interaction of these factors:
• The Table 91 on page 295 table shows the eight possible combinations of settings before initialization.
• TheTable 92 on page 296 table shows what happens after you run the OMEG INIT transaction to start
OMEGAMON for CICS. The first column indicates whether or not data is written to SMF. The second
column indicates whether or not data will be available to ONDV and RTA.
• The Table 93 on page 296table shows what happens if you run CEMT SET MONITOR ON after
OMEGAMON for CICS has been started.
To determine how performance data will be handled with your current option settings, find the row in
the first table that contains your settings before initialization. Then, check the corresponding row in the
second and third tables.
The following tables describes the contingencies.

Table 91. Settings Before Initialization

CMF Perf. Monitoring SMFCICS3 MONITOR
OFF NO NO
OFF NO YES
OFF YES NO
OFF YES YES
ON NO NO
ON NO YES
ON YES NO
ON YES YES

Appendix D. Detailed procedures for managing the OMEGAMON for CICS (3270) Global Data Areas 295
 Table 92. After OMEG INIT
SMF Write ONDV/RTA Get Data Comments
NO NO
NO YES CMF turned on, XMNOUT
activated.
NO NO
YES YES CMF turned on. XMNOUT
activated.
YES NO SMFCICS=NO
NO YES
YES NO
YES YES CICS and OMEGAMON for CICS
write to SMF. All OMEGAMON
for CICS data collected. XMNOUT
activated.

Table 93. After CEMT SET MONITOR PERF ON

SMF Write ONDV/RTA Get Data Comments
YES NO XMNOUT is OFF.
N/A N/A Monitoring is already ON.
YES NO XMNOUT is OFF.
N/A N/A Monitoring is already ON.
N/A N/A Monitoring is already ON.
N/A N/A Monitoring is already ON.
N/A N/A Monitoring is already ON.
N/A N/A Monitoring is already ON.

296 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Appendix E. SAS historical reporting
This section describes how SAS supplements the existing historical reporter feature of OMEGAMON for
CICS component.
This implementation provides the following:
• An alternative reporting mechanism
• Sample SAS reports that you might adapt to local requirements
• A means to generate one-off reports without you having in-depth knowledge of SAS
• A means to generate response time group definitions that you can imbed into your global data area
module (GLOBAL_OPTIONS).

Using the SAS historical reporter

Use the SAS historical reporter to accomplish the following tasks:
• Allocating a sequential SAS DETAIL data set that contains a complete day's worth of collected data
• Allocating a sequential SAS DAILY dataset that contains 31 days of summarized, aged information from
the DETAIL data set
• Using a Generalized Report Writer to produce custom reports on any collected data
• Using the Response Time Transaction Group Build program to analyze the collected SAS data and build
response time group parameter entries. You can then insert these parameters into the OMEGAMON for
CICS global data area module (GLOBAL_OPTIONS).

Overview of the SAS historical reporting process

To collect performance data, SMF recording must be enabled for OMEGAMON for CICS. You can enable
SMF recording during product customization.
Table 94 on page 297 shows the steps in the SAS historical reporting process, from OMEGAMON for CICS
data collection to SAS report creation.

Table 94. Steps in the SAS historical reporting process

Stage Description
1 OMEGAMON for CICS collects performance data using additional event monitoring
points defined in the MCT and clocks and counters information defined in the
GLOBAL_OPTIONS module. CICS or OMEGAMON for CICS writes performance data
as SMF 110 records and, optionally, clocks and counters information as SMF user
records.
2 SAS creates a DETAIL data set and, using job KC2SMFJ, populates it with collected
SMF data.
3 SAS uses data in the SAS DETAIL data set (through job KC2REPTJ) to generate the
supplied reports and charts (KC2TRPn and KC2TCHn).
4 You can generate user-defined reports by using the supplied Generalized Report
Writer job KC2GRWJ.
5 You can generate response time group definitions by using the supplied transaction
group build job KC2TRXJ.
6 At the end of the day, SAS summarizes the DETAIL data set to the DAILY data set and
archives the DETAIL data set to cartridge (through job KC2DLYJ) for post processing
purposes.

© Copyright IBM Corp. 2004, 2022 297

 Table 94. Steps in the SAS historical reporting process (continued)
Stage Description
7 SAS uses data in the SAS DAILY data set (through job KC2REPTJ) to generate the
supplied reports and charts (KC2DRPn and KC2DCHn).
8 Ad hoc reports may be produced directly from the SMF data set using job KC2ADHCJ.

Preparing to run the sample SAS reports

This section provides the steps you follow to prepare to run the sample SAS supplied reports.
The preparatory steps are as follows:
1. Create and populate the SAS runtime JCL and macro libraries.
2. Allocate the sequential SAS data sets.
3. Customize SAS macros.
4. Run the daily collection jobs to populate the SAS DETAIL and DAILY data sets.
For details on these steps, see:
• “Installation procedures” on page 168
• “Customization procedures” on page 168
• “Running the daily collection jobs” on page 169

Location of the SAS code

All the SAS code described in this section is distributed through the OMEGAMON for CICS hilev.TKANSAM
target library.

Installation procedures
The following sections describe the installation procedures that you perform. Perform the installation only
once.

Create and populate the SAS runtime JCL and macro libraries
To allocate and populate the SAS system files, edit and submit the JCL in the TKANSAM library member,
KC2SASJB. The IEBGENER job allocates these PDS files, KC2SJCL and KC2SPROS, and copies specific
members into them from the TKANSAM library. The purpose of these files is as follows:
KC2SJCL
Contains JCL procedures to allocate and maintain the SAS database and run the sample SAS reports.
KC2SPROG
Contains SAS system macros and the sample programs.
Important: Any further customization that you perform should be done on the members in the KC2SJCL
and KC2SPROG PDS files. Do not make changes directly to members in the TKANSAM library because it is
an SMP/E library that could change due to maintenance.

Allocate the sequential SAS data sets, DETAIL and DAILY

To create the DETAIL and DAILY SAS data sets, edit and submit the supplied job KC2ALOCJ, located in the
KC2SJCL data set. SAS requires that a standard sequential data set be allocated for use as the repository
for all the data collected from OMEGAMON for CICS. The purpose of these data sets is as follows:
• The DETAIL data set contains one or two data files:

298 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 – The CICSTRAN data file consisting of one record for each logical SMF 110 record; that is, one per
CICS transaction. This information is gathered daily from the SMF data sets. Each stored record is
approximately 2259 bytes.
– An optional DBD data file that contains database clocks and counters information for each
transaction collecting DBCOL information from the global data area (GLOBAL_OPTIONS). Each stored
record is approximately 76 bytes.
• The optional DAILY data set comprises data files (one per day) that contain summarized information
gathered from the DETAIL data set and aged over a number of days. As supplied, 31 days of information
is retained. Each stored record is approximately 824 bytes. If you do not want to produce summarized
data, do not create the DAILY data set.

Customization procedures
This section describes the customization procedures you can perform. Perform customization only once.

Customizing SAS macros and programs

Review and customize the following SAS macro members in the order indicated. These members are
located in the KC2SPROG data set. Follow these steps to customize the SAS macros and programs:
1. Customize KC2GRP and KC2GRF with group definitions and names.
KC2GRP allows you to group transactions for reporting purposes. Transactions defined in Group 0 are
overhead transactions and can be excluded from any report. The sample KC2GRP member contains
entries for some sample groups. KC2GRF defines names for the groups created in the KC2GRP macro.
2. Customize KC2CMPY with your company name. This name appears in the title of all reports produced.
3. Customize KC2SHFT with shift times if you want reporting by shift; otherwise, skip this step.
The default shifts are 8 a.m. to 5 p.m. (day shift), 5 p.m. to midnight (evening shift), and midnight to 8
a.m. (night shift).
4. Customize KC2WEEK to define the first day of the week at your site.
The default first day of the week is Sunday.
5. Review SAS macros for SMF record mappings. These mappings are equivalent to complete SMF 110
records; no fields have been excluded.
KC2V640
Provides the mapping of the CICS-produced SMF 110 record for CICS Transaction Server V3.1
(CICS Version 6.4.0).
KC2V650
Provides the mapping of the CICS-produced SMF 110 record for CICS Transaction Server V3.2
(CICS Version 6.5.0).
KC2V660
Provides the mapping of the CICS-produced SMF 110 record for CICS Transaction Server V4.1
(CICS Version 6.6.0).
KC2V670
Provides the mapping of the CICS-produced SMF 110 record for CICS Transaction Server V4.2
(CICS Version 6.7.0).
If you exclude fields from the Monitoring Control Table (MCT), you must modify the SMF 110 mapping
accordingly. To do so, create a new member name, then copy to it the appropriate mapping that
corresponds to the CICS release. You should then comment out redundant fields that were excluded.
If you use CICS Version 3.x and higher, the KC2DICTJ job is supplied to print the dictionary records.
The KC2DICTJ job reads and reports the structure of the dictionary record and assists you in
determining the format of your SMF 110 records.

Appendix E. SAS historical reporting 299

 6. If user-defined mappings are created as a result of the previous step, review and customize KC2PICK
to invoke the new mapping. The SAS code located in KC2PICK demonstrates how to select a specific
mapping according to the CICS release or applid.
Note: SMF 110 record layouts differ across CICS releases. You might have different SMF mappings for
CICS systems at the same release level due to MCT field exclusions. The main SMF converter program,
KC2SMFR, invokes KC2PICK to determine which SMF 110 mapping to use. The actual SMF mappings
are retained in separate members.
7. Review KC2BSC.
This SAS macro, used within the SMF converter program KC2SMFR, provides a mapping of the 132-
byte OMEGBSC EMP that is supplied. If you have excluded fields from the default supplied OMEGBSC,
you must modify this member accordingly. Be sure you specify the length of the customized OMEGBSC
correctly.
You can control the size of the OMEGBSC data area. The sample KC2BSC member demonstrates
how to select a specific mapping according to the CICS applid. The sample shows how to define a
mapping to be used by a CICS system, ”NODBCICS," that excludes the eight 4-byte database clocks
and counters fields. This exclusion reduces the size of the OMEGBSC from 132 bytes – 100 bytes. All
other CICS systems use the standard 132-byte supplied definition. This accommodates those users
who may have customized their OMEGBSC EMP differently for separate CICS systems.

Running the daily collection jobs

The last steps that you perform before you run the sample SAS reports are to populate the DETAIL and
DAILY data sets.

Populating the DETAIL data set

See Stage 2 of Table 54 on page 167.
To extract the SMF records, customize and run the supplied job, KC2SMFJ, located in the KC2SJCL data
set. You can run this job periodically during the day to populate the SAS DETAIL data set. By the end of the
day the DETAIL data set contains the full day's worth of SMF CICS data. Alternatively, if you already have
procedures in place to gather daily SMF data into one single data set, you can run this job just once at the
end of the day.
The supplied job, KC2SMFJ does the following:
• The IFASMFDP program supplied by IBM is run to unload the SMF data to a sequential data set; it
extracts SMF 110 and 112 records
• The SAS program, KC2SMFR, located in the KC2SPROG data set, is run to create a temporary SAS data
set using the input from the previous list item. (see Using the KC2SMFR converter program in the next
section).
• Runs a SAS procedure to append the temporary data set created in the KC2SMFR program to the
DETAIL data set.

Using the KC2SMFR converter program

KC2SMFR is the SAS SMF converter program that decodes the SMF 110 records and, optionally, the SMF
112 records. This program creates the SAS data files CICSTRAN and DBD on the DETAIL data set. The
CICSTRAN and DBD data files created by KC2SMFR contain fields for all the current releases of CICS.
The KC2SMFR converter program provides the following parameters:
TRAN=YES,NO
Determines whether the CICSTRAN datafile is generated. YES is the default setting.
DBD=NO,YES
Determines whether the DBD data file that contains clocks and counters information is generated. NO
is the default setting.

300 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

DBSMF=255,nnn
Specifies the SMF user record containing clocks and counters information. 255 is the default value.
CICS= ALL,xxxxxxxx
Determines whether SMF records relating to all or a specific or generic CICS applid are processed. For
example, CICS=PROD restricts processing to all CICS applids beginning with PROD. Alternatively, you
can specify CICS=ALL and use the EXIT= option to accommodate more specific processing. ALL is
the default setting.
C2SMF=110,nnn
Allows you to specify the same user record number that you specified in the SMFCICS2 parameter
of the USER_EVENT_MONITORING parameter (located in GLOBAL_OPTIONS) for the OMEGAMON for
CICS generated subset of the SMF type 110 record. 110 is the default setting.
DBSMF=112,nnn
Allows you to specify the same user record number that you specified in the SMFCICS2 parameter
of the USER_EVENT_MONITORING parameter (located in GLOBAL_OPTIONS) for the OMEGAMON for
CICS generated subset of the SMF type 112 record. 112 is the default setting.
GMTOFF=99,nn
A value of 99 signifies that the GMT offset in the OMEGBSC should be applied. You can specify an
override containing the actual GMT offset; for example, GMTOFF=+8, as not all transactions have an
OMEGBSC segment. An example is transactions that started before OMEGAMON for CICS component
is initialized. 99 is the default setting.
UMB=YES,NO
When set to YES, this parameter specifies that if the umbrella program and transaction ID are present,
they are used in preference to the actual CICS program and transaction ID. YES is the default setting.
EXIT=NO,xxxxxxxx
Specifies the name of a user-written exit program that allows greater selection criteria. For example,
to limit the size of the DETAIL file, you may omit specific transactions. The default setting is NO. This
is an example of the kind of program you would write to exclude records for a particular region and
exclude all CICS transactions:

IF SMFMNPRN = “PRODACCT” THEN DELETE; /*drop records for this region*/ IF

TRAN =: “C” THEN DELETE; /*and drop ‘CICS' trans */

DBDEXIT=NO,xxxxxxxx
Specifies the name of a user-written exit program to be applied to the DBD component of the DETAIL
file. NO is the default setting.
STOP=NO,nnn W.
When set to a numeric value, restricts processing to a specified number of input records for debugging
purposes. NO is the default setting.
DEBUG=NO,YES
When set to YES, this parameter switches debugging on. NO is the default setting.

Running the DETAIL reports and charts

See Stage 3 of Table 54 on page 167.
After the DETAIL data set is populated, you can run DETAIL reports and charts against this data set using
the KC2REPTJ job, located in the KC2SJCL data set. KC2REPTJ executes the SAS procedure that specifies
which of the supplied reports to produce (reports from both the DETAIL and DAILY data sets can be
produced by this job).

Appendix E. SAS historical reporting 301

 //STEP01 EXEC SASxxx,SASAUTO=&OHILEV.KC2SPROG,
// OPTIONS=&apos;MACRO MAUTOSOURCE S=72 S2=72 DQUOTE&apos;
//DETAIL DD DISP=SHR,DSN=&OHILEV.SAS.DETAIL
//DAILY DD DISP=SHR,DSN=&OHILEV.SAS.DAILY
//****************************************************************
// PLACE YOUR REPORT OPTIONS AFTER THE SYSIN STATEMENT ALONG WITH*
// ANY ADDITIONAL KEYWORD SELECTION CRITERIA. *
//****************************************************************
//SYSIN DD *
%KC2TRP1;
%KC2TRP2;
%KC2TRP3 (EXIT=MYEXIT); /* ONLY REPORT ON ABENDED */
/* TRANSACTIONS VIA AN EXIT */
%KC2TCH1;
%KC2DRP7 (DAILYLO=1,DAILYHI=7,SUMBY=WEEK);
%KC2DCH5 (DAILYLO=1,DAILYHI=7);
//MYEXIT DD *
IF ABCODEO =: “00”X THEN DELETE; /* DROP TRANS THAT HAVEN&apos;T ABENDED
*/

Figure 25. Example of the JCL you enter to specify the DETAIL and DAILY reports

Populating the DAILY data set

See Stage 6 of Table 54 on page 167.
Customize and run the supplied job KC2DLYJ, located in the KC2SJCL data set. This job does the
following:
1. Invokes the KC2SUMD program, located in the KC2SPROG data set, which takes as input the DETAIL
data set and summarizes its contents into the DAILY data set. The DAILY data set is aged over a
user-defined period (the default aging period is 31 days).
2. Runs a SAS procedure to copy the contents of the DETAIL dataset to a cartridge for archiving. You can
produce DETAIL reports directly from this cartridge.
3. Reallocates the DETAIL data set to make it available for the next day's processing.
You can run this job at the end of the day. You can then either produce reports from an archived copy of
the DETAIL data set or produce reports directly from the DAILY data set.

Using the KC2SUMD program

KC2SUMD is the SAS code that summarizes and ages the contents of the DAILY data set from the DETAIL
data set. Transaction data is summarized by region name, month, week, day, hour, userid, LU name, and
transaction ID. The DAILY data set occupies significantly less space than the DETAIL data set and allows
long-term summary reports to be produced.
The KC2SUMD program provides the following parameters:
DAYS=31,nn
The number of days of data to retain in the DAILY data set. This assumes that KC2SUMD is run daily.
You can determine your own requirements, bearing in mind the overall DASD storage requirements.
31 is the default setting.
EXIT=NO,xxxxxxxx
Specifies the name of a user-written exit program to allow greater selection criteria. NO is the default
setting.
STOP=NO,nnn
When set to a numeric value, this parameter restricts processing to a specified number of input
records for debugging purposes. NO is the default setting.
DEBUG=NO,YES
When set to YES, this parameter switches debugging on. NO is the default setting.
The KC2SUMD program does not summarize every field found in the DETAIL data set.

302 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 The DETAIL data set archive
Once summarizing and aging have occurred, the DETAIL data set is archived automatically and cleared,
ready for the next day's propagation phase. After the DETAIL data set has been cleared, you cannot report
against it directly. You can, however, report directly against the archived copy using the KC2REPTJ job. In
your JCL, just indicate the cartridge that contains the data set.

Running the DAILY reports and charts

See Stage 7 of Table 54 on page 167.
After summarizing and aging have occurred to populate the DAILY data set, you can produce reports on
the DAILY file by using the KC2REPTJ job, located in the KC2SJCL data set. KC2REPTJ executes the SAS
procedure that specifies the supplied reports to produce (reports from both the DETAIL and DAILY data
sets can be produced by this job).

Producing reports directly from SMF data

See Stage 8 of Table 54 on page 167.
The job KC2ADHCJ, located in the KC2SJCL data set, allows you to produce reports without creating a
permanent DETAIL data set. You can produce ad hoc reports directly from the unloaded SMF data, and
can specify any number of reports.
The KC2ADHCJ job performs the following tasks:
• Runs the IFASMFDP program supplied by IBM to unload the SMF data to a sequential data set.
• Runs KC2SMFR, located in the KC2SPROG data set, to create a temporary SAS data set that uses the
input from the IFASMFDP program.
In the following JCL, you can add report statements to the SYSIN DD statement following KC2SMFR.
For example, you could enter:

//DETAIL EXEC SASxxx,SASAUTO=&OHILEV..KC2SPROG,

OPTIONS='MACRO MAUTOSOURCE S=72 S2=72 DQUOTE'
//DETAIL DD DISP=(,PASS),DSN=&DETAIL,UNIT=SYSDA,
// SPACE=(CYL,(50,10))
//SMF DD DISP=OLD,DSN=&&SMF
//SYSIN DD *
/*THE FOLLOWING STATEMENT READS IN SMF DATA FROM THE SMF DD */
/*AND WRITES THE SAS DATA TO THE DETAIL DD Temporary dataset
/ %KC2SMFR (CICS=ALL,GMTOFF=+8,DBD=YES,DBSMF=112);
/* ENTER THE REPORTS YOU WISH TO PRODUCE. */
%KC2TRP1;
%KC2TRP2;
%KC2TRP3;
/*

Figure 26. Example of the JCL to use when you want to add report statements to the SYSIN DD statement

Producing reports from the SAS DETAIL data set

This section describes the sample SAS reports you can produce from the SAS DETAIL data set. Report
programs KC2TRxx and charts KC2TCHx are provided as samples.

Running the sample SAS reports

To run the supplied sample SAS reports, do one of the following:
• Customize and run the supplied KC2REPTJ job, located in the KC2SJCL data set, at any time. This job
runs the sample SAS reports on either the current SAS DETAIL data set (or its archived copy) or the
summarized DAILY data set.
• Customize and run the supplied KC2ADHCJ job at any time to report directly against the SMF data set.

Appendix E. SAS historical reporting 303

 Parameters for the DETAIL reports and charts
The following parameters are available to the DETAIL sample reports TRP1 through TRnn and charts
TCH1 through TCHnn.
These are parameters for the DETAIL reports and charts:
DAILYHI=DAILYLO value,nn
Determines the highest (oldest) daily file to be used. DAILYLO and DAILYHI determine the range of
history data to be reported. If you enter only DAILYLO, DAILYHI assumes that same value. If you enter
DAILYLO and inadvertently enter DAILYHI with a less value (error situation), DAILYHI again assumes
the DAILYLO value. DAILYLO is the default setting.
CICS=ALL,xxxxxxxx
Determines whether SMF records relating to all or a specific or generic CICS applid are processed. For
example, CICS=PROD restricts processing to all CICS applids beginning with PROD. Alternatively, you
can specify CICS=ALL and use the EXIT= option to accommodate more specific processing. ALL is
the default setting.
HRLO=00,nn
Determines the start time of data reported. 00 is the default setting.
HRHI=23,nn
Determines the end time of data reported. 23 is the default setting.
LUNAME=ALL,xxxxxxxx
Processes all VTAM LUs and allows you to restrict processing to a specific or generic LUNAME. ALL is
the default setting.
GROUP=ALL,WORKLOAD,nn
Processes transactions that belong to all GROUPS defined in KC2GRP. Allows you to restrict
processing to a specific group of transactions. If you specify GROUP=WORKLOAD, then all transactions
belonging to GROUP 0 are ignored from all processing. ALL is the default setting.
SHIFT=ALL,nn
Restricts the selection criteria to a specific shift as defined in KC2SHFT. ALL is the default setting.
SUMBY=DAY,WEEK,MONTH
Determines how a report is summarized. For example, you can create a report by day for 7 days by
specifying DAILYLO=1, DAILYHI=7, SUMBY=DAY, or by week by specifying DAILYLO=1, DAILYHI=7,
SUMBY=WEEK. KC2DCH1, a Response Time Chart by Hour, is summarized by week as follows:

DAILYLO=1,DAILYHI=7,LOTIME=09:00:00,HITIME=12:00:00,SUMBY=WEEK

This would graph the response time distribution for the three hour period over the week. This
parameter is not valid for reports KC2DCH5, KC2DCH6, and KC2DRP7. DAY is the default setting.
TRAN=ALL,xxxx
Restricts the selection criteria to a specific or generic transaction ID. ALL is the default setting.
USERID=ALL,xxxxxxxx
Restricts the selection criteria to a specific or generic userid. ALL is the default setting.
EXIT=NO,xxxxxxxx
Specifies the name of the exit program you write to allow greater selection criteria. NO is the default
setting.
STOP=NO,nnn
When set to a numeric value, restricts processing to a specified number of input records for debugging
purposes. NO is the default setting.
DEBUG=NO,YES
When set to YES, this parameter switches debugging on. NO is the default setting.

304 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

DETAIL reports and graph charts
These are the DETAIL reports and graph charts that can be produced:
• KC2TRP1 - Response Time Statistics by Transaction
This report has no additional parameters.
• KC2TRP2 - Response Time Statistics by Interval
This report program provides the following additional parameter. This parameter allows you to override
the default reporting interval.
INTERVAL=60,nn
Defines the reporting interval period in minutes. 60 is the default setting.
• KC2TRP3 - Transaction Detail
This report program provides the following additional parameter. Use this parameter to set a specific
response time threshold.
THRESH=NO,nn
Limits selection to a specific response time threshold in seconds, for example, THRESH=1 or
THRESH=0.5. NO is the default setting.
• KC2TRP4 - Service Level Report by Transaction
This report has no additional parameters.
• KC2TRP5 - Service Level Report by Interval
To override the default reporting interval, this report has the following additional parameter.
INTERVAL=60,nn
Defines the reporting interval period in minutes. 60 is the default setting.
• KC2TRP7 - Response Time Graphs
This report provides the following additional parameters:
INTERVAL=15,nn
Defines the reporting interval period in minutes. 15 is the default setting.
RPTINT=YES,NO
Specifies whether the Interval Response report is produced. YES is the default setting.
RPTTRAN=YES,NO
Specifies whether the Transaction Response report is produced. YES is the default setting.
RPTLU=YES,NO
Specifies whether the LU Response report is produced. YES is the default setting.
RPTPGM=YES,NO
Specifies whether the Program Response report is produced. YES is the default setting.
These are the graphs that can be produced:
– response time by user-defined interval
– response time by transaction ID
– response time by VTAM LU
– response time by program
• KC2TRP8 - Response Time and VSAM/DB Activity by Transaction
This report has no additional parameters.
• KC2TRP9 - Response Time and VSAM/DB Activity by interval
This report provides the following additional parameter.
INTERVAL=60,nn
Defines the reporting interval period in minutes. 60 is the default setting.

Appendix E. SAS historical reporting 305

 • KC2TRP13 - Response Time Distribution by Transaction
This report has no additional parameters.
• KC2TRP14 - Storage Utilization Statistics
This report has no additional parameters.
• KC2TRP16 - Region Summary
This report has no additional parameters.
• KC2TRP17 - Database/File Response Time Statistics
A report of database/file response time statistics by transaction. To produce this report, clocks and
counters data must have been collected by KC2SMFR using the parameter DBD=YES.
• KC2TCH1 - Chart of average response time by interval parameters
This chart provides the following additional parameters:
INTERVAL=15,nn
Specifies the response time graph interval. 15 is the default setting.
SPLIT=
You can specify the keyword ‘CICSGRP,' if you need it to produce charts by transaction group.
TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=RESPTIME,xxxxxxxx
Although this is by default a response time chart, you may specify another field here; for example,
USRCPUTM, to obtain a chart of User CPU Time. RESPTIME is the default setting.
HDR=AVERAGE RESPONSE TIME,cccc..ccc
Allows a user-defined header to be specified. AVERAGE RESPONSE TIME is the default setting.
SCALE=5,nn,0.n
Determines the maximum scale to use for the graph axis. 5 is the default setting.
These are examples of the graphs:
– a response time chart
– chart of average user CPU time
• KC2TCH2 - Average response time by interval parameters
KC2TCH2, which is a chart of average response time by interval within a group, provides the following
additional parameters:
INTERVAL=15,nn
Specifies the response time graph interval. 15 is the default setting.
SPLIT=
You can specify the keyword ‘CICSGRP,' if you need it to produce charts by transaction group.
TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=RESPTIME,xxxxxxxx
Although this is a chart of transaction response time, you may produce a chart using a different
variable. RESPTIME is the default setting.
HDR=AVERAGE RESPONSE TIME,cccc..ccc
Allows a user-defined header to be specified when requesting a different CHARTVAR variable.
AVERAGE RESPONSE TIME is the default setting.
SCALE=5,nn,0.n
Determines the maximum scale to use for the graph axis. 5 is the default setting.
• KC2TCH3 - A chart of total user CPU time by Interval parameters.
This chart provides the following additional parameters:

306 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 INTERVAL=15,nn
Specifies the graph interval.
SPLIT=
You can specify the keyword ‘CICSGRP,' if you need it to produce charts by transaction group.
TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=USRCPUTM,xxxxxxxx
Although this is a chart of user CPU time, you may produce a chart using a different variable.
USRCPUTM is the default setting.
HDR=USER CPU TIME,cccc..ccc
Allows a user-defined header to be specified when you are requesting a different CHARTVAR
variable. USER CPU TIME is the default setting.
SCALE=5,nn,0.n
Determines the maximum scale to use for the graph axis. 5 is the default setting.
• KC2TCH4 - Total User CPU Time by Interval within Group parameters
This chart provides the following additional parameters:
INTERVAL=15,nn
Specifies the graph interval.
SPLIT=
You can specify the keyword ‘CICSGRP,' if you need it to produce charts by transaction group.
TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=USRCPUTM,xxxxxxxx
Although this is a chart of user CPU time, you may produce a chart using a different variable.
USRCPUTM is the default setting.
HDR=USER CPU TIME,cccc..ccc
Allows a user-defined header to be specified when you are requesting a different CHARTVAR
variable. USER CPU TIME is the default setting.
SCALE=5,nn,0.n
Determines the maximum scale to use for the graph axis. 5 is the default setting.

Running the DETAIL reports and charts

See Stage 3 in Table 54 on page 167.
After the DETAIL data set is populated, you can run DETAIL reports and charts against this data set using
the KC2REPTJ job, located in the KC2SJCL data set. KC2REPTJ executes the SAS procedure that specifies
which of the supplied reports to produce (reports from both the DETAIL and DAILY data sets can be
produced by this job).
This is an example of the JCL you enter to specify the DETAIL and DAILY reports:

Appendix E. SAS historical reporting 307

 //STEP01 EXEC SAS608,SASAUTO=&OHILEV.KC2SPROG,
// OPTIONS=&apos;MACRO MAUTOSOURCE S=72 S2=72 DQUOTE&apos;
//DETAIL DD DISP=SHR,DSN=&OHILEV.SAS.DETAIL
//DAILY DD DISP=SHR,DSN=&OHILEV.SAS.DAILY
//****************************************************************
// PLACE YOUR REPORT OPTIONS AFTER THE SYSIN STATEMENT ALONG WITH*
// ANY ADDITIONAL KEYWORD SELECTION CRITERIA. *
//****************************************************************
//SYSIN DD *
%KC2TRP1;
%KC2TRP2;
%KC2TRP3 (EXIT=MYEXIT); /* ONLY REPORT ON ABENDED */
/* TRANSACTIONS VIA AN EXIT */
%KC2TCH1;
%KC2DRP7 (DAILYLO=1,DAILYHI=7,SUMBY=WEEK);
%KC2DCH5 (DAILYLO=1,DAILYHI=7);
//MYEXIT DD *
IF ABCODEO =: “00”X THEN DELETE; /* DROP TRANS THAT HAVEN&apos;T ABENDED
*/

Figure 27. Example of a JCL to enter to specify the DETAIL and DAILY reports

Populating the DAILY data set

See Stage 6 of Table 54 on page 167.
Customize and run the supplied job KC2DLYJ, located in the KC2SJCL data set. This job does the
following:
• Invokes the KC2SUMD program, located in the KC2SPROG data set, which takes as input the DETAIL
data set and summarizes its contents into the DAILY data set. The DAILY data set is aged over a
user-defined period (the default aging period is 31 days).
• Runs a SAS procedure to copy the contents of the DETAIL dataset to a cartridge for archiving. You can
produce DETAIL reports directly from this cartridge.
• Reallocates the DETAIL data set to make it available for the next day's processing.
You can run this job at the end of the day. You can then either produce reports from an archived copy of
the DETAIL data set or produce reports directly from the DAILY dataset.

Using the KC2SUMD program

KC2SUMD is the SAS code that summarizes and ages the contents of the DAILY data set from the DETAIL
data set. Transaction data is summarized by region name, month, week, day, hour, userid, LU name, and
transaction ID. The DAILY data set occupies significantly less space than the DETAIL data set and allows
long-term summary reports to be produced.
The KC2SUMD program provides the following parameters:
DAYS=31,nn
The number of days of data to retain in the DAILY data set. This assumes that KC2SUMD is run daily.
You can determine your own requirements, bearing in mind the overall DASD storage requirements.
31 is the default setting.
EXIT=NO,xxxxxxxx
Specifies the name of a user-written exit program to allow greater selection criteria. NO is the default
setting.
STOP=NO,nnn
When set to a numeric value, this parameter restricts processing to a specified number of input
records for debugging purposes. NO is the default setting.
DEBUG=NO,YES
When set to YES, this parameter switches debugging on. NO is the default setting.
The KC2SUMD program does not summarize every field found in the DETAIL data set.

308 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 The DETAIL dataset archive
Once summarizing and aging have occurred, the DETAIL data set is archived automatically to cartridge
and cleared, ready for the next day's propagation phase. After the DETAIL data set has been cleared, you
cannot report against it directly. You can, however, report directly against the archived copy using the
KC2REPTJ job. In your JCL, just indicate the cartridge that contains the data set.

Running the DAILY reports and charts

See Stage 7 of Table 54 on page 167.
After summarizing and aging have occurred to populate the DAILY data set, you can produce reports on
the DAILY file by using the KC2REPTJ job, located in the KC2SJCL data set. KC2REPTJ executes the SAS
procedure that specifies the supplied reports to produce (reports from both the DETAIL and DAILY data
sets can be produced by this job).

Producing reports directly from SMF data

See Stage 8 of Table 54 on page 167.
The job KC2ADHCJ, located in the KC2SJCL data set, allows you to produce reports without creating a
permanent DETAIL data set. You can produce ad hoc reports directly from the unloaded SMF data, and
can specify any number of reports.
The KC2ADHCJ job performs the following tasks:
• Runs the IFASMFDP program supplied by IBM to unload the SMF data to a sequential data set.
• Runs KC2SMFR, located in the KC2SPROG data set, to create a temporary SAS data set that uses the
input from the IFASMFDP program.

Producing reports from the SAS DAILY data set

This section describes sample SAS reports produced from the SAS DAILY data set. Report program
KC2DRxx and charts KC2DCHx are provided to run against the summarized SAS DAILY data set.

Running the sample SAS reports against the DAILY data set
To run the supplied sample SAS reports, customize and run the supplied KC2REPTJ job, located in the
KC2SJCL data set, at any time. This job runs the sample SAS reports on either the current SAS DETAIL
data set (or its archived copy) or the summarized DAILY data set.

Parameters for the DAILY reports and charts

The following parameters are available to the DAILY sample reports: DRP1 through DRnn and charts
DCH1 through DCHnn.
These are parameters for the DAILY reports and charts:
DAILYHI=DAILYLO value,nn
Determines the highest (oldest) daily file to be used. DAILYLO and DAILYHI determine the range of
history data to be reported. If you enter only DAILYLO, DAILYHI assumes that same value. If you
enter DAILYLO and inadvertently enter DAILYHI with a less than value (error situation), DAILYHI again
assumes the DAILYLO value. DAILYLO is the default setting.
CICS=ALL,xxxxxxxx
Determines whether SMF records relating to all or a specific or generic CICS applid are processed. For
example, CICS=PROD restricts processing to all CICS applids beginning with PROD. Alternatively, you
can specify CICS=ALL and use the EXIT= option to accommodate more specific processing. ALL is
the default setting.
HRLO=00,nn
Determines the start time of data reported. 00 is the default setting.

Appendix E. SAS historical reporting 309

 HRHI=23,nn
Determines the end time of data reported. 23 is the default setting.
LUNAME=ALL,xxxxxxxx
Processes all VTAM LUs and allows you to restrict processing to a specific or generic LUNAME. ALL is
the default setting.
GROUP=ALL,WORKLOAD,nn
Processes transactions that belong to all GROUPS defined in KC2GRP. Allows you to restrict
processing to a specific group of transactions. If you specify GROUP=WORKLOAD, then all transactions
belonging to GROUP 0 are ignored from all processing. ALL is the default setting.
SHIFT=ALL,nn
Restricts the selection criteria to a specific shift as defined in KC2SHFT. ALL is the default setting.
SUMBY=DAY,WEEK,MONTH
Determines how a report is summarized. For example, you can create a report by day for 7 days by
specifying DAILYLO=1, DAILYHI=7, SUMBY=DAY, or by week by specifying DAILYLO=1, DAILYHI=7,
SUMBY=WEEK. KC2DCH1, a Response Time Chart by Hour, is summarized by week as follows:

DAILYLO=1,DAILYHI=7,LOTIME=09:00:00,HITIME=12:00:00,SUMBY=WEEK

This would graph the response time distribution for the three hour period over the week. This
parameter is not valid for reports KC2DCH5, KC2DCH6, and KC2DRP7. DAY is the default setting.
TRAN=ALL,xxxx .
Restricts the selection criteria to a specific or generic transaction ID. ALL is the default setting.
USERID=ALL,xxxxxxxx
Restricts the selection criteria to a specific or generic userid. ALL is the default setting.
EXIT=NO,xxxxxxxx
Specifies the name of the exit program you write to allow greater selection criteria. NO is the default
setting.
STOP=NO,nnn
When set to a numeric value, restricts processing to a specified number of input records for debugging
purposes. NO is the default setting.
DEBUG=NO,YES
When set to YES, this parameter switches debugging on. NO is the default setting.

DAILY reports and graph charts

These are the DAILY reports and graph charts that can be produced:
• KC2DRP1 - Response Time Statistics by Transaction
This report has no additional parameters.
• KC2DRP2 - Response Time Statistics by Hour
This report has no additional parameters.
• KC2DRP4 - Service Level Report by Transaction
This report has no additional parameters.
• KC2DRP5 - Service Level Report by Hour
This report has no additional parameters.
• KC2DRP7 - Response Time Graphs
This report provides the following additional parameters:
RPTINT=YES,NO
Specifies whether the Interval Response report is produced. YES is the default setting.

310 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 RPTTRAN=YES,NO
Specifies whether the Transaction Response report is produced. YES is the default setting.
RPTLU=YES,NO
Specifies whether the LU Response report is produced. YES is the default setting.
These are the graphs that can be produced:
– response time by interval
– response time by transaction ID
– response time by VTAM LU
• KC2DRP8 - Response Time and VSAM/DB Activity by Transaction
This report has no additional parameters.
• KC2DRP9 - Response Time and VSAM/DB Activity by Hour
This report has no additional parameters.
• KC2DR16 - Region Summary
This report has no additional parameters.
• KC2DCH1 - Chart of Average Response Time by Hour parameters
This chart provides the following additional parameters:
SPLIT=
You can specify the keyword ‘CICSGRP,' if you need it to produce charts by transaction group.
TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=RESPTIME,xxxxxxxx
Although this is by default a response time chart, you may specify another field here; for example,
USRCPUTM, to obtain a chart of User CPU Time. RESPTIME is the default setting.
HDR=AVERAGE RESPONSE TIME,cccc..ccc
Allows a user-defined header to be specified. AVERAGE RESPONSE TIME is the default setting.
SCALE=5,nn,0.n
Determines the maximum scale to use for the graph axis. 5 is the default setting.
• KC2DCH2 - Average Response Time by Hour within Group
KC2DCH2, which produces a chart of average response time by hour within each group, has the
following additional parameters:
INTERVAL=15,nn
Specifies the response time graph interval. 15 is the default setting.
TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=RESPTIME,xxxxxxxx
Although this is a chart of transaction response time, you may produce a chart using a different
variable. RESPTIME is the default setting.
HDR=AVERAGE RESPONSE TIME,cccc..ccc
Allows a user-defined header to be specified when requesting a different CHARTVAR variable.
AVERAGE RESPONSE TIME is the default setting.
SCALE=5,nn,0.n
Determines the maximum scale to use for the graph axis. 5 is the default setting.
• KC2DCH3 - Chart of Total User CPU Time by Hour parameters
This chart provides the following additional parameters:
SPLIT=
You can specify the keyword ‘CICSGRP,' if you need it to produce charts by transaction group.

Appendix E. SAS historical reporting 311

 TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=USRCPUTM,xxxxxxxx
Although this is a chart of user CPU time, you may produce a chart using a different variable.
USRCPUTM is the default setting.
HDR=USER CPU TIME,cccc..ccc
Allows a user-defined header to be specified when you are requesting a different CHARTVAR
variable. USER CPU TIME is the default setting.
SCALE=5,nn,0.n
Determines the maximum scale to use for the graph axis. 5 is the default setting.
• KC2DCH4 - Total User CPU Time by Hour within Group parameters
KC2DCH4, which produces a chart of total user CPU time by hour within each group, has the following
additional parameters:
TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=USRCPUTM,xxxxxxxx
Although this is a chart of user CPU time, you may produce a chart using a different variable.
USRCPUTM is the default setting.
HDR=USER CPU TIME,cccc..ccc
Allows a user-defined header to be specified when you are requesting a different CHARTVAR
variable. USER CPU TIME is the default setting.
• KC2DCH5 - Chart of Average Response Time by Day
This chart provides the following additional parameters:
SPLIT=
You can specify the keyword ‘CICSGRP' to produce charts by transaction group.
TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=RESPTIME,xxxxxxxx
Although this is a chart of user CPU time, you may produce a chart using a different variable.
RESPTIME is the default setting.
HDR=RESPONSE TIME STATISTICS,cccc..ccc
Allows a user-defined header to be specified. RESPONSE TIME STATISTICS is the default setting.
SCALE=5,nn,0.n
Determines the maximum scale to use for the graph axis. 5 is the default setting.
KC2DCH5 uses a default value of 7 for the DAILYHI parameter rather than the usual default of 1. Using
this higher value, you can produce a report of daily response time for a seven day period.
• KC2DCH6 - Average Response Time by Day within Group
KC2DCH6, which produces a chart of average response time by day within each group, provides the
following additional parameters:
SPLIT=
You can specify the keyword ‘CICSGRP' to produce charts by transaction group.
TYPE=V,H
Determines the type of chart to be produced-vertical or horizontal. V is the default setting.
CHARTVAR=RESPTIME,xxxxxxxx
Although this is a chart of user CPU time, you may produce a chart using a different variable.
RESPTIME is the default setting.
HDR=RESPONSE TIME STATISTICS,cccc..ccc
Allows a user-defined header to be specified. RESPONSE TIME STATISTICS is the default setting.

312 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 SCALE=5,nn,0.n
Determines the maximum scale to use for the graph axis. 5 is the default setting.

Producing reports through the Generalized Report Writer

You can create your own custom reports from the DETAIL data set, using the Generalized Report Writer.
This facility allows you to supply the report field names, using the SAS LET command, and the
summarization criteria and output format that you require. A list of field names is contained in member
KC2LABL, which is used in the KC2SMFR program.
Reports can be list or summary type reports, depending on the parameters you define.

Using the KC2TGRW program

KC2TGRW is the SAS code that performs the Generalized Report Writer function. Whenever you want
user-defined reports, invoke the KC2TGRW program by customizing and running the supplied KC2GRWJ
job, located in the KC2SJCL data set, against the SAS DETAIL data set (or its archived copy).
The KC2TGRW program provides the following parameters:
CICS= ALL,xxxxxxxx
Determines whether SMF records relating to all or a specific or generic CICS applid are processed. For
example, CICS=PROD restricts processing to all CICS applids beginning with PROD. Alternatively, you
can specify CICS=ALL and use the EXIT= option to accommodate more specific processing. ALL is
the default setting.
LUNAME=ALL,xxxxxxxx
Processes all VTAM LUs and allows you to restrict processing to a specific or generic LUNAME. All is
the default setting.
GROUP=ALL,WORKLOAD,nn
Processes transactions that belong to all GROUPS defined in KC2GRP. Allows you to restrict
processing to a specific group of transactions. If you specify GROUP=WORKLOAD, then all transactions
belonging to GROUP 0 are ignored from all processing. All is the default setting.
SHIFT=ALL,nn
Restricts the selection criteria to a specific shift as defined in KC2SHFT. All is the default setting.
TERM=ALL,xxxx
Restricts the selection criteria to specific or generic terminal IDs. All is the default setting.
TRAN=ALL,xxxx
Restricts the selection criteria to a specific or generic transaction ID. All is the default setting.
USERID=ALL,xxxxxxxx
Restricts the selection criteria to a specific or generic userid. YES is the default setting.
LODATE=NO,mm/dd/yy
Restricts the selection criteria to a specific start date. NO is the default setting.
LOTIME=NO:,hh:mm:ss
Restricts the selection criteria to a specific start time. NO is the default setting.
HIDATE=NO,mm/dd/yy
Restricts the selection criteria to a specific end date. NO is the default setting.
HITIME=NO,hh:mm:ss
Restricts the selection criteria to a specific end time. NO is the default setting.
EXIT=NO,xxxxxxxx
Specifies the name of the exit program you write to allow greater selection criteria. NO is the default
setting.
STOP=NO,nnn
When set to a numeric value, restricts processing to a specified number of input records for debugging
purposes. NO is the default setting.

Appendix E. SAS historical reporting 313

 HDR=User Defined Report,cc..cc
Allows you to specify a heading to be generated as part of the report title. User Defined Report is the
default setting.
DEBUG=NO,YES
When set to YES, this parameter switches debugging on. NO is the default setting.

Running the Generalized Report Writer

Customize and run the supplied KC2GRWJ job, located in the KC2SJCL data set, against the SAS DETAIL
data set (or its archived copy) when you want user-defined reports.

Merging of the SAS DETAIL data files

Since the SAS DETAIL data set comprises of two data files, CICSTRAN and the optional DBD data file,
the Generalized Report Writer must merge the files for reporting purposes when the KEEPDBD parameter
specifies at least one field. The two files are merged based upon their internal CICS unit-of-work token
and transaction ID. Any mismatches are dropped from the report.

Control statements for generating custom reports

Use the following control statements in KC2GRWJ to generate custom reports: All control statements
must be present and each statement terminated with a semicolon (;).
KEEP=field1 field2 field3 field4..;
Assigns all the fields from the CICSTRAN data file within the DETAIL data set that you require to
produce the report. At least one field must be present.
KEEPDBD=field1 field2 field3 field4..;
Assigns any optional fields from the DBD data file within the DETAIL data set that you require to
produce the report. If no fields are required, you must define this parameter as KEEPDBD=; If you do
so, the data files (from the SAS DETAIL data set) are not merged.
SORTBY=field1 field2 field3..;
Assigns all the fields you sort by.
SUMVARS=field1 field2 field3..;
Specifies the field names to be summarized. The output from the summarization process generates
summarized variables in the order matching the SUMVARS statement; for example:

SUMVARS=USRCPUTM RESPTIME

This definition provides averages, totals, maximums and minimums of transaction CPU and response
times. The presence of variables defined to the SUMVARS control statement determines whether a list
or summary report is produced.
IMPORTANT: For each field defined in the SUMVAR control statement, you must define a
corresponding field in each of the AVER, TOTAL, MAX and MIN control statements. Therefore, you
might need to define dummy fields for fields you do not need. If you do not require any output
variables of a certain type, you can specify a null value; for example, MIN=.;.
AVER=useravgfield1 useravgfield2..;
Defines the user-specified fields for averages, for each field defined in the same order as specified in
the SUMVARS statement.
TOTAL=usertotfield1 usertotfield2..;
Defines the user-specified fields for totals, for each field defined in the same order as specified in the
SUMVARS statement.
MAX=usermaxfield1 usermaxfield2..;
Defines the user-specified field for maximums, for each field defined in the same order as specified in
the SUMVARS statement.

314 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

MIN=usermaxfield1 usermaxfield2..;
Defines the user-specified field for minimums, for each field defined in the same order as specified in
the SUMVARS statement.
PRINTBY=field1,userfieldx..;
Defines the print control break. For example, if you want a report of transaction counts by CICS region,
you can first sort by region (SMFMNPRN) and transaction ID (TRAN), summarize to get the total
transaction count, and then use the PRINTBY statement to force a break at every new region name.
PRINTID=field1;
Specifies the first field to appear on each line of the report. This parameter also prevents SAS from
numbering each line of the report.
PRINT=field1 userfieldx..;
Defines the fields that you want to appear on the report, including user-defined fields specified in the
AVER, TOTAL, MAX and MIN statements.
HEADING=userfield1=heading1 userfield2=heading2;
User-defined fields specified in AVER, TOTAL, MAX and MIN, which are to be written to the report, can
have headings defined. For example: HEADING=TRAN_CT=Total Transaction*Count;..
FORMAT=field1 field2 format..;
Defines the format in which a field is to be printed using standard SAS notation. For example, to print
User CPU Time and the Dispatch Wait Time as eight character fields to four decimal places, specify
the following: FORMAT USRCPUTM DISPWTTM 8.4
In addition, an internal format exists (IN_K.) to display count fields in units of thousands. For example,
to print a File Control I/O Requests field, specify: FORMAT FCTOTCT IN_K.; This field reports as nnn
for values less than 1000 and nnnK for values in excess of 1000. If FORMAT is set to default, the fields
print in accordance with their internal SAS format.
KC2TGRW
The SAS macro that invokes the Generalized Report Writer. The JCL supplied for KC2TGRW,
KC2GRWJ, contains sample custom reports that you can customize.

Tips for producing list and summary reports

If you require a list report, leave SUMVARS, AVER, TOTAL, MAX and MIN set to nulls; for example, specify
MIN=;. You might then report on any field defined in the KEEP list.
If you require a summary report, follow these steps:
1. Specify the required fields in the KEEP list.
2. In the SORTBY list, specify the fields you want to sort and summarize.
In the SUMVARS list, specify the fields for which you want summary information. If you require
averages, totals, minimums, or maximums, then specify fields in the AVER, TOTAL, MAX, and MIN
parameters, respectively. You can now report on the fields specified in the parameters SORTBY, AVER,
TOTAL, MAX and MIN.

Examples of custom reports

This section contains report definition examples for explanations of how the control statements are used
for custom reports:
Summary report for transaction abend codes
To produce a summary report of transaction abend codes, sorted by abend code with a count of the
number of abended transactions and how many resources these transactions consumed, specify the
following control statements:

%LET KEEP =SMFMNPRN ABCODEO TRANCNT RESPTIME USRCPUTM FCTOTCT;

%KEEPDBD =; /* No fields from DBD data file required */
%LET SORTBY = SMFMNPRN ABCODEO;/*Summarize by abend code within region*
%LET SUMVARS = TRANCNT RESPTIME USRCPUTM FCTOTCT;/*fields to summarize*
%LET AVER =DUM1 RESP_AVG CPU_AVG FC_AVG; /*user-defined fields*/
%LET TOTAL =TRAN_CNT RESP_TOT CPU_TOT FC_TOT; /*for averages,totals*/

Appendix E. SAS historical reporting 315

 %LET MAX = DUM3 RESP-MAX DUM4 DUM5; /*and maximums */
%LET MIN =;
%LET PRINTBY =SMFMNPRN; /*print by region*/
%LET PRINTID =ABCODEO; /*first report field*/
%LET PRINT =TRAN_CNT RESP_AVG RESP_MAX RESP_TOT CPU_AVG CPU_TOT
FC_AVG FC_TOT; /*field sequence on print line*/
%LET FORMAT =; /*no special formatting needed*/
%LET HEADING =TRAN_CNT ="Total*Tran*Count" /*meaningful headings to*/
RESP_AVG = "Average*Response*Time*(Secs)" /*fields */
RESP_MAX = "Maximum*Response*Time*(Secs)"
RESP_TOT = "Total*Response*Time*(Secs)"
CPU_AVG = "Average*CPU*Time*(Secs)"
CPU_TOT = "Total*CPU*Time*(Secs)"
FC_AVG = "Average*File*Requests"
FC_TOT = "Total*File*Requests" ;
%KC2TGRW (EXIT=MYEXIT,HDR=ABEND CODE SUMMARY REPORT);
/*
//MYEXIT DD *
IF ABCODEO=:"00" THEN DELETE; /*exit to filter just abends*/
/*

Note: The aforementioned example shows four fields specified in SUMVARS, so four fields must
appear in AVER, TOTAL, MAX, and MIN. No minimum values are required, however, so this control
statement is coded with null values. DUM1 is a dummy variable that acts as a placeholder for
TRANCNT in the AVER control statement, since the average transaction count is not required. This
is also true for dummy variables DUM3, DUM4, and DUM5.
The Abend Code Summary Report is an example of a report produced from the data previously
mentioned.
List report of transactions using umbrella services
To produce a list report of transactions that use OMEGAMON umbrella transaction services, specify
the following control statements. This report shows the umbrella transaction ID, program name, and
the 32 - byte user work area. Only those transactions with an umbrella transaction ID or program
name are reported.

%LET KEEP =SMFMNPRN TRANNUM TRAN PGMNAME START USRCPUTM RESPTIME

MUMBPTC MUMBUSR MUSRWRK;
%KEEPDBD =; no fields from DBD datafile required*/
%LET SORTBY = SMFMNPRN TRANNUM;
%LET SUMVARS =; /*denotes a LIST type report */
%LET AVER =; /*therefore AVER */
%LET TOTAL =; /* and TOTAL */
%LET MAX =; /* and MAX */
%LET MIN =; /* and MIN are not used so set to null*/
%LET PRINTBY = SMFMNPRN; /* print by region */
%LET PRINTID = TRANNUM; /* first report field */
%LET PRINT = TRAN PGMNAME START USRCPUTM RESPTIME MUMBPTC
MUMBUSR MUSRWRK; /* field sequence on print line */
%LET FORMAT =; /*Use default formatting */
%LET HEADING =; /*no special heading requirements needed */
%KC2TGRW (CICS=TDOCS66,GROUP=WORKLOAD,
HDR=UMBRELLA TRANSACTION REPORT,EXIT=UMBEXIT);
/*
//UMBEXIT DD *
IF MUMBPTC=:”00”X AND MUMBUSR=:”00”X THEN DELETE; /*our filter criteria
/*

The Umbrella Transaction Report is an example of a report that is produced from the previously
mentioned data.
Replication of the supplied SAS report, KC2TRP3
You can use the Generalized Report Writer to replicate the supplied SAS report, KC2TRP3. Specify the
following control statements:

%LET KEEP =SMFMNPRN TRAN START TRANNUM TTYPE TERM RESPTIME

USRCPUTM FCTOTCT SUSPNDTM DISPWTTM ABCODEO;
%LET KEEPDBD =; /*no fields from DBD needed */
%LET SORTBY =SMFMNPRN START; /*by task start time in region*/
%LET SUMVARS =; /*this is a list report so */
%LET AVER =; /*none */
%LET TOTAL =; /*of */
%LET MAX =; /*these */
%LET MIN =; /*fields needed */
%LET PRINTBY =SMFMNPRN; /*print by region */

316 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 %LET PRINTID =TRAN; /*first field on the report */
%LET PRINT =START TRANNUM TRANTYPE TERM RESPTIME USRCPUTM FCTOTCT
SUSPNDTM DISPWTTM ABCODEO; /*other fields in order */
%LET HEADING =TRANTYPE='Tran*Type'; /*Tran Type is our
/*representation of TTYPE */
%LET FORMAT =SUSPNDTM DISPWTTM 8.3 FCTOTCT IN_K.
USRCPUTM 8.4;
%KC2TGRW (HDR=TRP3 EQUIVALENT REPORT,EXIT=MYEXIT,GROUP=WORKLOAD);
/*
//MYEXIT DD *
IF ABCODEO=: "00"X THEN DELETE;

The TRP3 Equivalent Report is an example of a report that is produced from the previously mentioned
data.

Building response time transaction groups

KC2TRXG, located in the KC2SPROG data set, is the Response Time Transaction Group Build program.
This program analyzes the SAS DETAIL data set and produces GROUP_DEFINITIONS and ID parameter
for each CICS system for which transaction data is found.

Group threshold values

KC2TRXG can produce 15 groups (GROUP_DEFINITIONS parameters) with default thresholds of 1-10, 15,
20, 30, 45, and 60 seconds, respectively. Ascending threshold values are assigned to the groups.
You can override the default group thresholds, but ensure that you assign thresholds an ascending value
for each group. If you have no requirement to use all 15 groups, assign the unused groups a value of zero.
Each analyzed transaction ID is assigned to one of the 15 groups. If a transaction cannot be assigned to a
specific group, a warning message is provided. For example, a message may occur because the calculated
response time threshold for a transaction exceeds the highest group threshold.

Using the KC2TRXG program

KC2TRXG is the SAS program that performs the response time transaction group build function. To run the
build function, customize and run the supplied job KC2TRXJ, located in the KC2SJCL data set, to produce
ID and GROUP_DEFINITIONS parameters. You can then insert these parameters into the global data area
module (GLOBAL_OPTIONS).
The KC2TRXGh program provides the following parameters:
CICS= ALL,xxxxxxxx
Determines whether SMF records relating to all or a specific or generic CICS applid are processed. For
example, CICS=PROD restricts processing to all CICS applids beginning with PROD. Alternatively, you
can specify CICS=ALL and use the EXIT= option to accommodate more specific processing. ALL is
the default setting.
LUNAME=ALL,xxxxxxxx
Processes all VTAM LUs and allows you to restrict processing to a specific or generic LUNAME. All is
the default setting.
GROUP=ALL,WORKLOAD,nn
Processes transactions that belong to all GROUPS defined in KC2GRP. Allows you to restrict
processing to a specific group of transactions. If you specify GROUP=WORKLOAD, then all transactions
belonging to GROUP 0 are ignored from all processing. All is the default setting.
SHIFT=ALL,nn
Restricts the selection criteria to a specific shift as defined in KC2SHFT. All is the default setting.
TERM=ALL,xxxx
Restricts the selection criteria to specific or generic terminal IDs. All is the default setting.
TRAN=ALL,xxxx
Restricts the selection criteria to a specific or generic transaction ID. All is the default setting.

Appendix E. SAS historical reporting 317

 USERID=ALL,xxxxxxxx
Restricts the selection criteria to a specific or generic userid. YES is the default setting.
LODATE=NO,mm/dd/yy
Restricts the selection criteria to a specific start date. NO is the default setting.
LOTIME=NO:,hh:mm:ss
Restricts the selection criteria to a specific start time. NO is the default setting.
HIDATE=NO,mm/dd/yy
Restricts the selection criteria to a specific end date. NO is the default setting.
HITIME=NO,hh:mm:ss
Restricts the selection criteria to a specific end time. NO is the default setting.
EXIT=NO,xxxxxxxx
Specifies the name of the exit program you write to allow greater selection criteria. NO is the default
setting.
STOP=NO,nnn
When set to a numeric value, restricts processing to a specified number of input records for debugging
purposes. NO is the default setting.
GROUP1=10,nn
Determines the threshold (in 10ths of a second) to be applied to this group. This value is equivalent to
the ELOG= parameter in the GROUP_DEFINITIONS parameter. 10 is the default setting.
GROUP2=20,nn
Determines the threshold (in 10ths of a second) to be applied to group 2. 20 is the default setting.
GROUP3=30,nn
Determines the threshold (in 10ths of a second) to be applied to group 3. 30 is the default setting.
GROUP4=40,nn
Determines the threshold (in 10ths of a second) to be applied to group 4. 40 is the default setting.
GROUP5=50,nn
Determines the threshold (in 10ths of a second) to be applied to group 5. 50 is the default setting.
GROUP6=60,nn
Determines the threshold (in 10ths of a second) to be applied to group 6. 60 is the default setting.
GROUP7=70,nn
Determines the threshold (in 10ths of a second) to be applied to group 7. 70 is the default setting.
GROUP8=80,nn
Determines the threshold (in 10ths of a second) to be applied to group 8. 80 is the default setting.
GROUP9=90,nn
Determines the threshold (in 10ths of a second) to be applied to group 9. 90 is the default setting.
GROUP10=100,nn
Determines the threshold (in 10ths of a second) to be applied to group 10. 100 is the default setting.
GROUP11=150,nn
Determines the threshold (in 10ths of a second) to be applied to group 11. 150 is the default setting.
GROUP12=200,nn
Determines the threshold (in 10ths of a second) to be applied to group 12. 200 is the default setting.
GROUP13=300,nn
Determines the threshold (in 10ths of a second) to be applied to group 13. 300 is the default setting.
GROUP14=450,nn
Determines the threshold (in 10ths of a second) to be applied to group 14. 400 is the default setting.
GROUP15=600,nn
Determines the threshold (in 10ths of a second) to be applied to group 15. 500 is the default setting.

318 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 Values must be assigned to groups using increasingly higher values. If you do not require a specific
group, then set its value to zero.
CHKVALU=SIGMA3,PCT90,PCT95,PCT99
Determines the threshold to use when deciding to which response time group to allocate the
transaction. (Sigma3 is equivalent to 3 * Standard Deviation + the Mean. SIGMA3 is the default
setting.

Determining relevant thresholds for the local environment

KC2TRXG produces a report that shows the group and calculated threshold for each transaction found.
You should review the report and determine whether the thresholds are relevant to the local environment.
You might decide that the calculation method used is inappropriate and that a more realistic threshold
might have to be applied manually. By default, the threshold used to determine the group into which a
transaction is assigned is based on 3*Standard Deviation plus the Mean; that is, Sigma3.
As an alternative to the default calculation, you might want to apply the 90th, 95th, or 99th percentile
threshold. You can rerun the report as often as required using the alternative algorithms, until a more
relevant result is achieved. You might find, however, that due to fluctuations in the analyzed data,
discrepancies might occur that can only be addressed by local knowledge and manual adjustment.
Therefore, you may want to run KC2TRXG against data for different days and compare the results before
applying them.
For each transaction ID, KC2TRXG produces a corresponding ID parameter and rounds up the specific
transaction threshold to the next tenth of a second. For example, a calculated response threshold of
0.461 is defined as THRESH=50 in the ID parameter.

Running the response time transaction group builder

To run the Response Time Transaction Group Builder, customize and run the supplied SAS macro
KC2TRXJ, located in the KC2SJCL data set, to produce the ID and GROUP_DEFINITIONS parameters.
You can later insert these parameters into the global data area module (GLOBAL_OPTIONS).
A report that is produced from KC2TRXG is Response Time Profile for Transactions by CICS Region.
This the Parameter Definitions List:

*
*
* DEFINITIONS FOR CICS REGION PROD
*
GROUP_DEFINITIONS INITIAL
GROUP_DEFINITIONS ID,GRP=1,GTYP=TRAN, X
NAME='PROD GROUP1',ELOG=10
GROUP_DEFINITIONS ID,GRP=2,GTYP=TRAN, X
NAME='PROD GROUP2',ELOG=20
GROUP_DEFINITIONS ID,GRP=3,GTYP=TRAN, X
NAME='PROD GROUP3',ELOG=30
GROUP_DEFINITIONS ID,GRP=4,GTYP=TRAN, X
NAME='PROD GROUP4',ELOG=40
GROUP_DEFINITIONS ID,GRP=5,GTYP=TRAN, X
NAME='PROD GROUP5',ELOG=50
GROUP_DEFINITIONS ID,GRP=6,GTYP=TRAN, X
NAME='PROD GROUP6',ELOG=60
GROUP_DEFINITIONS ID,GRP=7,GTYP=TRAN, X
NAME='PROD GROUP7',ELOG=70
GROUP_DEFINITIONS ID,GRP=8,GTYP=TRAN, X
NAME='PROD GROUP8',ELOG=80
GROUP_DEFINITIONS ID,GRP=9,GTYP=TRAN, X
NAME='PROD GROUP9',ELOG=90
GROUP_DEFINITIONS ID,GRP=10,GTYP=TRAN, X
NAME='PROD GROUP10',ELOG=100
GROUP_DEFINITIONS ID,GRP=11,GTYP=TRAN, X
NAME='PROD GROUP11',ELOG=150
GROUP_DEFINITIONS ID,GRP=12,GTYP=TRAN, X
NAME='PROD GROUP12',ELOG=200
GROUP_DEFINITIONS ID,GRP=13,GTYP=TRAN, X
NAME='PROD GROUP13',ELOG=300
GROUP_DEFINITIONS ID,GRP=14,GTYP=TRAN, X
NAME='PROD GROUP14',ELOG=450

Appendix E. SAS historical reporting 319

 GROUP_DEFINITIONS ID,GRP=15,GTYP=TRAN, X
NAME='PROD GROUP15',ELOG=600
GROUP_DEFINITIONS FINAL
*
ID INITIAL,SCALE=2,WINDOW=10
*WARNING*
* TRANSACTION LSR1 COULD NOT BE PUT IN ANY GROUP
*WARNING*
*WARNING*
* TRANSACTION MIKE COULD NOT BE PUT IN ANY GROUP
*WARNING*
*WARNING*
* TRANSACTION MISC COULD NOT BE PUT IN ANY GROUP
*WARNING*
*WARNING*
* TRANSACTION OEN2 COULD NOT BE PUT IN ANY GROUP
*WARNING*
*WARNING*
* TRANSACTION QTDI COULD NOT BE PUT IN ANY GROUP
*WARNING*
*WARNING*
* TRANSACTION QTI1 COULD NOT BE PUT IN ANY GROUP
*WARNING*
*WARNING*
* TRANSACTION QTS2 COULD NOT BE PUT IN ANY GROUP
*WARNING
ID ID,TRAN=AADD,GROUPS=(1),THRESH=1
IDID ID,TRAN=AC2A,GROUPS=(1),THRESH=4
ID ID,TRAN=AC20,GROUPS=(1),THRESH=2
ID ID,TRAN=AC22,GROUPS=(1),THRESH=3
ID ID,TRAN=AC28,GROUPS=(1),THRESH=7
ID ID,TRAN=AMNU,GROUPS=(1),THRESH=1
ID ID,TRAN=AUPD,GROUPS=(1),THRESH=8
ID ID,TRAN=DEGE,GROUPS=(1),THRESH=3
ID ID,TRAN=IDMS,GROUPS=(1),THRESH=2
ID ID,TRAN=LSRW,GROUPS=(1),THRESH=1
ID ID,TRAN=OAD1,GROUPS=(1),THRESH=1
ID ID,TRAN=OAID,GROUPS=(1),THRESH=2
ID ID,TRAN=OENQ,GROUPS=(1),THRESH=1
ID ID,TRAN=OICE,GROUPS=(1),THRESH=1
ID ID,TRAN=OIC1,GROUPS=(1),THRESH=4
ID ID,TRAN=OMEG,GROUPS=(1),THRESH=2
ID ID,TRAN=PAIN,GROUPS=(1),THRESH=6
ID ID,TRAN=RAID,GROUPS=(1),THRESH=1
ID ID,TRAN=STAT,GROUPS=(1),THRESH=4
ID ID,TRAN=STR1,GROUPS=(1),THRESH=2
ID ID,TRAN=VADD,GROUPS=(1),THRESH=1
ID ID,TRAN=VAD1,GROUPS=(1),THRESH=5
ID ID,TRAN=VBR1,GROUPS=(1),THRESH=10
ID ID,TRAN=VSTR,GROUPS=(1),THRESH=1
ID ID,TRAN=WD80,GROUPS=(1),THRESH=4
ID ID,TRAN=ABRW,GROUPS=(2),THRESH=17
ID ID,TRAN=AINQ,GROUPS=(2),THRESH=13
ID ID,TRAN=DEGS,GROUPS=(2),THRESH=13
ID ID,TRAN=INIT,GROUPS=(2),THRESH=11
ID ID,TRAN=QMNU,GROUPS=(3),THRESH=21
ID ID,TRAN=QTS1,GROUPS=(3),THRESH=30
ID ID,TRAN=DEGG,GROUPS=(4),THRESH=31
ID ID,TRAN=QTSA,GROUPS=(4),THRESH=39
ID ID,TRAN=DEGC,GROUPS=(5),THRESH=42
ID ID,TRAN=QTSM,GROUPS=(6),THRESH=56
ID ID,TRAN=VBRW,GROUPS=(7),THRESH=62
ID ID,TRAN=DEGT,GROUPS=(9),THRESH=89
ID ID,TRAN=QTDG,GROUPS=(9),THRESH=83
ID ID,TRAN=DEGV,GROUPS=(10),THRESH=99
ID ID,TRAN=DEGA,GROUPS=(14),THRESH=399
ID ID,TRAN=MANT,GROUPS=(14),THRESH=425
ID ID,TRAN=VSEX,GROUPS=(14),THRESH=329
ID FINAL
*
*END OF DEFINITIONS FOR PROD

320 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Appendix F. OMEGAMON for CICS optional features
This section contains configuration information on some optional features that you can use in
OMEGAMON for CICS.

Enabling monitoring for user-defined events

This information is about enabling monitoring for user-defined events. Monitoring for user-defined events
allows you to monitor the performance of CICS applications and display the results you are monitoring in
OMEGAMON for CICS.

Background about monitoring for user-defined events

When you enable monitoring for user-defined events, you can monitor any event in a CICS application.
Use this feature for the following tasks:
• Collecting clock and counter statistics for an event including up to 10 functions for the event
• Displaying the results in OMEGAMON for CICS
The clock and counter statistics are displayed in the following locations in OMEGAMON for CICS:
• Task File Statistics Eventname panel
• Task History panel
• Task History Details panel
• Task History Eventname Resources panel
• Task History Eventname Details panel
• Application Trace panel

The process for monitoring for a user-defined event

The following information provides an overview of the process you follow to enable monitoring for events.
• When you specify the monitoring options for the product in the Global Data Area, specify the event and
the parameters for the event.
• In the code for the application, specify a call to the subroutine before and after the event you want to
monitor.

Specifying a user-defined event and parameters for the event

In the Global Data Area, use USREVNT1 to specify the event you want to monitor.
Table 95 on page 321 shows the parameters you can specify for the event and the values you can use.

Table 95. Parameters available for USREVNT1

Parameter Purpose Valid Value
AUTO_START Specifies whether or not collection starts YES or NO
automatically.
ONDV_WRITE Specifies whether or not include or exclude YES or NO
statistics for the task history collector.
SMF_WRITE Specifies whether or not to write statistics to SMF. YES or NO

© Copyright IBM Corp. 2004, 2022 321

 Table 95. Parameters available for USREVNT1 (continued)
Parameter Purpose Valid Value
EVENT Specifies the name you want for the event. 1 to 8 character string
(OMEGAMON for CICS displays this name on the
panels where the event occurs.)
FUNCTION Specifies up to 10 function names that can be 1 to 8 character string
displayed for the event.

Event example
This event example has the following characteristics.
• Collection starts automatically.
• Statistics are available for the task history collector.
• Statistics are not written to SMF.
• OMEGAMON for CICS displays the event on the panels as SALTLAKE.
• OMEGAMON for CICS displays the functions ADD, DELETE, BROWSE, UPDATE, and READ when details
are displayed for the event.

<<USREVNT1>>
AUTO_START=YES
ONDV_WRITE=YES
SMF_WRITE=NO
EVENT=SALTLAKE
FUNCTION=(ADD, DELETE, BROWSE, UPDATE, READ)

Specifying the call to the subroutine in the application

In the code for the application, you must also call the subroutine before and after the event you want to
monitor.
OMEGAMON for CICS provides samples of the code you use to monitor the event and this information
covers how to use the samples.

Sample code provided by OMEGAMON for CICS

OMEGAMON for CICS provides samples of the code you use to monitor the event. The samples are
located in hilev.midlev.TKANSAM and thilev.midlev.TKANMAC libraries.
Table 96 on page 322 shows the name of the data set and member that contains the sample code and
provides the purpose of the sample provided.

Table 96. Data set and member purpose for event monitoring sample code
Data set and member Purpose
thilev.midlev.TKANSAM( KOCUE1DR) Driver program that collects the records for the
event.
thilev.midlev.TKANSAM(KOCAUE1) When the records are collected, DSECT you
can use to map the SMF type 112 records for
Assembler.
thilev.midlev.TKANSAM(KOCCUE1) When the records are collected, DSECT you can
use to map the SMF type 112 records for COBOL.
thilev.midlev.TKANSAM(KOCPUE1) When the records are collected, DSECT you can
use to map the SMF type 112 records for PLI.

322 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Table 96. Data set and member purpose for event monitoring sample code (continued)
Data set and member Purpose
thilev.midlev.TKANSAM(KOCSUE1) When the records are collected, DSECT you can
use to map the SMF type 112 records for SAS.
thilev.midlev.TKANMAC(KOCAUE1D) Macro used by the driver to map the parameter list.
thilev.midlev.TKANMAC (KOCUE1) Macro used by the driver to generate the storage
definitions for the output fields.
thilev.midlev.TKANMAC (KOCAUE1) Macro used by the driver to generate online code
that calls the OMEGAMON for CICS code.
Note: You might have to alter the register
convention to adhere with your coding standards.

Where to specify the call for the subroutine in the application

The table in this section shows where you specify the call for the subroutine.
• The first column shows the order in the application before you add the subroutine.
• The other column shows the order in the application after you add the call for the subroutine.

Table 97. Where to specify the call to the subroutine for monitoring user-defined events
Application before you add the subroutine Application after you add the subroutine
Your Application Code Your Application Code
User Event • Location to add the code to build the parameter
list and the call to OMEGAMON for CICS to start
Your Application Code
to monitor the event.
User Event
• Location to add the code to build the parameter
list and the call to OMEGAMON for CICS to stop
the monitoring for the event.
Your Application Code

What to specify in your application code before the user event

Follow these instructions to add the code to build the parameter list and add the call to OMEGAMON for
CICS to start monitoring the user event.
The instructions use the following examples:
• The event name is SAMPLE.
• The resource name is TESTING.
• The function defined in the Global Data Area is SUBTRACT.
1. Build the PLIST using DSECT KOCAUE1D (located in thilev.midlev.TKANMAC).
• Move value START into field CALLER_COMMAND
• Move value TESTING into CALLER_RESOURCE_NAME
• Move value SUBTRACT into CALLER_FUNCTION_TYPE
• Move a return code (RC) into CALLER_STATUS (optional)
2. Call KOCUE1DR ensuring that the address of the parameter list is passed in register 1. (KOCUE1DR is
located in thilev.midlev.TKANSAM.)

Appendix F. OMEGAMON for CICS optional features 323

 What to specify in your application code after the user event
Follow these instructions to add the code to build the parameter list and call OMEGAMON for CICS to stop
monitoring the user event.
The instructions use the following examples:
• The event name is SAMPLE.
• The resource name is TESTING.
• The function defined in the Global Data Area is SUBTRACT.
1. Build the PLIST using DSECT KOCAUE1D (located in thilev.midlev.TKANMAC).
• Move value STOP into field CALLER_COMMAND
• Move value TESTING into CALLER_RESOURCE_NAME
• Move value SUBTRACT into CALLER_FUNCTION_TYPE
• Move a return code (RC) into CALLER_STATUS (optional)
2. Call KOCUE1DR ensuring that the address of the parameter list is passed in register 1. (KOCUE1DR is
located in thilev.midlev.TKANSAM.)

System Management Facility considerations

This section describes interval, system-related, and task-related records and the ways to start, stop, and
limit their logging to SMF.
OMEGAMON for CICS writes interval, system-related, and task-related records to the IBM System
Management Facility (SMF). You can use these records to produce historical reports of your system’s
performance.
You specify all the options for SMF logging using the Global Data Area.
Depending on the options you specified in your Global Data Area for collecting data, OMEGAMON for CICS
can write many records per second to SMF. Therefore, make sure your site has enough storage in your
SMF data sets for these records.

System Management Facility record type

For CICS transaction records, the record type is 110. For all other SMF records, it is 112. Audit records are
specified in the SMFNUM control statement.
Note: Security audit records do not have a default record type.

Record layout
Each record produced by OMEGAMON contains a standard SMF header followed by an OMEGAMON for
CICS (3270) header common to all the records. You must use the OMEGAMON for CICS (3270) header to
identify the record type.
The library thilev.TKANSAM contains Statistical Analysis System (SAS), COBOL, and PL/I record layouts
for all the records written by the OMEGAMON for CICS component. The record layout for the SMF 110
records and OMEGAMON for CICS (3270) header portion is found in member:
• KOCSSMF for SAS records
• KOCCSMF for COBOL records
• KOCPSMF for PL/I records
The library thilev.TKANMAC contains assembler record layouts. The record layout for the SMF and
OMEGAMON for CICS (3270) header portion is found in member KOCSMF in thilev.TKANMAC.
For specific member names of each record layout, refer to the following sections.
– “Interval records” on page 194

324 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 – “System records” on page 194
– “File and database records” on page 195
– “Transaction records” on page 196
– “Dictionary records” on page 196

Interval records
An interval record contains one-minute summaries of response time, bottleneck, and resource
information.
Frequency of records
The number of records depends on the number of buckets generated by such features as the internal
bottleneck collector and the response time collector.
Approximate record length
The length depends on the number of element IDs containing response time data and the number of
unique wait reasons detected by the internal bottleneck collector during the interval.
Controls
Records are written only if the interval record collector is active. The collector starts automatically, if
the AUTO parameter is specified with the INTR keyword, when the monitoring options were specified
for the product using the Global Data Area. You can manually start and stop the collector from
an OMEGAMON for CICS (3270) session by selecting the Control option on the Main Menu in the
OMEGAMON for CICS (3270) interface.
Post processing
OMEGAMON for CICS supplies a program to extract the records and produce reports. The job is in the
thilev.TKANSAM(KOCREPT).
Record description
See the KOCSINTR, KOCCINT2, KOCPINTR, and KOCAINTR members in thilev.TKANSAM for the SAS,
COBOL, PL/I, and assembler record layouts.

System records
Each time OMEGAMON for CICS (3270) starts and stops monitoring a CICS region, OMEGAMON for CICS
(3270) creates a system record that contains z/OS-related statistics as well as copies of the CSA and
system initialization table (SIT) from CICS.
This can happen in either of the following ways:
• OMEG INIT or OMEG SHUT
• PLT startup or shutdown when the KOCOME00 program is run.
Frequency of records
One record when OMEGAMON for CICS (3270) starts to monitor a CICS region and one record when
OMEGAMON for CICS (3270) stops monitoring a CICS region.
Approximate record length
Record length depends on the version of your CICS Transaction Server.
• V3.1.0 approximately 5912 bytes
• V3.2.0 approximately 5912 bytes
• V4.1.0 approximately 6776 bytes
• V4.2.0 approximately 6616 bytes
Controls
Writing of records is controlled by the Global Data Area WRITE_SYSTEM_RECORDS parameter. If it is
set to YES, system records are written; if it is set to NO, system records are not written; if it is set to
CMF, the setting of the Global Data Area CICS_CMF_WRITE parameter determines if system records
are written. For example, CICS_CMF_WRITE=YES or CICS_CMF_WRITE=NO.

Appendix F. OMEGAMON for CICS optional features 325

 Post processing
OMEGAMON for CICS converts these records to produce the System Detail Report.
Record description
Refer to the KOCSSREC, KOCCSREC, KOCPSREC, and KOCASREC members of thilev.TKANSAM for the
SAS, COBOL, PL/I, and assembler record layouts.

File and database records

OMEGAMON for CICS produces records detailing the file and database usage for each CICS transaction.
These records contain counts and elapsed times for each type of file or database command that a
transaction issues. These records are intended to be used along with the CICS type 110 SMF records.
The creation of file and database SMF records is controlled by the DATABASE_COLLECTION keyword in
the Global Data Area. You must define one for each file or database product for which you want data
collected. In addition, third-party products require the steps described in “Installing third-party support”
on page 196.
Frequency of records
One record for each transaction for each file or database product used by the transaction. If a single
transaction accesses both DL/I and native VSAM, a file and a database record (2 records) is produced.
One record contains DL/I statistics, and the other record contains VSAM statistics.
Approximate record length
Each record has a totals segment followed by a detail segment for each file or database accessed
during the transaction. The number of files or databases accessed during the life of the transaction
determines the number of bytes in each record.
Controls
Records are written based on the parameter in the DATABASE_COLLECTION keyword in the Global
Data Area for the particular file or database product. You can also turn logging on or off dynamically
from an OMEGAMON for CICS (3270) session by selecting the Control option on the Main Menu in the
OMEGAMON for CICS (3270) interface.
Post processing
Use the CICS Performance Analyzer for z/OS program to process these 112 records; it produces a
transaction level report on file usage by transaction.
Record description
Table 98 on page 326 lists the type of file or database and the member names in the thilev.TKANSAM
library where you can find sample record layouts.

Table 98. Location of file or database sample record layouts

File or database type Programming language Member name
File Control (VSAM) SAS COBOL PL/1 assembler KOCSVSAM KOCCVSAM KOCPVSAM
KOCAVSAM
ADABAS SAS COBOL PL/1 assembler KOCSADA KOCCADA KOCPADA KOCAADA
CA-DATACOM SAS COBOL PL/1 assembler KOCSDCOM KOCCDCOM KOCPDCOM
KOCADCOM
DL/I SAS COBOL PL/1 assembler KOCSDLI KOCCDLI KOCPDLI KOCADLI
IDMS SAS COBOL PL/1 assembler KOCSIDMS KOCCIDMS KOCPIDMS
KOCAIDMS
SUPRA SAS COBOL PL/1 assembler KOCSSUPR KOCCSUPR KOCPSUPR
KOCASUPR
MQ SAS COBOL PL/1 assembler KOCSMQ KOCCMQ KOCPMQ KOCAMQ

326 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Transaction records
Transaction records contain resource usage and performance-related statistics for each CICS transaction.
Transaction records are produced by CMF.
CICS Transaction Server produces the following records:
• For each conversation if MNCONV=YES is coded in the SIT
• At each syncpoint if MNSYNC=YES is coded in the SIT
• At the interval specified if MNFREQ is coded with a valid time value
• Every time an EXEC CICS MONITOR request is processed to deliver data for a valid Event Monitoring
Point
• During normal end-of-task processing
Frequency of records
Data is written to a buffer for each transaction or conversation. When the buffer is full, the contents
are written to SMF. The rate at which the buffer fills and is written to SMF varies with the rate of
transactions.
Approximate record length
The length of the record depends on the release of CICS and what is coded in the MCT (field
inclusions, exclusions or user EMPs).
Controls
CICS Transaction Server writes records to SMF unless they are suppressed with the
CICS_CMF_RECORDS keyword set to NO. If you want CMF records in CICS TS, you must set the
CICS_CMF_WRITE keyword to YES. You can also selectively suppress the writing of transaction
records based on transaction ID, refer to the USER_EVENT_MONITORING keyword in the Global Data
Area for more information.
Post processing
You can convert these records and use the historical reporter to produce batch reports.
Record description
Refer to the KOCSTRAN, KOCCTRAN, and KOCPTRAN members in thilev.TKANSAM for the SAS,
COBOL, and PL/I record layouts. In addition, refer to these members to map the OMEGBSC event
monitoring point, which is part of the transaction record. For general information on all of these
members, see KOC$DEF.

Dictionary records
Dictionary records describe the contents of SMF type 110 records and are required when reporting on
transaction records.
OMEGAMON for CICS writes a dictionary record during CICS startup or whenever CMF recording of
transaction records can be enabled by, for example, a CEMT SET MONITOR command.

Installing third-party support

OMEGAMON for CICS can monitor several third-party database and fourth-generation language products.
This section describes how to install support for the products.
These are the supported database products:
• ADABAS
• CA-DATACOM
• IDMS (excluding UCF applications)
• SUPRA
OMEGAMON for CICS provides the following information:

Appendix F. OMEGAMON for CICS optional features 327

 • Count and elapsed times of database calls per transaction. This data is available through Task History
panels of the OMEGAMON for CICS (3270) interface, the ONDV command of the OMEGAMON for CICS
(3270) interface, or as SMF records for batch historical reporting.
• The database name. This data is collected as part of the waiting resource name during the database
call. The waiting resource name is used in the task display and internal bottleneck analysis.
The fourth-generation language products supported are:
• CA-IDEAL
• GENER/OL
• Millennium
• NATURAL
• PCS
• UFO/Forms
OMEGAMON for CICS (3270) supplies the application name as the umbrella program name on the Task
History panels of the 3270 interface, ONDV command output in the interface, and in SMF 110 records for
historical reporting.
Note:
1. The supported products and the steps you must take to provide that support can change. Before
installing support for any of the third-party products listed, you must
• Check the Preventative Service Planning (PSP) documentation
• Contact IBM Software Support to ensure that you have the latest support and any required
maintenance.
2. When installing a new release of OMEGAMON for CICS or doing a major maintenance upgrade,
investigate whether you have to implement the TPPS facilities again.

Installing ADABAS support

The Tivoli OMEGAMON support for ADABAS has two user exits that you must assemble and link-edit into
the ADABAS/CICS interface module during installation.
There are several versions of the exits provided by OMEGAMON, which one you require, depends on your
ADABAS version and configuration.
If you are using a driver program to run multiple exits at either ADABAS exit point, you must modify the
supplied exits to conform to the standards required by the driver program.
If you are a user of ADABAS and Software AG's VISTA, use the VISTA file translation facility. If you
want to monitor FILE/DATABASE usage using the file numbers as translated by VISTA, use the exits
and JCL defined in the KOCADAVI member of thilev.TKANSAM library. See the KOCADVII member of
thilev.TKANSAM library for further instructions. If you do not need to monitor the VISTA translated FILE /
DATABASE number, use the ADABAS sample exits for your version of ADABAS.
If you are using ADABAS Version 7, and you are not using the VISTA exits, use the exits and JCL defined in
the KOCADAV7 member of thilev.TKANSAM library. See the KOCADV7I member of thilev.TKANSAM library
for further instructions.
If you are not using the Vista exits and are using ADABAS version 8, use the exits and JCL defined in the
KOCADAV8 member of thilev.TKANSAM library. See the KOCADV8I member of thilev.TKANSAM library for
further instructions.

Installing CA-DATACOM and CA-IDEAL support

Support for CA-DATACOM is available for Versions 8 to 12 inclusive.
1. Modify a copy of the CA-DATACOM exit DCCTXPR as follows:
a. Change the line:

328 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 TEMP B RETURN SKIP THE COREMARK

to

TEMP B OVERHEAD SKIP THE COREMARK

b. After OVERHEAD label add the following line:

KOCDC832 ,

2. Assemble and link-edit DCCTXPR.

a. Modify the CA-supplied JCL as follows:
b. Assemble step: Point SYSIN to the modified copy of DCCTXPR:

//SYSIN DD DISP=SHR,DSN=your.source.lib(DCCTXPR)

c. Add OMEGAMON TKANMAC to SYSLIB concatenation:

//SYSLIB DD DISP=SHR,DSN=...............
// DD DISP=SHR,DSN=thilev.TKANMAC

Note: Be sure to use the latest CICS, DATACOM, and OMEGAMON CICS macro libraries for the
assembly.
d. Link step: Add OMEGAMON CICS TKANMOD as SYSLIB:

//SYSLIB DD DISP=SHR,DSN=thilev.TKANMOD

Note: If your configuration uses the SMP libraries, include thilev.TKANMOD in the SYSLIB
concatenation.
e. Modify the control statements to include an OMEGAMON CICS module, for example:

// DD *
INCLUDE SYSLIB(KOCFIN00)
NAME DCCTXPR(R)

3. Specify <<DATACOM>> in the <DATABASE_COLLECTION> section of the Global Data Area.

Installing GENER/OL support

To install GENER/OL support, follow these steps:
1. Add an entry to the PPT for KOCGENcc, with the attributes of assembler and resident.
2. Replace the cc in KOCGENcc with the 2-character suffix that represents the version you are running, as
shown in the following table.

Table 99. Suffix for Transaction Server by version

CICS Transaction Server release Suffix
3.1 CA
3.2 DA
4.1 EA
4.2 FA
3. Select option 4, Security, from the GENER/OL Customize Task Exit Parameters panel. The System
Administration menu is displayed.
4. Select option 4, Customize, from the System Administration menu. The Customize Task
Parameters menu is displayed .
5. Enter the following information on the Customize Task Parameters menu:

Appendix F. OMEGAMON for CICS optional features 329

 • KOCGENcc for the program name
• L for Use Branch Entry or CICS Link
• YES for GENER/OL Initialization
• NO for all other fields
6. Restart GENER/OL.

Installing IDMS support

This section describes how to install IDMS support for Versions 10 and 12.
To install support for IDMS, you must modify the IDMS-supplied macro IDMSINTC with the supplied
macros by completing the following procedure.
1. Make a copy of the IDMSINTC macro.
• For V10, modify this copy by inserting KOCAIDMS START after the statement that generates the
following set of installation instructions.

IDMSINC1 STM R14,R12,12(R13)

L R9,BASE
LR R8,R13
L R13,CSAADDR
L R12,CSACDTA
KOCAIDMS START

Insert KOCAIDMS STOP after the statement that generates the following set of installation
instructions.

IDMSINC2 STM R14,R12,12(R13)

L R9,BASE
LR R8,R13
L R13,CSAADDR
L R12,CSACDTA
KOCAIDMS STOP

• For V12, make a copy of the IDMSINTC macro. Modify this copy by inserting the statement
KOCAID12 START as shown. The instructions are located near the label NOOPTI.

L R1,CALLERSV+24 R1 -> CALLER’S PLIST

KOCAID12 START
B *(R5)

Insert the statement KOCAID12 STOP as shown.

XXIDMS DS 0H
KOCAID12 STOP
B *(R5) GO BASED ON TYPE OF CALL

2. Reassemble and link the module. You must include the thilev.TKANMAC and the IBM AMODGEN data
sets in the SYSLIB concatenation for the assemble step.
The link-edit step must also include:
a. The thilev.TKANMOD library in the SYSLIB concatenation
Note: If your configuration uses the SMP libraries, include thilev.TKANMOD in the SYSLIB
concatenation.
b. The following control statement for the linkage editor:

INCLUDE SYSLIB(KOCFIN00)

Save a copy of the IDMSINTC source prior to making any changes.

3. Specify NAME=IDMS for DATABASE_COLLECTION in the Global Data Area.
Note: IDMS support does not cover UCF, non-Data-Manipulation-Language (DML) queries through the
IDMS Dedicated Mode facility, because no DML requests are issued from the CICS region.

330 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Installing Millennium support
To install Millennium support, you must define the user event monitoring point OMEGBSC to your MCT.
You must also add USER_EVENT_MONITORING and STARTUP_CONTROL to specify the name of the user
event monitoring point.
To install Millennium support, follow these steps:
1. Change the Millennium program M2X000:
a. Add the following lines to the working storage section:

01 OMEG-WORK AREA.
05 OMEG-REQ PIC S9(8) COMP VALUE +7.
05 OMEG-SCRID PIC X(5) VALUE SPACE.

b. Add the following lines after the label L000-Process-Security.

MOVE TS-SCR-SCREEN TO OMEG-SCRID.

CALL KOCRMCLL USING OMEG-REQ OMEG-SCRID.

2. Recompile and re link M2X000, in the following way:

a. Add the rhilev.RKANMOD library to the SYSLIB statement of the link-edit step.
Note: If your RTE uses the SMP libraries, include thilev.TKANMOD in the SYSLIB concatenation.
b. Add the statement INCLUDE SYSLIB(KOCRMCLL) to the link-edit SYSIN.
3. Examine the output of the compile and link-edit for any error messages. Be sure that the KOCRMCLL
reference was resolved during link-editing.

Installing NATURAL support

The OMEGAMON for CICS NATURAL support runs as an exit to the NATURAL Review Data Collector.
Both the NATURAL Review Data Collector and the OMEGAMON for CICS NATURAL support exit must be
link-edited into a NATURAL Shared Nucleus (NSN).
The OMEGAMON for CICS NATURAL support exit is a TP-specific module for the CICS environment, and,
as such, must be included as part of a Single-Environment Shared Nucleus for CICS. Refer to the NATURAL
Operations Manual for more information regarding the NATURAL Shared Nucleus, TP-specific modules,
and Single-Environment Shared Nuclei.
To install NATURAL support, follow these steps:
1. Verify that the OMEGAMON for CICS NATURAL support exit is available. This is program KOCATL00
found in the rhilev.RKANMOD library.
2. It is important to follow the instructions found in the NATURAL Operations Manual for the creation of
an NSN as a Single-Environment Shared Nucleus. OMEGAMON exit RDCOMON must be defined as a
user exit for the Natural Data Collector, for example:

NTRDC ON,EXIT=(RDCOMON),SIZE=2

3. Follow the instructions for link-editing the NATURAL Review Data Collector, NATRDC, into an NSN as
provided by the vendor.
4. Add the following DD statement for the OMEGAMON for CICS load library to the job used to link-edit
the NSN:

//RKANMOD DD DISP=SHR,DSN=rhilev.RKANMOD

Note: If your RTE uses the SMP libraries, add the following DD statement instead:

//RKANMOD DD DISP=SHR,DSN=thilev.TKANMOD

5. Add the following linkage-editor control statement to the linkage-editor input stream after the
INCLUDE statement for NATRDC:

Appendix F. OMEGAMON for CICS optional features 331

 INCLUDE RKANMOD(KOCATL00)

Installing PCS support

To install PCS support follow these steps. You must also add USER_EVENT_MONITORING and
STARTUP_CONTROL to specify the name of the user event monitoring point
1. Make the following changes to the PCS program DOCSCMAN:
a. Locate the statement

PERFEMP SENTER

b. After the instruction

MVC WKASCNAM,TWASCAM

Add the following instructions if you have PCS V1R2:

ST 13,DFHEIR13
LA 13,DFHEISA
MVC WKAFNCID(4),=F’7’
LA 14,WKAFNCID
LA 15,WKASCNAM
CALL KOCRMCLL,((14),(15)),VL
L 13,DFHEIR13

Add the following instructions if you have PCS V1R3:

MVC WKAFNCID(4),=’7’
LA 14,WKAFNCID
LA 15,WKASCNAM
CALL KOCRMCLL,((14),(15)),VL

2. Assemble and link-edit DOCSCMAN.

a. Add the rhilev.RKANMOD library to the SYSLIB statement of the link-edit step.
Note: If your RTE uses the SMP libraries, include thilev.TKANMOD in the SYSLIB concatenation.
b. Add the statement to SYSIN

INCLUDE SYSLIB(KOCRMCLL)

3. Examine the output of the ASM.

a. Link-edit for any error messages.
b. Make sure the KOCRMCLL sub routine was resolved in the link-edit step.
4. Recycle your CICS region.

Installing SUPRA support

To install SUPRA 2.7 and higher support follow these steps:
1. Add KOCSU27B to CSTK0001 as detailed in sample KOCSU27B.
2. Add KOCSU27A to CSTK0002 as detailed in sample KOCSU27A.
3. Use the sample JCL in the SUPRA PDM Administrator Guide to assemble CSTK0001 and link edit
CSTEXT01 and assemble CSTK0002 and link edit CSTEXT02.
a. When link editing, include the thilev.TKANMOD library in the SYSLIB concatenation sequence and
add the following statement to SYSIN:

INCLUDE SYSLIB(KOCFIN00)

332 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 4. Use the sample JCL in the SUPRA PDM Administrator Guide to relink SUPRA PDM interface for the
CSTXCSMT CICS module.
Verify that the new CSTXCSMT CICS module is in use in the CICS region.

Installing UFO/Forms support

To install UFO/Forms support, follow these steps.
1. Add an entry to the PPT for KOCUFO00 with the attributes of assembler and resident.
2. Identify KOCUFO00 as an accounting exit to UFO/Forms. You can do this in one of the two following
ways:
• Use the CICS utility UFOINIT. (The change remains in effect only as long as is running.)
• Update the CICS UFMAINIT macro. (The exit is always available.)
For more information about installing UFO/Forms, see the section on Accounting Exits in the UFO/Forms
Customization and Operation Guide.

Umbrella transaction services

CICS business applications can run different functions under a single CICS transaction name. These
applications are often called umbrella applications and they enable you to analyze transactions from a
different perspective.
These applications typically display a general menu of choices or selections, but all their processing is
done under the single transaction name, which is used to call up the application's main menu. Although
efficient in some ways, important details, such as metrics and statistics about the application's functions
in task history and system performance reports, can be difficult to interpret. OMEGAMON for CICS on
z/OS and CICS each have an API feature for replacing the CICS tasks' original transaction names with
more meaningful transaction names.
OMEGAMON for CICS supplies the KOCRMCLL and KOCGLCLL subroutines; these subroutines modify
certain values associated with a transaction.

Using subroutines
This information describes the KOCRMCLL and KOCGLCLL subroutines and how to use them.
Use the KOCRMCLL and KOCGLCLL, subroutines to do the following tasks:
• Supply an additional transaction ID for task analysis, the response time collector, task history collector,
and SMF records
• Supply an additional program name for task analysis, the response time collector, task history collector,
and SMF records
• Supply a different resource name and resource type for task analysis and internal bottleneck analysis
• Supply an additional 32 bytes of data for each task record written to SMF
• Change the Resource Limiting status of the monitored transaction. You can turn resource limiting (RLIM)
off, or on, for the transaction which issues the request. This allows for a temporary suspension of RLIM
processing during the life of a transaction which you might not want RLIM to cancel at that point. Any
activity that occurs during this suspension of RLIM counts toward the totals used later in RLIM warn and
kill threshold calculation. An additional option allows you to query the status of RLIM monitoring for a
given transaction.
• Supply Web Service name and Operation name for SOAP requests processed in CICS to allow displaying
of the transactions related to CICS Web Services in OMEGAMON for CICS for z/OS.
The KOCRMCLL and KOCGLCLL subroutines replace the umbrella service facility from prior releases of
OMEGAMON for CICS. All programs using OMUMBSUB or UMBFIND must be converted to use these new
routines. OMUSEREC is no longer supported.

Appendix F. OMEGAMON for CICS optional features 333

 KOCRMCLL and KOCGLCLL provide similar functions. Their use depends on the CICS environment in which
they are called.
KOCRMCLL can run as part of any CICS application code, including a CICS task-related user exit. It cannot
be used in a CICS global user exit.
Prior to the call to KOCRMLL, you have to acquire a standard save area. Store register one (holding the
pointer to the parameter list for KOCRMLL) in the correct position in this save area (ST 1,24,(13) or STM
14,12,12(13), where register 13 addresses the new save area). Chain the new save area to the previous
one.
KOCGLCLL can run as part of any CICS application code and any CICS global user exit.
When either KOCRMCLL or KOCGLCLL is started, the fields that are changed stay in effect until a
subsequent call changes or clears them. A field is cleared at the end of a conversation if CONV=YES
is specified in the CICS monitoring control table (MCT). You can retain the field across conversations.
If you want to use these fields for the historical display panels such as the task history and response
time, you must define a user event monitoring point for the basic section. For task analysis and internal
bottleneck analysis, the event monitoring point is not required.
Note: If you want more information, see the KOCAPITX member in the thilev.TKANSAM library.

Subroutine call syntax and parameters

This is the syntax for calling the KOCRMCLL subroutine.

CALL KOCRMCLL,(request,parm),VL

These are the parameters for the KOCRMCLL subroutine call:

request
The full word containing the number of the requested operation. For the list of possible requests, see
Figure 28 on page 335.
parm
The area of storage used to move a value into or a field out of the transaction record. See Figure 28 on
page 335 for the required length, which depends on the request.
VL
The end of the list of parameters.
This is the syntax for calling the KOCGLCLL subroutine:

CALL KOCGLCLL,(workarea,rc,request,parm),VL

The parameters for the KOCGLCLL subroutine call are described in the following list:
workarea
The full word that must be initialized to hexadecimal zeroes the first time the KOCGLCLL subroutine is
used. Subsequent calls to the KOCGLCLL subroutine need to use the same field unaltered.
rc
The full word containing the return code. These are the possible return codes:
0
Normal completion.
4
Invalid request code.
8
OMEGAMON has not initialized in the CICS region. Verify that KOCOME00 is in the PLTPI or enter
the transaction OMEG INIT.
12
Incomplete parameter list provided.

334 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 A negative value in rc indicates that KOCOME00 is not available for task related user exit calls. For
example, it is not enabled or not started.
request
The full word containing the number of the requested operation. For the list of possible requests, see
Figure 28 on page 335.
parm
The area of storage used to move a value into or a field out of the transaction record. See Figure 28 on
page 335 for the required length, which depends on the request.
VL
The end of the list of parameters. For the KOCRMCLL subroutine, the return code is set in Register 15
for Assembler programs or in the appropriate variables for COBOL and PL1 programs. Figure 28 on
page 335 lists the possible types of requests.

REQUEST NUMBER DESCRIPTION PARAMETER FIELD LENGTH FIELD NAME

--------------------------------------------------------------------------------
2 READ FLAG FIELD 1 MN#FLAG4
3 WRITE FLAG FIELD 1 MN#FLAG4
4 READ UMBRELLA TRANSACTION PSEUDO 4 MN#UMBPTC
5 WRITE UMBRELLA TRANSACTION PSEUDO 4 MN#UMBPTC
6 READ UMBRELLA PROGRAM NAME 8 MN#UMBUSR
7 WRITE UMBRELLA PROGRAM NAME 8 MN#UMBUSR
8 READ WAITING RESOURCE NAME 8 MN#DEXFIL
9 WRITE WAITING RESOURCE NAME 8 MN#DEXFIL
10 READ WAITING RESOURCE TYPE 8 MN#DEXTYP
11 WRITE WAITING RESOURCE TYPE 8 MN#DEXTYP
12 READ USER DATA 32 MN#USRWK
13 WRITE USER DATA 32 MN#USRWK
14 TURN RLIM OFF FOR THIS TRANSACTION 0
15 TURN RLIM ON FOR THIS TRANSACTION 0
16 QUERY THE RLIM STATUS FOR THIS TRANSACTION 4 User Supplied
17 READ SOA DATA 96 MN#SOA
18 WRITE SOA DATA 96 MN#SOA

Note: Requests 14 and 15 do not require a user field. Request 16 requires that the user program provide
a 4 byte field. The results of the query are stored in the field, which you can then inspect. In the case,
where the KOCGLCLL subroutine is used to start requests 14 and 15 the user needs to provide a dummy
user field in the request.
Figure 28. List of Requests for the KOCRMCLL subroutine

Each field is described in the following list:

MN#FLAG4
This flag contains two indicators that you set if you want the values you supply for MN#UMBPTC,
MN#DEXFIL, and MN#DEXTYP to be carried over the end of a transaction conversation. Call the
KOCRMCLL sub routine to read the current field (REQUEST # = 2); set the bit corresponding to the
field you want carried across to 1; and call the KOCRMCLL sub routine to write the field (REQUEST #
=3). Refer to the dsects for the bit settings.
MN#UMBPTC
Set this field with an alternate transaction ID. The Task, Response Time, and History menu paths
display this ID name in place of the actual transaction ID. You can change the value several times
over the course of the task, but the response time collector and task history collector pick up only
the last setting. Changing the value does not cause an individual record to be written. Rather, it
allows you to highlight the phase of the task with the TASK menu option. One popular use of this
field is to supply a meaningful name to a CICS application that runs under a transaction ID used for
many programs. For example, many fourth-generation language packages use one transaction ID to
invoke many applications. By supplying a new transaction ID, you can get a clearer indication of the
application that was running as part of that transaction.
MN#UMBUSR
Set this field with an alternate program name. The Task Details panel (KC2C02D) and the Task History
Details panel (KC2T02D) displays the umbrella pushbutton. Selecting this button displays either panel

Appendix F. OMEGAMON for CICS optional features 335

 Task Umbrella Data (KC2C09D) or panel Task History Umbrella Data (KC2T06D). These panels display
MN#UMBUSR as the umbrella program ID.
MN#DEXFIL
This field is used in task display and internal bottleneck analysis and represents the resource name
that the task is waiting on. The resource name is normally supplied by CICS. Supplying a new resource
name can give you a clearer indication of the reason for the wait. For example, you might have a
transaction that issues requests to database products. While the transaction is waiting for a service to
complete, it normally appears to be waiting on an z/OS system ECB, which really gives no indication
of the type of wait. By calling the KOCRMCLL subroutine before the request, you can supply a name
that clearly identifies the type of wait, such as a database product name or function type. When the
transaction receives control back from the database product, you can call the KOCRMCLL subroutine
again to clear out this waiting resource name.
MN#DEXTYP
This field is used in task display and internal bottleneck analysis and represents the resource type
that the task is waiting on. The resource type is normally supplied by CICS. This field is used the same
way as MN#DEXFIL.
MN#USRWK
Use this field as a work area for user data.
MN#SOA
Use this field as a work area for SOA data.

Using umbrella services for Web service details

OMEGAMON for CICS on z/OS automatically records the Web service name and Operation name for Web
Service Provider transactions, with Version 4 or higher of CICS Transaction Server. If you are running an
older version of CICS or wish to override the values provided by CICS you can use umbrella services to set
these values.
The KOCRMCLL and KOCGLCLL subroutines are used to enable OMEGAMON for CICS on z/OS to
effectively monitor Web service transactions through the use of the Web Service Name and Operation
attributes. The details on how to use these subroutines are located in the KOCAPITX member of the
TKANSAM library.
To use umbrella services to inform OMEGAMON for CICS on z/OS of the Web service details, issue the
OC@API_SOA_WRITE request type that passes an area mapped by the KOCSOA macro provided in the
TKANMAC library.
The KOCSOA macro defines the Web Service Name as a 32 character field. This should contain the first 32
characters of the Web Service Name padded with blanks. The Operation name is a 64 character field and
should contain the first 64 characters of the Web Service Operation padded with blanks. See Figure 29 on
page 336 for an example how the KOCSOA macro defines these values.
You can use the following example to report these values to OMEGAMON for CICS on z/OS using the CICS
API in the KOCRMCLL subroutine to report SOA data. This example shows how to request the information
about the Web Services Name and Operation from CICS. This does require the DATAREG parameter on the
DFHEIENT macro is either set to register 13 or allowed to default to that value.
Figure 29. A request for information about Web Services Name and Operation from CICS

***------------------------------------------------------------***
*/* CICS STORAGE
***------------------------------------------------------------***
DFHEISTG DSECT
FUNCTION DS CL16
LENGTH DS F
REQUEST DS F
KOCCALL CALL ,(0,0),MF=L
KOCSOA ,
EJECT
***------------------------------------------------------------***
*/* PROGRAM START
***------------------------------------------------------------***
OMEGPROG DFHEIENT

336 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 ***------------------------------------------------------------***
*/* GET THE FIRST 32 BYTES OF WSNAME
***------------------------------------------------------------***
MVC MN#WSNAME,SPACES
MVC LENGTH,=A(L'MN#WSNAME)
EXEC CICS GET CONTAINER('DFHWS-WEBSERVICE') *
INTO(MN#WSNAME) FLENGTH(LENGTH) *
NOHANDLE
CLC EIBRESP,DFHRESP(NORMAL)
BE GETOPER
CLC EIBRESP,DFHRESP(LENGERR)
BNE EXIT
***------------------------------------------------------------***
*/* AND THE FIRST 64 OF THE OPERATION
***------------------------------------------------------------***
GETOPER DS 0H
MVC MN#OPERATION,SPACES
MVC LENGTH,=A(L'MN#OPERATION)
EXEC CICS GET CONTAINER('DFHWS-OPERATION') *
INTO(MN#OPERATION) FLENGTH(LENGTH) *
NOHANDLE
CLC EIBRESP,DFHRESP(NORMAL)
BE TELLOMEG
CLC EIBRESP,DFHRESP(LENGERR)
BNE EXIT
***------------------------------------------------------------***
*/* NOW REPORT TO OMEGAMON
***------------------------------------------------------------***
TELLOMEG DS 0H
MVC REQUEST,=A(OC@API_SOA_WRITE)
CALL KOCRMCLL,(REQUEST,MN#SOA),VL,MF=(E,KOCCALL)
EXIT DFHEIRET
***------------------------------------------------------------***
*/* STATIC DATA
***------------------------------------------------------------***
SPACES DC CL64' '

OMEGAMON for CICS on z/OS also provides the KOCSOAP sample pipeline handler program. Use this
program to report SOA data without having to change any application code. It does require that you
assemble and link the KOCSOAP member found in the TKANSAM library and change the pipeline handler
program.
The following pipeline definition file shows how to ensure the provided handler is started for the Web
Services provided by this pipeline configuration file:

<?xml version='1.0" encoding="EBCDIC-CP-US"?>

<provider_pipeline xmlns="htp://www.ibm.com/software/htp/cics/pipeline"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ibm.com/software/htp/cics/pipeline provider.xsd ">
<service>
<service_handler_list>
<handler>
<program_name>KOCSOAP</program_name>
<handler_parameter_list> </handler_parameter_list>
</handler>
</service_handler_list>
<terminal_handler>
</cics_soap_1.2_handler>
</terminal_handler>
</service>
<apphandler.DFHPITP</apphandler>
</provider_pipeline>

OMEGAMON for CICS (3270) address space

This information describes the OMEGAMON for CICS (3270), which is an address space that is separate
from the CICS address space. OMEGAMON for CICS (3270) can accept commands from either a member
of its parameter library or a z/OS operator’s console.
With these commands you can do any of the following:
• Start the OMEGAMON for CICS (3270) monitoring sessions with a different set of startup parameters for
each session. For example, each session can pass the address of a different, dedicated, local 3270 to
use as its output device.

Appendix F. OMEGAMON for CICS optional features 337

 • Start the OBVTAM OMEGAMON for CICS (3270) VTAM application. When this program is running under
the OMEGAMON for CICS (3270), any 3270 terminal in your VTAM network (depending on authorization)
can log on to the program and have its own OMEGAMON for CICS (3270) session.
• Display all subtasks currently running under the OMEGAMON for CICS (3270).
• Stop any subtask running under the OMEGAMON for CICS (3270).

OMEGAMON for CICS (3270) operation

You can enter commands to the OMEGAMON for CICS (3270) interface using the CICM command by
performing the following steps.
1. Select U, UTILITIES, from the Main menu.
2. Select M, INTERFACE, from the Utilities menu.
The following panel is displayed on your console:

________________ ZUOCCI VTM CICSPROD V530./I SYSA collector 12:15: 21

> PF1 Help PF3 Back PF4 Main Menu PF7 Up PF8 Down

==============================================================================

> ISSUE COLLECTOR COMMAND

> To issue an OCCI command, replace the > preceding CICM with a hyphen and
> replace DISPLAY with the required OCCI command.

>CICM DISPLAY

> To display console output:

> - Blanks after CONS indicate the main terminal. You may enter a z/OS
> console ID after CONS.
> - Replace 10 after LINE with the number of lines at the end to display.

-CONS Main Console 6A2 ( Id=2 )

line10
+ - 087D0001
+ - 10.42.50 STC08737 IST895I CCCDRM26 08420000 CCCD00
. . . . .
. . . . .
. . . . .

> If a password is required, enter /PWD on the beginning line. At the prompt, enter
> the password.
===============================================================================

Figure 30. Issue Collector Command Menu Panel

3. Follow the instructions on the panel to enter OMEGAMON for CICS (3270) commands.

OMEGAMON for CICS (3270) interface commands

You can enter commands to control the OMEGAMON for CICS (3270) interface with the CICM command.
The CICM command formats the z/OS Modify (F) command allowing you to issue one of the following
DISPLAY, EXEC, HELP, LIST, LOG, START and STOP interface commands.
You can store commands as members in the rhilev.RKANPARU library, then issue:

CICM EXEC mmmmmmmm

where mmmmmmmm is the member name.

To use the stored interface commands, use the following steps:
1. Create a member in the rhilev .RKANPARU library.
2. Use the EXEC command to process the member. You can either enter this command by using MODIFY
or as a command in an EXEC member.
Note: All commands from the console must be preceded by the MODIFY command and the modify ID.

338 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 You can start the commands in the EXEC members of the rhilev.RKANPARU library in any column
as long as you complete the command word before column 72. (You can continue the command by
placing any character in column 72.)
The following list defines the commands that the OMEGAMON for CICS (3270) supports:
*
Comment, ignored by the OMEGAMON for CICS (3270), must begin in column 1.
DISPLAY
Shows active OMEGAMON for CICS (3270) sub tasks.
EXEC
Runs the commands in the specified member.
HELP
Shows help for all or specific OMEGAMON for CICS (3270) commands.
LIST
Alias of DISPLAY; shows active OMEGAMON for CICS (3270) sub tasks.
LOG
Sends a message to the z/OS console.
START
Starts a OMEGAMON for CICS (3270) subtask.
STOP
Stops a OMEGAMON for CICS (3270) subtask.

OMEGAMON for CICS (3270) comment

In members of the rhilev.RKANPARU library, use an asterisk (*) in column 1 of any line to comment out the
text to follow.
Use a non blank character in column 72 to continue the comment.

DISPLAY command
The DISPLAY command lists all tasks that are currently active. An internal ID is displayed along with the
program name of the task.
An example of an output from the DISPLAY command appears in the following figure.

F cccccccc,DISPLAY
CI0543: THE FOLLOWING TASK IDS ARE ACTIVE:
CI0594: ID=KOCBGR.subtask PROGRAM=KOCBGR
CI0594: ID=KOCRTA.subtask PROGRAM=KOCRTA
CI0594: ID=KOCDEX.subtask PROGRAM=KOCDEX
CI0594: ID=OCU772 PROGRAM=KOCCICS
CI0594: ID=OBVTAM PROGRAM=KOBVTAM
CI0594: ID=XMIT PROGRAM=KOCOCPR

Figure 31. DISPLAY Command Output

Each task has a unique ID. The ID of a subtask associated with a specific CICS region consists of the
program name combined with the CICS job name. That is, subtask in Figure 31 on page 339 is replaced
with the monitored job name. OMEGAMON for CICS (3270) sessions under OBVTAM do not have separate
IDs, and are controlled by the OBVTAM ID. In dedicated mode, OMEGAMON for CICS has the task ID of
OCUcuu, where cuu is the dedicated terminal address.

EXEC command
The EXEC command is used to run the commands in a specific rhilev.RKANPARU member.

F cccccccc,EXEC [mmmmmmmm]

Appendix F. OMEGAMON for CICS optional features 339

 Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) and
mmmmmmmm is the member name.
The EXEC member contains commands such as START, STOP, and even another EXEC command. When
an EXEC command is processed inside another EXEC member, it is as if all of the commands of the other
EXEC member were placed into the calling EXEC member in the same position as the calling command.
For example, consider the following command:

F cccccccc,EXEC MEMBERA

Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) during your
product configuration.
If MEMBERA contains the following commands:

START KOCCICS,CICS=CICSPROD,UNIT=560,LROWS=255
EXEC MEMBERB

And, if MEMBERB contains the following commands:

LOG * OM/CICS VTAM common interface START - APPL=KOCVTMnn *

START OBVTAM,OM=KOCCICS,CICS=CICSPROD,APPL=KOCVTMnn,UMAX=05

Then the effect of entering F cccccccc,EXEC MEMBERA is the same as if you entered the following
commands:

F cccccccc,START KOCCICS,CICS=CICSPROD,UNIT=560,LROWS=255
F cccccccc,LOG * OM/CICS VTAM common interface START - APPL=KOCVTMnn *
F cccccccc,START OBVTAM,OM=KOCCICS,CICS=CICSPROD,APPL=KOCVTMnn,MAX=05

Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) during your
product configuration. It is also the same effect if you use a single member that contains all of the
commands:

START KOCCICS,CICS=CICSPROD,UNIT=560,LROWS=255
LOG * OM/CICS VTAM common interface START - APPL=KOCVTMnn *
START OBVTAM,OM=KOCCICS,CICS=CICSPROD,APPL=KOCVTMnn,UMAX=05

The maximum number of EXEC commands that can be processed at one time is 10. This helps prevent
EXEC loops, where A EXECs B and B EXECs A.

HELP command
The HELP command displays help for the OMEGAMON for CICS (3270) commands.
You can use the HELP command without an operand to find out the names of all the commands that are
supported by the OMEGAMON for CICS (3270). Issue the command using this format:

F cccccccc,HELP

Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) using the
PARMGEN configuration method.
Figure 32 on page 341 shows the HELP command output.

340 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 LOG 'HELP' Command
Syntax: HELP command-name

Description: The 'HELP' command is used to display the

help information available on the commands that are used to
control the OMEGAMON interface.

HELP is available for all the commands below:

* - Comment (ignored by the Interface)

EXEC - Execute the commands in the member specified
DISPLAY - Display active Interface subtasks
LIST - Alias of DISPLAY - Display active Interface
subtasks
LOG - Send a message to the MVS Console
START - Start an Interface Subtask
STOP - Stop an Interface Subtask

Figure 32. HELP Command Output

You can use the HELP command to display information about any other command that the OMEGAMON
for CICS (3270) interface processes by following HELP with the name of a specific command. If the
command name is not specified, is unrecognized, or is the HELP command used by itself, OMEGAMON for
CICS displays the help text shown in Figure 32 on page 341.
Use the following format to request HELP for a specific command. For example, to request HELP for the
START command, issue the following statement:

F ccccccccc,HELP START

Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) during your
product configuration.

LIST command
LIST is an alternate name for the DISPLAY command. The LIST command shows all tasks that are
currently active.
The output from the LIST command is the same as that shown in DISPLAY Command Output. For a
complete description of this command, see “DISPLAY command” on page 208.

LOG command
The LOG command is used to send a message to the z/OS console.
The output from the LOG command looks exactly like its input. You can use LOG in an EXEC member to
indicate the name of a command as it is being processed. For example, if you use the LOG command
to enter the following message, that message is displayed at your system console when OMEGAMON is
processing the specified member.

F cccccccc,LOG *** Processing membername ***

Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) during your
product configuration.

START command
Use the START command to start a subtask under the OMEGAMON for CICS (3270).
These are the tasks that you can start:
• Dedicated sessions
• OBVTAM
• RTA
• ONDV

Appendix F. OMEGAMON for CICS optional features 341

 • DEX
• XMIT
Most of the parameters that are specified have defaults taken from the OMEGAMON for CICS (3270) or
from the task being started. You can change some of these defaults by modifying the OMEGAMON user
data module.
If you stop OBVTAM, any OMEGAMON sessions running under it also stop, and you must restart them
manually.
This is the command to start the task history subtask from the z/OS console:

F cccccccc,START KOCBGR,CICS=cccccccc

Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) during your
product configuration.
A subtask can also be started by placing the START command in a member of the rhilev.RKANPARU library
and starting it using the EXEC command.
For examples of the START command for the internal bottleneck collector and response time collector,
see rhilev.RKANSAM(KOCIDEX) and rhilev.RKANSAM(KOCIRTA).
Use the following command to start a dedicated session: (See Table 100 on page 343 for a description of
the parameters.)

F cccccccc,START KOCCICS [,CICS=cccccccc]

[,COLS=nnn]
[,FSCR=cccccccc]
[,LROWS=nnn]
[,MODE=CN1]
[,ROWS=nn]
[,SYS=cccc]
[,UNIT=cuu]
[,USER=cc]

Where ccccccccc is the started task name you specified for the OMEGAMON for CICS (3270) during your
product configuration.
Note: Changes to the FSCR parameter can disable the OMEGAMON for CICS (3270).
An example is provided in rhilev.RKANSAM(KOCIDED).
Use the following command to start OBVTAM:

F cccccccc,START OBVTAM [,APPL=cccccccc]

[,AUP=YES/NO]
[,DATA=cc...cc]
[,LROWS=nnn]
[,MODE=IC1]
[,OM=KOCCICS]
[,PRTCT=cccccccc]
[,PSWD=cccccccc]
[,SYS=cccc]
[,UMAX=nn]
[,USER=cc]

Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) during your
product configuration.
An example is provided in rhilev.RKANPAR(KOCVTMnn).
The application ID specified with APPL=cccccccc must be defined to VTAM. To run multiple copies of
OBVTAM, use a unique APPLID for each copy.
The parameters specified with the START OBVTAM command become the defaults for any OMEGAMON
for CICS (3270) sessions created by OBVTAM in response to LOGON requests.

342 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

To change the default value or any other command at LOGON time, use the DATA keyword of the LOGON
command to override it. The CICS parameter (the job name of the target CICS) can be specified through
the DATA keyword at LOGON time, as in the following example.

LOGON APPLID(KOCVTMnn) DATA('CICS=CICSPROD,USER=01')

You can specify the items enclosed in brackets ([ ]), but many have defaults that need not be specified.
Table 100 on page 343 shows the START options for OMEGAMON for CICS (3270) and OBVTAM.

Table 100. START options for OMEGAMON for CICS (3270) and OBVTAM
Parameter Value Description Default
APPL cccccccc Up to eight character VTAM application name KOCVTMnn
to be used by OBVTAM. Name must match
the ACBNAME specified in rhilev.RKANPAR
member KOCVTMnn. Must also be specified
in SYS1.VTAMLST.
AUP YES or NO Specifies whether or not the OBVTAM NO
sessions are to be in automatic update
mode.
CICS cccccccc The name of the CICS to be monitored.
COLS 80, 132, or The number of columns on the screen; use Derived from VTAM or
160 for dedicated mode. CICS terminal definition
DATA YES or NO Specifies whether a log on data string is YES
used. DATA=NO allows logon with VTAM
interpret table names.
DC Y or N Specifies whether the OMEGAMON for CICS Y
(3270) compresses the 3270 data stream
before it is sent to the terminal.
FOLD Y or N Indicates whether the password should be Y
folded to uppercase or not.
FSCR cccccccc Specifies the first screen space to be
displayed. The default is ZMENUI.
If the command that you want to
run is a security protected command,
then the AUTHLIB= statement in
RKANPARU(KOMSUPDI) needs to be
commented out and pointed to the
authorized screen space library. This
option allows you to run protected
commands as part of the initialization
screen without entering a password. Verify
that the authorized screen space library
is concatenated into your hi.lev.PROC
DD statement. The authorized screen
space library is not an APF-authorized
data set, rather it is an AUTHLIB data
set. IMPORTANT: Changes to the FSCR
parameter can disable the OMEGAMON for
CICS (3270) user interface.

Appendix F. OMEGAMON for CICS optional features 343

 Table 100. START options for OMEGAMON for CICS (3270) and OBVTAM (continued)
Parameter Value Description Default
LROWS 99–9999 The number of logical rows. The LROWS 99
parameter is always larger than or equal to
the ROWS parameter.
MODE CN1 Indicates dedicated mode. Dedicated
IC1 Indicates OBVTAM mode.

OM KOCCICS The OMEGAMON module. KOCCICS

PASSPHRASE passphrase Specifies the passphrase support setting. NO
Valid values are PARTIAL, MAX62, FULL, NO/
NONE.
PRTCT cccccccc The password of the VTAM application ID to User-specified
be used by the OMEGAMON VTAM collector.
(Required with VTAM mode if applid has a
password.)
PSWD cccccccc The password required to be entered by the User-specified
terminal user to be able to log on to the
OMEGAMON VTAM collector. If PSWD is not
specified, anyone can log on to it.
ROWS nn The number of rows on the screen; use for Derived from VTAM or
dedicated mode. CICS terminal definition
SAFAPPL secclass Specifies the name of the optional SAF CANDLE
application ID for OMEGAMON 3270 Classic
interface security.
SECCLASS secclass Specifies the name of the SAF security OMCANDLE
class for OMEGAMON 3270 Classic interface
security.
SYS cccc The four character system ID to be displayed sysid
on the INFO-line.
TIMEOUT nn Specifies the number of minutes until 0
OMEGAMON stops the idle VTAM mode
sessions. The value can be any number from
0 through 99. Specify 0 if you do not want
VTAM mode sessions to time out.
UMAX 01–99 The number of sessions the OMEGAMON 5
VTAM collector can have. The more sessions
that are specified, the more storage
required.
UNIT cuu The unit address of the OMEGAMON terminal User-specified
(used for dedicated mode).
USER cc The user profile identifier. /C

344 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 STOP command
Use the STOP command to stop an OMEGAMON for CICS (3270) subtask.
To stop an OMEGAMON for CICS (3270) subtask such as OBVTAM, you must specify a task ID with the
STOP command. Find this ID by using the DISPLAY command (described in “DISPLAY command” on page
208), or the LIST command (described in “LIST command” on page 210).
This is an example of the STOP command to stop OBVTAM:

F ccccccccc.STOP OBVTAM

Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) during your
product configuration.
If you stop OBVTAM, any OMEGAMON for CICS (3270) sessions running under it also stop.
To stop a subtask, for example, KOCBGR, that is associated with a specific CICS region, issue the
following command:

F cccccccc,STOP KOCBGR.CICS_jobname

Where cccccccc is the started task name you specified for the OMEGAMON for CICS (3270) during your
product configuration.
Note: You can also stop tasks such as ONDV from the Control Options path, or by entering a fast path; see
Starting and stopping the historical collector. Additionally, in the Classic interface, you can enter a STOP
command from any line, for example:

ONDV STOP

In the e3270UI, you can stop the historical collector from the Task History Status panel, by overtyping the
current Task History Status with Inactive.

Installing multiple OMEGAMON address space pairs

OMEGAMON consists of a pair of address spaces; there is one OMEGAMON for CICS (3270) address
space.
One OMEGAMON for CICS (3270) address space can support approximately 40 to 80 sessions; this
number varies, depending on the region size and other environmental factors. If you experience virtual
storage constraints in OMEGAMON due to the number of concurrent sessions, you can generate multiple
address pairs for a z/OS operating system. If you are a new OMEGAMON user, begin by generating only
one pair of addresses.
OMEGAMON for CICS (3270) associates each CICS address space with a particular OMEGAMON for CICS
(3270) session when you add the following DD statement to both the JCL for the collector and the JCL for
CICS:

//RKC2XMnn DD DUMMY

Where nn is a two digit number from 00 through 15. The default setting is 00.
OMEGAMON for CICS associates any CICS without an RKC2XMnn DD statement with the collector that
either has no RKC2XMnn DD statement or has the RKC2XM00 DD statement.
Note: The RKC2XMnn DD statement is required only when running two or more collector address spaces
of the same version number.
When installing a new version of OMEGAMON for CICS with the existing version, choose which regions are
to be monitored by the new version. These regions need to have the new RKANMOD data set in their JCL.
References to the old RKANMOD data set need to be removed. Also confirm there are no duplicate started
task names or VTAM APPLIDs that conflict with the old version.

Appendix F. OMEGAMON for CICS optional features 345

Virtual terminal pool considerations
This information describes virtual terminal pool considerations for the OMEGAMON for CICS (3270)
interface.
For the OMEGAMON for CICS (3270) interface, this section describes how to perform the following tasks:
• Modify your virtual terminal pool definitions
• Support OMEGAMON sessions under more than one TSO

Modifying the default virtual terminal pool definition

If you use TSO or ISPF mode and your runtime environment is not sharing libraries with other runtime
environments or with SMP/E, this is the procedure to modify virtual terminal pool definitions.
Note: The procedure in this section applies only to the OMEGAMON for CICS (3270).
Do the following.
1. Review the comments in the following members of the &rtehilev.RKANSAMU library to ensure you
understand the contents and purpose of each member. These are the library members:
• KOBVTPL
• KOBVTPLX
• KOBVT1AP
2. Define your virtual terminals and LOGMODE names to the VTM1 program by updating the KOBVTPL
member in the &rtehilev.RKANSAMU library.
3. Assemble and link edit the KOBVTPL source to create the KOBVTPL load module using the JCL in the
KOBVTPLX member of the &rtehilev.RKANSAMU library. The resulting KOBVTPL load module is stored
in the &rtehilev.KANMODU library.
Note: The &rtehilev.RKANSAMU(KOBVTPLX) job is file tailored and created through PARMGEN.
4. If you modified the terminal definitions (the number of terminals or their names) do the following
tasks:
a. Update the KOBVT1AP VTAM node list member, in the &rtehilev.RKANSAMU library
b. Update your VTAMLST controls accordingly.

Determining when to change virtual terminal pool definitions

The default definition might need to be changed because of any of the following conditions:
• The size of the virtual terminal pool does not meet your needs.
• The names of the virtual terminals do not meet your site’s naming conventions.
• The VTAM LOGMODE name defaults are not appropriate.
Before you make any changes to the number of virtual terminals in the pool, consider the needs of all
OMEGAMON for CICS (3270) users running the same copy of the KOBVTPL load module. Because virtual
terminal pool definitions can be shared by multiple VTAM hosts, consider the maximum expected number
of concurrent TSO and ISPF sessions as you determine the size of the virtual terminal pool.

Sharing virtual terminal pool definitions

To provide support for OMEGAMON for CICS (3270) sessions under more than one TSO (or ISPF), you
must install VTM1 in every VTAM domain that controls a TSO address space.
VTM1 uses a virtual terminal for each OMEGAMON session; KOBVTPL defines this virtual terminal pool.
Normally, each installation of VTM1 includes a virtual terminal pool definition.
The samples in this section assume the following:
• There are two VTAM domains in the network:

346 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 – Host Subarea A (HSAA) which runs OMEGAMON and TSO (TSOA)
– Host Subarea B (HSAA) which runs OMEGAMON and TSO (TSOA)
• OMEGAMON users who use ISPF or TSO mode must use the local TSO. This means that users whose
terminals are controlled by VTAM domain HSAA must log on to TSOA and users whose terminal are
controlled by VTAM domain HSAB must log on to TSOB.

Defining the virtual terminal pool to VTM1

The following information describes how multiple VTM1 installations can share a single virtual terminal
pool definition.
In the sample network, if you described that a pool of 10 virtual terminals is required for each host
subarea, the following $VTAPPL statement defines this virtual terminal pool to VTM1.

$VTAPPL APPL#=10,VTAPPL=OBVTM1

Specifying network names

The VTAM APPL definition statement permits you to specify a network name and an ACB name.
The network name can differ from the ACB name, which can be useful in situations in which you must
support multiple VTAM hosts.

Specifying ACB names

KOBVTPL defines the ACB names to VTM1, so the VTAM definitions in the KOBVT1AP member must
reflect these names.
The $VTAPPL definition statement determines the ACB names of the virtual terminals, as follows:
• The first portion of each name (up to six characters) is taken from the value of the VTAPPL keyword.
• The two-character suffix is based on the value of the APPL# keyword, which can range from 01–99,
inclusive.
Example:
If a $VTAPPL statement is coded with VTAPPL=OBVTM1 and APPL#=25, a combination of the two
keyword values results in 25 ACB names, OBVTM101 through OBVTM125.

Defining the virtual terminal pool to each domain

After defining virtual terminal pools to VTM1, you must define the virtual terminals to each VTAM domain.
To do so, you can define the local name and the network name separately.
The local name is defined by the ACBNAME keyword in the VTAM APPL definition statement.
The network name is defined by the name field in the VTAM APPL definition statement. In the sample
VTAM APPL definitions that follow, the HSAA network names differ from those of HSAB, but the local
names for each virtual terminal are the same in both host subareas.
Figure 33 on page 347 shows the definition statements for Host Subarea A that correspond to the
$VTAPPL definition statement.

HSAAVTM1 VBUILD TYPE=APPL

HSAAVT01 APPL ACBNAME=OBVTM101,EAS=1
HSAAVT02 APPL ACBNAME=OBVTM102,EAS=1
HSAAVT03 APPL ACBNAME=OBVTM103,EAS=1
HSAAVT04 APPL ACBNAME=OBVTM104,EAS=1
HSAAVT05 APPL ACBNAME=OBVTM105,EAS=1
HSAAVT06 APPL ACBNAME=OBVTM106,EAS=1
HSAAVT07 APPL ACBNAME=OBVTM107,EAS=1
HSAAVT08 APPL ACBNAME=OBVTM108,EAS=1
HSAAVT09 APPL ACBNAME=OBVTM109,EAS=1
HSAAVT10 APPL ACBNAME=OBVTM110,EAS=1

Figure 33. HSAA VTAM Definition Statements

Appendix F. OMEGAMON for CICS optional features 347

 Figure 34 on page 348 shows the definition statements for Host Subarea B that correspond to the
$VTAPPL definition statement.

HSABVTM1 VBUILD TYPE=APPL

HSABVT01 APPL ACBNAME=OBVTM101,EAS=1
HSABVT02 APPL ACBNAME=OBVTM102,EAS=1
HSABVT03 APPL ACBNAME=OBVTM103,EAS=1
HSABVT04 APPL ACBNAME=OBVTM104,EAS=1
HSABVT05 APPL ACBNAME=OBVTM105,EAS=1
HSABVT06 APPL ACBNAME=OBVTM106,EAS=1
HSABVT07 APPL ACBNAME=OBVTM107,EAS=1
HSABVT08 APPL ACBNAME=OBVTM108,EAS=1
HSABVT09 APPL ACBNAME=OBVTM109,EAS=1
HSABVT10 APPL ACBNAME=OBVTM110,EAS=1

Figure 34. HSAB VTAM Definition Statements

Virtual terminal pool access summary

VTM1 selects virtual terminals from KOBVTPL at run time when OMEGAMON for CICS (3270) session in
TSO or ISPF modes is started. Any changes you make to the default KOBVTPL must be assembled and
link-edited.
Install VTM1 execution time modules (including KOBVTPL) in both host subareas. The most convenient
method is to place these modules in a load library shared by both systems; this allows TSOA and TSOB
users access to OMEGAMON for CICS (3270).

Interfacing with other products for transaction tracking support

OMEGAMON for CICS on z/OS enables you to monitor all the components that a CICS application consists
of. OMEGAMON for CICS on z/OS interfaces with IBM Tivoli Composite Application Manager (ITCAM) for
CICS, V7 and higher and ITCAM for Transactions V7 and higher to correlate these transactions.
ITCAM for CICS is used to track Dynamic Program Link (DPL) requests to or from a CICS program;
it can track requests through CICS Transaction Gateway. ITCAM for CICS provides a correlation for
Service-oriented architecture (SOA) and WebSphere MQ traffic into CICS. ITCAM for CICS also provides
the capability to track CICS transaction routing and function shipping requests.
ITCAM for Transactions helps you determine all the components of a complex transaction.

Starting ITCAM for CICS in a CICS region

OMEGAMON for CICS on z/OS can automatically start ITCAM for CICS in a CICS region.
This is controlled by the TRANSACTION_TRACKING=AUTO value in the <STARTUP_CONTROL> section of
the Global Data Area for OMEGAMON for CICS:

*
<STARTUP_CONTROL>
*
TRANSACTION_TRACKING=AUTO| NOAUTO

The default setting is NOAUTO.

When you specify the TRANSACTION_TRACKING=AUTO value, OMEGAMON for CICS on z/OS attempts to
link to the ITCAM for CICS component and initialize it in the CICS region. You only specify one program in
the CICS PLT (program list table). If the ITCAM for CICS component is installed in the same SMP/E CSI as
OMEGAMON for CICS on z/OS, then no JCL changes are required to CICS to enable ITCAM for CICS. The
JCL that is required for OMEGAMON for CICS on z/OS is sufficient.

348 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Using OMEGAMON for CICS to start or stop ITCAM for CICS in a specific
region
OMEGAMON for CICS on z/OS provides the capability to dynamically start or stop ITCAM for CICS in a
specific region.
This is achieved through the OMEGAMON for CICS (3270) interface. Use the O.X menu option to view the
status of ITCAM in a specific CICS region.

________________ ZCTRK VTM CICSR37L V530./C SYS 11/05/12 14:35:02

> PF1 Help PF3 Back

> A-RTA On B-RTA Off C-RTA Status D-RTA Intervals E-RTA Scaling
> F-ONDV On G-ONDV Off H-ONDV Status I-Bottleneck Ctl J-Wait Reasons
> K-INTR Ctl L-IANL On M-IANL Off N-IANL Settings O-IANL Groups
> P-Collection Q-Shutdown R-RLIM On S-RLIM Off T-RLIM Status
> U-SMF Status V-ATF Filters W-ATF Status X-ITCAM Status
================================================================================
> Transaction Tracking (ITCAM) status

> The current status of ITCAM in the CICS region, The current Global setting
> for transaction tracking and an indication as to whether ITCAM will be
> stopped when OMEGAMON is stopped in the CICS region.

> Changing the command to TRKU allows authorized users to modify status of
> ITCAM in the CICS region and the global setting for transaction tracking.

TRKS
+ Transaction Tracking Control Information
+ TRKSTATE ITCAM for CICS status . : Active
+ TRKGLOB ITCAM started in Global : Yes
+ TRKOMEG Stopped on OMEG SHUT. . : Yes

Figure 35. The OMEGAMON for CICS (3270) interface provides the capability to dynamically enable or
disable ITCAM for CICS in a specific region.

You can use the following commands for the OMEGAMON for CICS (3270) interface:
TRKS
Displays the status of the transaction tracking. The default security level is internal, level=0.
TRKU
Modifies the status from the value that is used in the global data area. The default security level is
internal, level=03.

Appendix F. OMEGAMON for CICS optional features 349

350 IBM Z OMEGAMON for CICS: Planning and Configuration Guide
Appendix G. Default DD Names
This section contains the standard DD names for data sets.

Standard DD names for the OMEGAMON for CICS (3270) address

space
The following definitions apply to the DD names found in the OMEGAMON for CICS files for the
OMEGAMON for CICS (3270) address space.
These are standard throughout all Tivoli-supplied JCL, PROCs, and CLISTs.
RKOCPROC
The data sets where OMEGAMON for CICS (3270) screen spaces are read. A data set in the
RKOCPROC concatenation is treated as read-only.
RKOCPCSV
The data set where a site’s OMEGAMON for CICS (3270) screen spaces are written. RKOCPCSV cannot
be concatenated.
RKOCPROF
The data sets where user profiles are read. A data set in the RKOCPROF concatenation is treated as
read-only.
RKOCPFSV
The data set where a site’s user profiles are written. RKOCPFSV cannot be concatenated.
RKANHENU
The data sets that contain the OMEGAMON for CICS (3270) command help panels.
RKANPAR
The data set that contains the commands to start the collector subtask.
RKLVSNAP
The data set that formatted dumps or summary dumps are directed to in the event of an abend. The
default configuration assigns this to SYSOUT. The value of the SDUMP() parameter determines if these
dumps are used: The SDUMP(N) parameter directs a formatted dump to this dataset; the SDUMP(S)
parameter directs a summary dump; the default value is the SDUMP(Y) parameter, which directs the
dump to a system dump data set (SYS1.DUMPxx).
These are specific to OMEGAMON for CICS on z/OS:
RKC2GLBL
The data set that contains the Global Data Areas, which control the monitoring options for CICS
regions.
RKC2XMnn
This DD DUMMY name is only required if you have more than one OMEGAMON for CICS (3270)
address space; the nn value identifies the OMEGAMON for CICS (3270) . The nn value can be 00 to 15
and defaults to 00 so the RKC2XM00 DD statement is not required.

© Copyright IBM Corp. 2004, 2022 351

352 IBM Z OMEGAMON for CICS: Planning and Configuration Guide
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:

Intellectual Property Licensing

Legal and Intellectual Property Law
IBM Japan, Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan

The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of
express or implied warranties in certain transactions, therefore, this statement might not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes 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.
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.

© Copyright IBM Corp. 2004, 2022 353

 The licensed program described in this document and all licensed material available for it are provided by
IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any
equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the
results obtained in other operating environments may vary significantly. Some measurements may have
been made on development-level systems and there is no guarantee that these measurements will be
the same on generally available systems. Furthermore, some measurement may have been estimated
through extrapolation. Actual results may vary. Users of this document should verify the applicable data
for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their
published announcements or other publicly available sources. IBM has not tested those products and
cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of
those products.
All statements regarding IBM's future direction or intent are subject to change or withdrawal without
notice, and represent goals and objectives only.
This information is for planning purposes only. The information herein is subject to change before the
products described become available.
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 platforms. 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 platform
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. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be
liable for any damages arising out of your use of the sample programs.
Each copy or any portion of these sample programs or any derivative work, must include a copyright
notice as follows:
© (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. ©
Copyright IBM Corp. 2022. All rights reserved.
If you are viewing this information in softcopy form, the photographs and color illustrations might not
display.

Privacy policy considerations

IBM Software products, including software as a service solutions, (“Software Offerings”) may use cookies
or other technologies to collect product usage information, to help improve the end user experience,
to tailor interactions with the end user or for other purposes. In many cases no personally identifiable
information is collected by the Software Offerings. Some of our Software Offerings can help enable you
to collect personally identifiable information. If this Software Offering uses cookies to collect personally
identifiable information, specific information about this offering’s use of cookies is set forth below.
Depending upon the configurations deployed, this Software Offering may use session cookies that
collect each user’s user name for purposes of session management, authentication, and single sign-on
configuration. These cookies cannot be disabled.
If the configurations deployed for this Software Offering provide you as customer the ability to collect
personally identifiable information from end users via cookies and other technologies, you should seek

354 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

 your own legal advice about any laws applicable to such data collection, including any requirements for
notice and consent.
For more information about the use of various technologies, including cookies, for these purposes,
See IBM’s Privacy Policy at http://www.ibm.com/privacy and IBM’s Online Privacy Statement at http://
www.ibm.com/privacy/details the section entitled “Cookies, Web Beacons and Other Technologies”
and the “IBM Software Products and Software-as-a-Service Privacy Statement” at http://www.ibm.com/
software/info/product-privacy.

Trademarks
IBM, the IBM logo, and ibm.com® are trademarks or registered trademarks of International Business
Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be
trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at
"Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml.
Intel, Intel logo, and Intel Xeon, are trademarks or registered trademarks of Intel Corporation or its
subsidiaries in the United States and other countries.
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or
both.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or
its affiliates.

Notices 355
356 IBM Z OMEGAMON for CICS: Planning and Configuration Guide
Index

Special Characters CICSplex Rules and Agent Preferences panel 55, 56, 59–62,
75
$VTAPPL 215, 216, 347 CICSPlex System Manager 61
CNMLINK data set 98, 224
command 84–87
A command line interface 82
ACB name 216, 347 commands 83
ACB names 216, 347 comment DISPLAY 208, 339
ACBNAME keyword 216, 347 comment EXEC 208, 339
accessing 55, 67, 75 comment HELP 209, 340
action tags 91 comment LOG 210, 341
ADABAS 196, 197, 327, 328 comment START 210, 341
adding 43, 57, 61, 68, 71, 73 comment STOP 213, 345
adding or editing 69 CONCURRENCY(THREADSAFE) 40
additional considerations 164, 294 configuration
agent preferences configuration 54 components to configure
agent preferences derived from CPSM 61 OMEGAMON XE for CICS 15
APPL definition statement 216, 347 OMEGAMON XE for CICS TG 16
application support 43 planning 11
application trace configuration for OMEGAMON for CICS
enhanced 3270UI 64 verifying 50
asterisk (* 208, 339 configuration instructions 25
attributes 56, 60 configuration overview 25
audit 120, 246 configuration prerequisites 26
authorization 82 Configuration Tool 25
configuring
KC5 26, 30
B KGW 31
OMEGAMON for CICS on z/OS 26,
basic system configuration 19
30
building 186, 317
OMEGAMON for CICS TG on z/OS 31
PARMGEN 26, 31
C configuring historical data collection 28
configuring security 28
CA-ACF2 external security 99, 224 continuation character 207, 338
CA-DATACOM 196, 197, 327, 328 control statements
CA-IDEAL 196, 197, 327, 328 AUTHLIB 108, 234
CA-TOP SECRET external security 99, 224 COMMAND 108, 234
catalog and attribute files 43 LIST 108, 234
CICM 207, 338 MINOR 108, 234
CICS monitoring facility (CMF) MODULE 108, 234
records 196, 327 PASSWORD 108, 234
CICS regions 36 RESET 108, 234
CICS SLA view 66–70, 72, 73 SMFNUM 108, 234
CICS tables 36 UPDATE 108, 234
CICS TG CPSM as a source for agent preferences for a CICSplex 61
definition 9 cross-memory considerations 19
CICS TG daemons 47 customization 117, 243
CICSplex classification rule 57, 59, 61 customizing 118, 244
CICSplex classification rule definitions 63
CICSplex classification rule definitions and agent
preferences 54 D
CICSplex classification rules 17
DAILY 168, 169, 299, 300
CICSplex classification rules requirements 56, 60
daily collection jobs 168, 169, 299, 300
CICSplex control settings 72
DD DUMMY 214, 345
CICSplex rules 95, 221
DD names 218, 351
defined to VTAM

Index 357
defined to VTAM (continued) historical data tables
definition statements 216, 347 disk space requirements 121, 249
VTAM 216, 347 historical reporting 166, 297
defining resources 95, 221 historical reporting considerations 19
defining the virtual terminal pool to each domain 216, 347 hub monitoring server on z/OS operating system 43, 54
definition statements 216, 347
delete 59, 62
designating OMEGAMON for CICS tables for near-term
I
history collection 123, 251 IBM Z OMEGAMON for CICS 11, 51, 54, 66, 82, 95, 221
designating OMEGAMON for CICS TG tables for near-term IBM Z OMEGAMON for CICS component
history collection 125, 253 manages 8
DETAIL 168, 169, 299, 300 monitors 8
detailed procedures overview 8
Global Data Areas 127, 257 tasks 8
determining when to change virtual pool definitions 215, 346 IBM Z OMEGAMON for CICS Take Action commands 95, 221
dictionary records 196, 327 IBMC20 26
disk space requirements IBMC5 26
historical data tables 121, 249 IBMCN 26
dispatching priority 19 IBMDS 26
DISPLAY command 208, 339 IBMETE 26
Dynamic Profile Update Facility 19 IBMOC0 26
IBMTOM 26
E IDMS 196, 199, 327, 330
initialization verification 50
editing 57 installing 54, 168, 298
editing classification rules 70 installing support
enabling 54 ADABAS 197, 328
End-to-End response time collector CA-DATACOM 197, 328
z/OS 3 IDMS 199, 330
enhanced 3270 user interface installing third-party support 196, 327
Near-Term History 123, 125, 251, interval records 194, 325
253 Issue Collector Command menu panel 207, 338
enhanced 3270UI IVP messages 53
application trace 64
service level analysis 74
error messages 117, 243
J
estimating optimal value for KC5_PD_CYL 123, 251 JCL
estimating optimal value for KGW_PD_CYL 125, 253 modify 36
ETE response time, verifying 50
EXEC command 208, 339
exporting 93 K
external security 99, 117, 224, 243
KC5_PD_CYL 123, 251
kcp_batch utility 82, 83
F kcp_slabatch export 85
kcp_slabatch help 87
file and database usage records 195, 326 kcp_slabatch import 84
finding the OMEGAMON TxnMonitor exit (kgw_monitor.jar) kcp_slabatch utility 82, 94
after product install 45 kcp_slabatch validateserviceclass 86
kgw_monitor.jar 45
G KGW_PD_CYL 125, 253
KOBVT1AP member 216, 347
Gateway daemon 44 KOBVTPL 215, 216, 346, 347
GENER/OL 196, 327 KOCAUE1 192, 323
GENER/OL support 198, 329 KOCGLCLL
Generalized Report Writer 182, 313 subroutine call syntax 203, 334
generic names 95, 221 KOCOME00 program 40
Global Data Area 127, 164, 190, 257, 294, 321 KOCPUE1 192, 322
KOCRMCLL
subroutine call syntax 203, 334
H KOCSOAP 205, 336
HELP command 209, 340 KOCSUE1 192, 323
historical data collection 121, 122, 249, 250 KOCSUPDI 28
historical data store 43 KOCUE1 192, 323

358 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

KOCUE1DR 191, 322 OMEGAMON enhanced 3270 user interface component (continued)
tasks 7
OMEGAMON for CICS
L interfaces 8
language support 54 sample code 191, 322
LIST 210, 341 OMEGAMON for CICS (3270 127, 257
LIST OMEGAMON for CICS (3270) command OMEGAMON for CICS (3270)
see also DISPLAY OMEGAMON for CICS (3270) configuring security 28
command 210, 341 OMEGAMON for CICS (3270) address space 206, 337
location of file or database sample record layouts 195, 326 OMEGAMON for CICS (3270) commands 99, 224
LOG command 210, 341 OMEGAMON for CICS (3270) comment 208, 339
LOG OMEGAMON for CICS (3270) command 210, 341 OMEGAMON for CICS (3270) interface 19
log on to 99, 224 OMEGAMON for CICS (3270) interface commands 207, 338
logon security 28 OMEGAMON for CICS (3270) operation 207, 338
OMEGAMON for CICS (3270) values 128, 258
OMEGAMON for CICS component
M manages 8
monitors 8
maintenance 43
overview 8
migrate 19
OMEGAMON for CICS TG on z/OS 52
migrating 128, 258
OMEGAMON for CICS TG on z/OS
migration 19
component
Millennium 196, 327
manages 9
Millennium support 200, 331
monitors 9
modify 108, 234
overview 9
modifying the default virtual terminal pool definition 214,
OMEGAMON II for CICS 50
346
OMEGAMON RETRY parameter 40
modifying VTAM node and application definitions 28, 30, 31
OMEGAMON Subsystem
monitoring a user-defined event 190, 321
z/OS 3
monitoring active 47
OMEGAMON WLM definitions
monitoring agents
preparing for upgrade 17
managed system 3
OMEGAMON XE for CICS
overview 3
planning configuration 15
Monitoring Control Table 36
OMEGAMON XE for CICS TG
monitoring control table (MCT)
planning configuration 16
system records 194, 325
OMEGBSC 200, 331
monitoring options 128, 164, 258, 294
OMEGBSC segment
monitoring, OMEGAMON 36
data collection overhead, reducing 36
OMEGBSC 36
N OMEGDEMO 95, 221
OMEGPLEX 54
NATURAL 196, 327 OMEGPLEX, default 55, 75
NATURAL support 200, 331 OMNIMON base
NATURQL 200, 331 z/OS 3
Near-Term History 123, 125, 251, 253 OMUMBSUB program 202, 333
Near-Term History PDS calculation 123, 125, 251, 253 OMUSEREC program 202, 333
NetView for z/OS 98, 224 opening 68
Network Access Manager internal security 99, 224 optional 117, 243
network names 216, 347 orphaned transactions
new release 17 defined 47
Override Goal element 93
O overriding 72
overriding default parameters 210, 341
OBVTAM 213, 345 overview 127, 167, 257, 297
OCCIREQ DD statement 40
OMEG CANCEL command 40
P
OMEG transaction 40
OMEGAMON enhanced 3270 user interface 54, 55, 75 PARMGEN 25
OMEGAMON Enhanced 3270 User Interface PCS 196, 327
z/OS 3 PCS support 201, 332
OMEGAMON enhanced 3270 user interface component PDS 122, 250
manages 7 persistent data store 123, 125, 251, 253
monitors 7 persistent datastore
overview 7 size 122, 250

Index 359
planning configuration of OMEGAMON for CICS 15 security tables for external and internal security 108, 234
planning configuration of OMEGAMON for CICS TG 16 security, functional, external, internal 99, 224
post installation configuration 44, 47 self-describing agent enablement 53
Preferences For All CICSplex Agents subpanel 56, 60 service class
preparing 167, 298 deleting 73
prerequisites service class goal 72
configuration 26 service classes 66
preventive service planning (PSP) bucket 196, 327 service level analysis
procedures 168, 298 enhanced 3270UI 74
producing 173, 182, 303, 313 service level analysis definitions 72
profiles 118, 244 Service Level Analysis definitions 66, 82
profiles, types 118, 244 service policies 66
Program Load Table 36 service policy
programs and transactions deleting 73
defining 40 Service Policy element 93
service policy, activate 71
ServiceClass element 91
R shared z/OS agent
RACF external security 99, 224 component 3
records SLA definitions 87, 91, 93
file and database 195, 326 SLA updates 73
records: transaction SMF 193, 324
transaction records 196, 327 specifying ACB names 216, 347
refreshing 164, 294 specifying network names 216, 347
reports 182, 313 specifying the call to the subroutine in the application 191,
resetting 73 322
resource names 95, 221 START command 210, 341
response time transaction groups 186, 317 start options 210, 341
return codes 94 start options, OBVTAM 210, 341
reviewing format rules for control statements 108, 234 starting, OBVTAM 210, 341
RKANHENU ddname 218, 351 STOP command 213, 345
RKANPAR ddname 218, 351 STOP OMEGAMON for CICS (3270) command 213, 345
RKC2GLB ddname 218, 351 stopping ITCAM for CICS in a CICS region 217, 349
RKC2XM 214, 345 subroutine call syntax 203, 334
RKC2XM00 214, 345 subroutine calls 191, 322
RKC2XMnn ddname 218, 351 subroutines 202, 333
RKLVLOG 53 summary log file 93
RKLVSNAP ddname 218, 351 SUPRA 196, 201, 327, 332
RKOCPCSV ddname 218, 351 SUPRA, installing support 201, 332
RKOCPFSV ddname 218, 351 sweep policy updates 47
RKOCPROC ddname 218, 351 sweepInterval parameter 47
RKOCPROF ddname 218, 351 sweepTimeout parameter 47
RTE_SECURITY_CLASS 95, 221 System Initialization Table 36
run 167, 298 System Management Facilities (SMF) 120, 246
running 168, 169, 178, 299, 300, 309 System Management Facility
dictionary records 196, 327
file and database records 195, 326
S interval records 194, 325
operational considerations 193, 324
sample code
record layout 193, 324
OMEGAMON for CICS 191, 322
record type 193, 324
SAS 166, 297
system records 194, 325
SAS DAILY data set 178, 309
transaction records 196, 327
SAS DETAIL data set 173, 303
system records 194, 325
SAS historical reporter 166, 297
SAS historical reports 168, 298
SAS sample historical reports 167, 297, 298 T
secondary TCPIP stack 47
securing 95, 221 Take Action commands
security 28, 54, 95, 118, 221, 244 securing 95, 221
security authority 55, 75 task history data
security considerations 19 collecting 126, 255
security exit routines for OMEGAMON for CICS (3270) 99, storing 126, 255
224 third-party support 196, 327
Tivoli Enterprise Portal 66

360 IBM Z OMEGAMON for CICS: Planning and Configuration Guide

Tivoli Management Services W
System z products 1
transaction monitoring support 44 web service details 205, 336
transaction tracking what to specify in your application code before the user
ITCAM for CICS V7.1.0 217, 348, 349 event 192, 323
ITCAM for Transactions V7.1.0 217, 348, 349 where to specify the call to the subroutine for monitoring
starting ITCAM for CICS in a CICS region 217, 348, 349 user-defined events 192, 323
TxnMonitor exit 45 workload
deleting 74
workload element 91
U workloads 66
UFO/Forms 196, 202, 327, 333
UFO/Forms, installing support 202, 333 X
UMBFIND program 202, 333
umbrella services 205, 336 XML format 87
Umbrella transaction services
using subroutines 202, 333
unlocking 99, 224
update 61
updating agent and Tivoli Enterprise Monitoring Server
protocols 30, 31
updating CICSplex rules 95, 221
updating the security table 108, 234
upgrade considerations 19
upgrading 17
upgrading to a the new release 17
used 95, 221
user-defined event parameters 190, 321
user-defined events
stopping monitoring 193, 324
what to specify in your application code after the user
event 193, 324
using 93, 99, 166, 224, 297
using generic profiles to define resources 95, 221
Using subroutines 202, 333
using the KOCSUPDI member in the TKANSAM library 28
using the Preferences For All CICSplex Agents subpanel 56,
60
using the Rule Definitions for All CICSplexes subpanel 56
using wild card characters 63
USREVNT1
parameters available 190, 321

V
verifying 49, 51–53, 72
Version 4.2.0
resource security 95, 221
virtual pool definitions 215, 346
virtual terminal definition statement 215, 347
virtual terminal definitions 216, 347
virtual terminal pool
OMEGAMON for CICS (3270) access to 217, 348
virtual terminal pool definitions
sharing 215, 346
virtual terminal pool definitions OMEGAMON for CICS (3270)
214, 346
virtual terminal pools 214, 346
VTAM node and application definitions
modifying 31
VTAM Node and application definitions 26
VTM1 215, 346, 347

Index 361
362 IBM Z OMEGAMON for CICS: Planning and Configuration Guide
IBM®

Product Number: 5698-T07