IBM Support

V 5.3.0: Updates to the manual "Monitoring Performance from the OMEGAMON Classic Interface" of the products "IBM Tivoli OMEGAMON XE for DB2 Performance Expert on z/OS" and "IBM Tivoli OMEGAMON XE for DB2 Performance Monitor on z/OS

Product documentation


Abstract

This document contains updates of the manual "Monitoring Performance from the OMEGAMON Classic Interface", SH12-7050-00, of the products "IBM ® Tivoli® OMEGAMON for DB2® Performance Expert on z/OS" and "IBM Tivoli OMEGAMON XE for DB2 Performance Monitor on z/OS", Version 5.3.0.

Content

  • Update 1 (June 2016) in Chapter 8. Application Trace Facility (ATF) to reflect enhanced filtering functionality.
  • Update 2 PI72198 (February 2017) in Chapter 8. Application Trace Facility (ATF) filtering enhancements.
__________________________________________________________________________________
Update 1 (June 2016) in Chapter 8. Application Trace Facility (ATF) to reflect enhanced filtering functionality

Specify Application Trace

Use these two panels to specify the criteria for the application to be traced and the data set to which the trace data is to be stored for later analysis.

In the first panel, specify the destination data set and the filtering values to limit the data collected and written to the output data set. In the second panel, specify the options that limit the data collected (IFCID-related) together with the scheduling and duration options.

All ATF panels display the current trace status. The following values might be displayed:
ACTIVE
The application trace is active.
INACTIVE
The application trace is inactive.
DSN FULL
The output file ran out of space.
INIT-XXX
This status is briefly displayed during an early stage of initialization.
ABENDED
The application trace is abended.

Specifying multiple filter values
The following filtering options support multiple values:

  • PLANNAME
  • PACKNAME
  • COLLID
  • PKGLOC
  • AUTHID
DB2 limits the trace specification so that only ONE of these fields can contain multiple values. For example, if you specify three values for PLANNAME, you can specify only one (or > zero) value for any of the other four options that support multiple values.

Panel 1: Specify the destination data set and the filtering values:

________________ ZATRQ    VTM     O2       V530.#P SEB1 04/07/16 18:15:43   3
>         Help PF1                                            Back PF3        
> A.A     Current Trace Status: INACTIVE                                      
> *-SPECIFY TRACE    B-VIEW TRACE       C-STOP TRACE       D-SELECT DSN        
> E-VIEW DATASET     F-STOP VIEW        G-CREATE VSAM LDS  H-QUEUED TRACES    
===============================================================================
>                          SPECIFY APPLICATION TRACE                          
ATRQ                                                                          
+         DSN= ____________________________________________  Mode= Append      
+                         Plan name(s) or ALL for all active threads          
+    PLANNAME= ________   ________   ________   ________   ________            
+    PACKNAME= ________   ________   ________   ________   ________            
+      COLLID= ________________   ________________   ________________          
+      PKGLOC= __________________   __________________                        
+      AUTHID= ________   ________   ________   ________   ________            
+    XPLN= N      XPKG= N      XCOL= N      XPLO= N      XAUT= N              
+     TSOUSER= ________  TSO UserID        |   JOBNAME= ________  Job Name    
+    CICSTRAN= ____      CICS Trans ID     |  CICSCONN= ________  CICS Conn. ID
+     PSBNAME= ________  IMS PSB Name      |     IMSID= ________  IMS Region ID
+    WSUSERID= ________________            |    WRKSTN= __________________    
+     APPNAME= ________________________________                                
+             Press <ENTER> to continue to Trace Specification                
==============================================================================
=

Panel 2: Specify the Trace Level Details:

________________ ZATRQ    VTM     O2       V530.#P SEB1 04/07/16 18:17:04   3
>         Help PF1                                            Back PF3        
> A.A     Current Trace Status: INACTIVE                                      
> *-SPECIFY TRACE    B-VIEW TRACE       C-STOP TRACE       D-SELECT DSN        
> E-VIEW DATASET     F-STOP VIEW        G-CREATE VSAM LDS  H-QUEUED TRACES    
===============================================================================
>                          SPECIFY APPLICATION TRACE                          
ATRQ                                                                          
+                               Trace Level Details                            
+     STATSQL= N   Static  SQL?  (Y/N)     |   SQLDATA= Y   Dynamic SQL?  (Y/N)
+    LOCKDATA= Y   Lock    Data? (Y/N)     |  SCANDATA= Y   Scan    Data? (Y/N)
+    THRDDATA= Y   Thread  Data? (Y/N)     |  CONNDATA= Y   Connect Data? (Y/N)
+    HOSTVARS= N   Host Variable?(Y/N)                                        
+                        Trace Duration and Scheduling                        
+     MEMSIZE= 02  (01-04MEG)  TIME= 0005  (0001-0060)  FLUSH= 300  (001-300)  
+    DEFERRED:  STDATE= MM/DD/YYYY  STTIME= HH:MM  (mm/dd/yyyy dd.mm.yyyy)    
+                                 Destination Options                          
+         SMF= N   Output to SMF? (Y/N)    |       GTF= N   Output to GTF?(Y/N)
===============================================================================

To limit trace overhead incurred by the DB2® subsystem and OMEGAMON® XE for DB2 PE, qualify your trace request as much as possible. To qualify a trace request, enter the required information for only one of the connection types (TSO, batch, CICS®, or IMS™).

Note: Use SMP/E USERMOD if you want to change default options and limits listed below. See TKANSAM(KO2MOD01) for more information.

Navigation
For additional options, use the PF keys.

Fields

DSN
The name of a VSAM data set. If you want trace data to be saved for later viewing, enter the name of a preallocated, preformatted data set; otherwise, leave this field blank.

For considerations about sizing VSAM data sets for various record types and output devices, see Configuration and Customization.

For procedures about customizing the Application Trace Facility, see Configuration and Customization. The ATF uses only the primary extent of a data set; it does not use secondary extents. Keep this in mind when considering space requirements for the trace data.


    MODE
    Defines whether trace data is appended to existing data in the VSAM data set that is specified in the DSN field. You can use the following values:
    APPEND
    Any previously collected trace data is retained and new data is appended to the end of existing data.
    This is the default value.
    REUSE
    Deletes existing trace data from a data set before new trace data is added.

You can change the default value by adding the keyword ATFMODE to the member OMPEOPTS in the rhilev.RKD2PAR(OMPEOPTS) data set. Valid values for the keyword ATFMODE are APPEND or REUSE.

PLANNAME
The DB2 plan names of the application threads to be traced. To trace all thread activity, set the plan name to ALL. This field is required. See also Specifying multiple value filters. This is a mixed case field, so it MUST be entered in the correct case for the filter to match.
PACKNAME
DB2 package that is to be traced. See also Specifying multiple value filters. This is a mixed case field, so it MUST be entered in the correct case for the filter to match.
COLLID
The collection ID for the requested packages. Use this filter to limit tracing to only those specified collections. See also Specifying multiple value filters. This is a mixed case field, so it MUST be entered in the correct case for the filter to match.
PKGLOC
The locations that the requested packages have been bound on. See also Specifying multiple value filters. This is a mixed case field, so it MUST be entered in the correct case for the filter to match.
AUTHID
The DB2 authorization IDs of the application (threads) to be traced. This field is optional, however, you should supply one or more authorization IDs to limit trace overhead and the amount of data collected. See also PLANNAME for possible restrictions.
Exclude Specifications
These fields indicate that the filters can be used to include (N) or exclude (Y) data based on the filter values. For example, a value XPKG=Y and PKGNAME=PACK1 PACK2 PACK3 means that all packages EXCEPT these three are traced.
TSOUSER
The TSO user ID of the application (thread) to be traced if the application originates from a DB2 TSO connection. This limits the amount of trace data collected and overhead incurred.
JOBNAME
The jobname of the application (thread) to be traced if the application originates from a DB2 batch (TSO background) connection. This limits the amount of trace data collected and overhead incurred.
CICSTRAN
The transaction ID of the application (thread) to be traced if the application originates from a DB2 CICS connection. This limits the amount of trace data collected and overhead incurred.
CICSCONN
The DB2 connection ID of the CICS region from which the application (thread) originates. This limits the amount of trace data collected and overhead incurred.
PSBNAME
The IMS PSB name of the application (thread) if the application originates from the DB2 IMS connection. This limits the amount of trace data collected and overhead incurred.
IMSID
The IMSID of the IMS region from which the application (thread) originates. This limits the amount of trace data collected and overhead incurred.
WSUSERID
The end user ID from the workstation that initiated the application. Enter the value in uppercase only.
WRKSTN
The name of the workstation that initiated the application. Enter the value in uppercase only.
APPNAME
The client application driving the DB2 connection. Enter the value in uppercase only.
STATSQL
Specify Yes to enable display of static SQL statements.
SQLDATA
Specify No to inhibit collection of DB2 SQL trace records. This reduces the number of captured trace records and associated overhead.
SQLDATA activates the following IFCIDs:

  • 58 END OF SQL STATEMENT EXECUTION
  • 59 START OF FETCH SQL STATEMENT EXEC
  • 60 START OF SELECT SQL STATEMENT EXEC
  • 61 START OF INSERT, UPDATE, DELETE SQL
  • 62 START OF DDL STATEMENT EXECUTION
  • 63 SQL STATEMENT TO BE PARSED
  • 64 START PREPARE SQL STATEMENT EXEC
  • 65 START OPEN CURSOR STATIC/DYN SQL
  • 66 START CLOSE CURSOR STATIC/DYN SQL
  • 177 SUCCESSFUL PACKAGE ALLOCATION
  • 233 START/END CALL TO USER ROUTINE
LOCKDATA
Specify NO to inhibit collection of DB2 lock trace records. This reduces the number of captured trace records and associated overhead.
LOCKDATA activates the IFCID 21 DETAIL LOCK REQ.ON RETURN FROM IRLM.
SCANDATA
Specify NO to inhibit collection of DB2 scan trace records. This reduces the number of captured trace records and associated overhead.
SCANDATA activates the following IFCID(s):
  • 15 INPUT MATCH./NON-MATCH.INDEX SCAN
  • 16 INPUT TO THE FIRST INSERT
  • 17 INPUT TO SEQUENTIAL SCAN
  • 18 END INDEX SCAN, INSERT, SEQ. SCAN
  • 221 PARALLEL DEGREE FOR PARALLEL GROUP
  • 222 PARALLEL GROUP ELAPSED TIME
  • 231 PARALLEL GROUP COMPLETION
THRDDATA
Specify NO to inhibit collection of DB2 thread trace records. This reduces the number of captured trace records and associated overhead.
THRDDATA activates the following IFCID(s):
  • 68 BEGINNING OF A ROLLBACK REQUEST
  • 69 ENDING OF A ROLLBACK REQUEST
  • 70 BEGIN COMMIT PHASE 2 REQUEST
  • 71 END COMMIT PHASE 2 REQUEST
  • 73 ENDING OF A CREATE THREAD REQUEST
  • 74 BEGINNING OF TERM. THREAD REQUEST
CONNDATA
Specify NO to inhibit collection of DB2 connection trace records. This reduces the number of captured trace records and associated overhead.
CONNDATA activates the following IFCID(s):
  • 84 BEGIN PHASE 1 COMMIT REQUEST
  • 85 END PHASE 1 COMMIT REQUEST
  • 86 BEGINNING OF SIGNON REQUEST
  • 87 ENDING OF SIGNON REQUEST
  • 88 BEGINNING OF A SYNC REQUEST
  • 89 ENDING OF A SYNC REQUEST
  • 95 SORT STARTED
  • 96 SORT ENDED
HOSTVARS
Specify Y to enable input HOSTVAR data collection. The default is N.
HOSTVARS activates the IFCID 247 SQLDA AND INPUT HOST VARIABLE DATA.
MEMSIZE
Specifies the amount of virtual memory to be used for the collection work area. You can specify a value from 1 to 4 MB.
The default value is 2 MB.
TIME
The time (in minutes) that OMEGAMON XE for DB2 PE will trace the application. The default is 5 minutes. The trace time can be any value from 1 through 60 minutes. The length of the application trace should be minimized to limit the resource utilization (CPU, memory) required by the facility.
FLUSH
The interval at which ATF processing will flush those Unit of Work (UOW) records that are complete and write them to the VSAM data set. The default is 300 seconds (5 minutes).
DEFERRED
Optionally, you can defer the start of the trace request by specifying the following fields:
STDATE
The date (in mm/dd/yyyy or dd.mm.yyyy format) the trace request is to start. You can specify the current date or a date in the future.
STTIME
The time (in 24 hour format) the trace is to start. This field is required, if STDATE is specified.
If STDATE represents the current date, STTIME must be a time in the future.
If STDATE is for a future date, this field must be a valid time.
If the OMEGAMON Collector Address Space is stopped, all scheduled requests will be lost. Both fields must be entered for the request is to be deferred. Deferred requests must be written to VSAM datasets.
Deferred information cannot be entered when the ATF command is entered from the Thread Detail display.
SMF
Specifies whether the trace data will be written out to SMF in addition to the capture. The default is N. SMF and GTF are mutually exclusive fields. You can specify N for both fields, but not Y.
GTF
Specifies whether the trace data will be written out to GTF in addition to the capture. The default is N. SMF and GTF are mutually exclusive fields. You can specify N for both fields, but not Y.

When you complete the fields in this panel and press Enter, OMEGAMON XE for DB2 PE displays a confirmation panel that contains the values you supplied. To start the application trace using these values, press Enter. To change the values without starting a trace, press F3.
__________________________________________________________________________________
Update 2 PI72198 (February 2017) in Chapter 8. Application Trace Facility (ATF) filtering enhancements

The following additional functionality has been added to Application Trace Facility:

  • Routine (stored procedure/UDF) filtering
  • Trace collection from all members of a data sharing group
  • Filtering ATF reports by threshold values
  • Changes to Queued Traces in support of threshold filters
  • Changes to the Main menu and STOP VIEW menu

Routine filtering

Tracing can to be limited to records cut by requested stored procedures. Use the ATRQ command to specify up to 2 routine filters, with each filter consisting of a schema and name to reduce the amount of trace data collected. The schema and name fields support wildcard characters, and are case sensitive.


 ________________ ZATRQ    VTM     O2       V530.#P SEB1 01/20/17  7:21:13   3

>         Help PF1                                            Back PF3        
> A.A     Current Trace Status: INACTIVE                                      
> *-SPECIFY TRACE    B-VIEW TRACE       C-STOP TRACE       D-SELECT DSN        
> E-VIEW DATASET     F-STOP VIEW        G-CREATE VSAM LDS  H-QUEUED TRACES    
===============================================================================
>                          SPECIFY APPLICATION TRACE                          
 ATRQ                                                                          
:         DSN= WDRI.V520PGEN.SEB1.ATF.DSG01                  Mode= Append      
+                         Plan name(s) or ALL for all active threads          
:    PLANNAME= ________   ________   ________   ________   ________            
:    PACKNAME= ________   ________   ________   ________   ________            
:      COLLID= ________________   ________________   ________________          
:      PKGLOC= __________________   __________________                        
:      AUTHID= ________   ________   ________   ________   ________            
:    XPLN= N      XPKG= N      XCOL= N      XPLO= N      XAUT= N              
:     TSOUSER= ________  TSO UserID        |   JOBNAME= ________  Job Name    
:    CICSTRAN= ____      CICS Trans ID     |  CICSCONN= ________  CICS Conn. ID
:     PSBNAME= ________  IMS PSB Name      |     IMSID= ________  IMS Region ID
:    WSUSERID= ________________            |    WRKSTN= __________________    
:     APPNAME= ________________________________                                
:    ROUTINE1= ________  . __________________________________________________  
:    ROUTINE2= ________  . __________________________________________________  
+             Press <ENTER> to continue to Trace Specification                
===============================================================================

  • When you specify routine names, enter both the schema and the name. If only one is specified, an error message is displayed.
  • If only one filter is requested, it must be in the ROUTINE1 entry.
  • When requesting filtering by routine, filtering by PACKAGE, COLLID and PKGLOC is not supported, and if you specify this you an error message is displayed.
  • SQLDATA (on the second panel) MUST be set to “Y”. If SQLDATA=N is specified, an error is generated.
  • The data be captured to a VSAM dataset, in-memory traces are not able to handle the filtering.

The following sections in the help have also been updated to provide new information:

Note on multiple filtering values
There are a number of filtering options that support multiple values. These options are PLANNAME, PACKNAME, COLLID, PKGLOC and AUTHID. However DB2 limits the trace specification such that only ONE of these fields can contain multiple values. For example, if 3 plan names are specified, only one (or zero) entries can be specified for the other 4 options that support multiple values.
Note on wildcarding character strings
Fields PLANNAME, PACKNAME,COLLID, PGKLOC, AUTHID, TSOUSER, JOBNAME, CICSTRAN, CICSCONN, PSBNAME, IMSID, WSUSERID, WRKSTN, APPNAME, ROUTINE1 and ROUTINE2 support wildcards. The allowed wildcards are "_" which matches a single character within the string and "*" which matches the remaining string.
Application Trace follows the DB2 -START TRACE wildcard syntax so the "*" can only be located at the end of the value.

Note on filtering restrictions when filtering on ROUTINE
Due to the way that DB2 trace filters reduce the records generated, it isn't possible to use the following filters when tracing ROUTINE execution:
PACKNAME, COLLID and PKGLOC. If these filters are requested at trace specification, mesage KO2O1165E will be issued.

Exclude Specifications
These fields can be used to indicate that the filters are to be used to include ("N") or exclude ("Y") data based on the filter values.
For example, a value XPKG=Y and PKGNAME=PACK1 PACK2 PACK3 all packages EXCEPT these three will be traced.

Note on WSUSERID, WRKSTN, APPNAME, ROUTINE1 and ROUTINE2
WSUSERID, WRKSTN, APPNAME, ROUTINE1 and ROUTINE2 are case sensitive, and will NOT be folded to upper case before being passed to DB2, so if the value is all caps, it must be entered in upper case on this panel.
For these fields, the valid characters are upper and lower case letters, numbers, the MVS Defined "national characters" (#,@,$), the dash "-", the underscore character ("_") and the asterisk ("*"). Note that the last two are used as wild cards, and that the asterisk is only valid at the end of the field value.
WSUSERID
The end user ID from the workstation that initiated the application.

WRKSTN
The name of the workstation that initiated the application.

APPNAME
The client application driving the DB2 connection.

ROUTINE1 and ROUTINE2
Limit tracing to only when user routines, specified by 1-8 SCHEMA and 1-50 character name, which represents the specific name of the routine.
Up to 2 routines can be specified, and both fields and specifications can contain wildcards. Note that while the ROUTINE1 specifies the ROUTINE NAME (target of the SQL CALL statement) ATF actually records and reports on the PROGRAM NAME. For external procedures, this is the value in the EXTERNAL_NAME column of SYSIBM.SYSROUTINES for the procedure. In order to capture ROUTINE
specific data, SQLDATA=Y must be specified.
If only one routine is requested, it must be in ROUTINE1, a blank ROUTINE1 and data in ROUTINE2 is invalid.
ROUTINE filitering REQUIRES that the output be collected to a VSAM dataset. If DSN is blank, specifying ROUTINE1 will result in an Error.
NOTE: If the terminal that is logged on to OMEGAMON is defined as 24x80
also known as MOD2, only ROUTINE1 can be specified.

GROUP
Specify Y to activate the trace on members of the current Data Sharing Group. All data will be consolidated in the one output source.
Note that GROUP will only be allowed if an output Dataset Name is provided.

Collecting trace data from all members of a Data Sharing Group

A new Trace Level Detail option GROUP=|N|Y has been added to the second ATRQ panel.

________________ ZATRQ    VTM     O2       V530.#P SEB1 01/20/17  7:58:49   3  
>         Help PF1                                            Back PF3          
> A.A     Current Trace Status: INACTIVE                                        
> *-SPECIFY TRACE    B-VIEW TRACE       C-STOP TRACE       D-SELECT DSN        
> E-VIEW DATASET     F-STOP VIEW        G-CREATE VSAM LDS  H-QUEUED TRACES      
===============================================================================
>                          SPECIFY APPLICATION TRACE                            
 ATRQ                                                                          
+                               Trace Level Details                            
:     STATSQL= N   Static  SQL?  (Y/N)     |   SQLDATA= Y   Dynamic SQL?  (Y/N)
:    LOCKDATA= Y   Lock    Data? (Y/N)     |  SCANDATA= Y   Scan    Data? (Y/N)
:    THRDDATA= Y   Thread  Data? (Y/N)     |  CONNDATA= Y   Connect Data? (Y/N)
:    HOSTVARS= N   Host Variable?(Y/N)     |     GROUP= N   Group Scope?  (Y/N)
+                        Trace Duration and Scheduling                          
:     MEMSIZE= 02  (01-04MEG)  TIME= 0005  (0001-0060)  FLUSH= 300  (001-300)  
:    DEFERRED:  STDATE= MM/DD/YYYY  STTIME= HH:MM  (mm/dd/yyyy dd.mm.yyyy)      
+                                 Destination Options                          
:         SMF= N   Output to SMF? (Y/N)    |       GTF= N   Output to GTF?(Y/N)
===============================================================================

When the GROUP= option is set to YES, the trace is started with SCOPE(GROUP) specified, which collects data from all members of the data sharing group.

If no DSN is specified on the first ATRQ panel, the GROUP= option is not displayed, because the option is only available for trace written to VSAM datasets.

Note:

  • Depending on the number of members and the activity levels on them, use of this feature could put additional strain on the DB2 coupling services, as the data gets passed through the coupling facility
  • In addition, the VSAM dataset could fill much more quickly, increasing the possibility for record loss.

Filtering ATF reports by threshold values

You can filter the generated reports by threshold values related to a number of metrics associated with a unit of work. The ATRD command display now has multiple panels, similar to the ATRQ command when you request a trace to be collected. ATRD has:

  • Two input display panels
  • An output-only request summary display panel

The first input display:


________________ ZATRD    VTM     O2       V530.#P SZ11 01/23/17 23:11:21   3
>       Help PF1                                               Back PF3        
> A.D   Current Trace Status: INACTIVE                                        
> A-SPECIFY TRACE    B-VIEW TRACE       C-STOP TRACE       *-SELECT DSN        
> E-VIEW DATASET     F-STOP VIEW        G-CREATE VSAM LDS  H-QUEUED TRACES    
===============================================================================
>                     SELECT DATASET AND TRACE PARAMETERS                      
 ATRD                                                                          
+                                                                              
+ Option H Is Recommended for Accessing VSAM Trace Datasets                    
+                                                                              
+ Enter trace dataset which contains the captured trace, and additional        
+ (optional) selection criteria to limit trace information reported.          
+ When complete press ENTER                                                    
+                                                                              
:          DSN= ____________________________________________ (Required)        
:     PLANNAME= ________   ________   ________   ________   ________          
:       AUTHID= ________   ________   ________   ________   ________          
:      TSOUSER= ________  TSO UserID      |   JOBNAME= ________  Job Name      
:     CICSTRAN= ____      CICS Trans ID   |  CICSCONN= ________  CICS Conn. ID
:      PSBNAME= ________  IMS PSB Name    |     IMSID= ________  IMS Region ID
+             Press <ENTER> to add additional Filter Options                  
===============================================================================

Press Enter to display the second panel. This is where most of the existing character string filter data is entered:

________________ ZATRD    VTM     O2       V530.#P SZ11 01/23/17 23:11:21   3
>       Help PF1                                               Back PF3        
> A.D   Current Trace Status: INACTIVE                                        
> A-SPECIFY TRACE    B-VIEW TRACE       C-STOP TRACE       *-SELECT DSN        
> E-VIEW DATASET     F-STOP VIEW        G-CREATE VSAM LDS  H-QUEUED TRACES    
===============================================================================
>                     SELECT DATASET AND TRACE PARAMETERS                      
 ATRD                                                                          
+                                                                              
+ Option H Is Recommended for Accessing VSAM Trace Datasets                    
+                                                                              
+ Enter trace dataset which contains the captured trace, and additional        
+ (optional) selection criteria to limit trace information reported.          
+ When complete press ENTER                                                    
+                                                                              
:          DSN= ____________________________________________ (Required)        
:     PLANNAME= ________   ________   ________   ________   ________          
:       AUTHID= ________   ________   ________   ________   ________          
:      TSOUSER= ________  TSO UserID      |   JOBNAME= ________  Job Name      
:     CICSTRAN= ____      CICS Trans ID   |  CICSCONN= ________  CICS Conn. ID
:      PSBNAME= ________  IMS PSB Name    |     IMSID= ________  IMS Region ID
+             Press <ENTER> to add additional Filter Options                  
===============================================================================

There are six new threshold fields on this panel. They are entered in the format:

<OP>b<VALUE>

Where <OP> is a character-based comparison operator, with GT (Greater Than) being the default.

Supported operators are:

Operator Meaning
GT Greater Than
GE Greater Than or Equal To
LT Less Than
LE Less Than or Equal To
EQ Equal To
NE Not Equal

The following filtering thresholds are supported:

INDB2TME
The DB2 Elapsed Time filtering provides the ability to display only units of work which exceed the specified filtering limits. The value is a 13-character numeric field (maximum value is 999999.999999 seconds).
Valid examples of this field are:

  • 999999
  • 999
  • 9.009
  • 0.9
  • .0009
  • .000009
  • 999.999

INDB2CPU

The DB2 CPU Time Filtering provides the ability to display only units of work which exceed the specified filtering limit. A 13 character numeric with a maximum value of 999999.999999. This field has the same format as INDB2TME.

SQLCALLS
Allows filtering on the SQL statement count to display only units of work which exceed the specified filtering limit. The value is a positive integer of 9 digits or less.

ROWSPROC
Allows filtering on the number of rows processed by the UOW to display only units of work which exceed the specified filtering limit. The value is a positive integer of 9 digits or less.

NUMSORT
Allows filtering on the number of sorts requested by the UOW to display only units of work which exceed the specified filtering limit. The value is a positive integer of 9 digits or less.

LOCKSACQ
Allows filtering on the number of locks acquired by the UIW. The value is a positive integer of 9 digits or less.

Press ENTER from this panel to display a read-only panel that contains the filter values entered from the first two panels:

________________ ZATRD    VTM     O2       V530.#P SZ11 01/23/17 23:38:12   3
>       Help PF1                                               Back PF3        
> A.D   Current Trace Status: INACTIVE                                        
> A-SPECIFY TRACE    B-VIEW TRACE       C-STOP TRACE       *-SELECT DSN        
> E-VIEW DATASET     F-STOP VIEW        G-CREATE VSAM LDS  H-QUEUED TRACES    
===============================================================================
>                     SELECT DATASET AND TRACE PARAMETERS                      
 ATRD                                                                          
+          DSN=WDRI.V520PGEN.SZ11.ATF.DSG00                (Required)          
+     PLANNAME=W*       ________ ________ ________ ________                    
+       AUTHID=________ ________ ________ ________ ________                    
+      TSOUSER=________ TSO UserID      |  JOBNAME=________ Job Name          
+     CICSTRAN=____     CICS Trans ID   |  CICSCONN=________ CICS Conn. ID    
+      PSBNAME=________ IMS PSB Name    |    IMSID=________ IMS Region ID      
+       STARTDATE=________(MM.DD.YY)STARTTIME=________(HH.MM.SS)              
+         ENDDATE=________(MM.DD.YY)  ENDTIME=________(HH.MM.SS)              
+           DB2ID=____    DB2 Subsystem ID                                    
+           MVSID=____    MVS System ID                                        
+        STATSQL=N        Static SQL?(Y/N|HOSTVARS=N   Host Variable?(Y/N)    
+       INDB2TME GT      5.000000  (sec) |INDB2CPU GT       .100000  (sec)    
+       SQLCALLS GT _________   SQL Call |ROWSPROC GT      1000   Row Proc    
+        NUMSORT GT _________   Sort     |LOCKSACQ GT _________   Lock Acq    
===============================================================================
To start initialization for viewing the dataset, press Enter.

Note:

If you enter values for multiple fields of the 6 thresholds the values are ANDED so only units of work that contain values that satisfy all of the thresholds are displayed.

Changes to Queued Traces in support of Threshold Filters

The QUEUED TRACES processing, accessible from Option H of ZATMENU has been changed to support the specification of Threshold Filters when viewing a trace queue element.

When you zoom into a Queued Trace Dataset Entry, a new option, E-APPLY FILTERS, has been added to all the panels:

________________ ZATVB    VTM     O2       V530.#P SZ11 02/06/17 22:29:39   2  
>       Help PF1      Back PF3      Up PF7      Down PF8                        
> *-VIEW TRACE       B-VIEW DATASET     C-DELETE ENTRY     D-STOP TRACE        
> E-APPLY FILTERS                                                              
===============================================================================
>                   QUEUED APPLICATION TRACE DETAILS                            
 ATVW                                                                          
+ Queued Request Owner   = WDRI          Type                      = Immediate  
+ Trace Status           = INACTIVE      Trace Time Remaining      = 00:00:00  
+ Trace Start Time       = 21:38:44      Trace Start Date          = 02/06/2017
+ Trace End Time         = 21:43:45      Trace End Date            = 02/06/2017
+ Trace Time Limit       = 00:05:00                                            
+                                                                              
+ DSN                    = WDRI.V520PGEN.SZ11.ATF.DSG00                        
+                                                                              
+ Trace records captured =  158398       Trace records lost        =  239998    
+ UOW records captured   =      17       UOW records lost          =       0    
+                                                                              
+       >> KO2O1133E APPLICATION TRACE DATA HAS BEEN LOST.  COLLECTOR UNABLE <<
+       >>           TO PROCESS VOLUME OF DATA COLLECTED (ATVWATVW)          <<
+                                                                              
+ Trace Request Information :                                                  
+                                                                              
+ PLANNAME   = W*                                                              
:  STATSQL= N                                                                  
+ HOSTVARS   = N                                                                
+ GROUP      = Y                                                                
+                                                                              
+                                                                              
+              Trace data is being captured to dataset.                        
+              Please view trace from dataset using option B  
===============================================================================   

Other panel menus 

Option B

________________ ZATQD    VTM     O2       V530.#P SZ11 02/06/17 22:32:21   3
>       Help PF1      Back PF3      Up PF7      Down PF8       Zoom PF11      
>         Current Trace Status: INACTIVE                                      
> A-VIEW TRACE       *-VIEW DATASET     C-DELETE ENTRY     D-STOP TRACE      
> E-APPLY FILTERS                                                            
==============================================================================
>               APPLICATION TRACE THREAD SUMMARY -- VIEW DATASET              
 ATVD                                                                        
+                                                                            
+ DSN               = WDRI.V520PGEN.SZ11.ATF.DSG00                            
+ Start Date        = 02/06/2017          Start Time       = 21:38:44        
+ End Date          = 02/06/2017          End Time         = 21:43:45        
+ PLANNAME          = W*                                                      
+                                                                            
+ Planname Connid   Corrid       Authid   DB2  MVS  InDB2 CPU Commits  Aborts
+ -------- -------- ------------ -------- ---- ---- --------- -------- ------
+ WDPLAN02 RRSAF    WEDINDIO003  WDRI     SZ11 PMO1    .18950        1      0
+ WDPLAN01 RRSAF    WEDINDIO004  WDRI     SZ11 PMO1    .18404        1      0
+ WDPLAN02 RRSAF    WEDINDIO003  WDRI     SZ12 PMO2    .08944        1      0
+ WDPLAN01 RRSAF    WEDINDIO003  WDRI     SZ12 PMO2    .06009        1      0
+ WDPLAN02 RRSAF    WEDINDIO003  WDRI     SZ13 PMO2    .05992        1      0

Option C

________________ ZATQX VTM O2 V530.#P SZ11 02/06/17 22:35:06 3
>       Help PF1      Back PF3      Up PF7      Down PF8       Zoom PF11      
>         Current Trace Status: INACTIVE                                      
> A-VIEW TRACE       B-VIEW DATASET     *-DELETE ENTRY     D-STOP TRACE      
> E-APPLY FILTERS                                                            
==============================================================================
>               APPLICATION TRACE QUEUE - DELETE ENTRY                        
>                                                                            
 ATQV                                                                        
+  Owner                 = WDRI          State                     = Complete
+  First Plan            = W*            First Authid              =          
+  Dataset               = WDRI.V520PGEN.SZ11.ATF.DSG00                      
>                                                                            
>  To delete this ATF Request, remove the ">" preceding the following        
>  command and press the ENTER key.  Note, if the status is EXECUTING,        
>  the ATQX command will end in error.  Use the ATQS command first to        
>  stop the trace execution.                                                  
>                                                                            
>ATQX                                

Option D
________________ ZATQS VTM O2 V530.#P SZ11 02/06/17 22:35:41 3
>       Help PF1      Back PF3      Up PF7      Down PF8       Zoom PF11      
>         Current Trace Status: INACTIVE                                      
> A-VIEW TRACE       B-VIEW DATASET     C-DELETE ENTRY     *-STOP TRACE        
> E-APPLY FILTERS                                                              
===============================================================================
>               APPLICATION TRACE QUEUE - STOP TRACE.                          
>                                                                              
 ATQV                                                                          
+  Owner                 = WDRI          State                     = Complete  
+  First Plan            = W*            First Authid              =          
+  Dataset               = WDRI.V520PGEN.SZ11.ATF.DSG00                        
>                                                                              
>  To stop this TRACE Request, remove the ">" preceding the following          
>  command and press the ENTER key.  Note, if the status is not EXECUTING,    
>  the ATQS command will fail.                                                
>                                                                              
>ATQS                              

Option E

________________ ZATQE    VTM     O2       V530.#P SZ11 02/09/17  1:00:43   2
>       Help PF1      Back PF3      Up PF7      Down PF8                      
> A-VIEW TRACE       B-VIEW DATASET     C-DELETE ENTRY     D-STOP TRACE        
> *-APPLY FILTERS                                                              
===============================================================================
>                   APPLICATION TRACE APPLY FILTERS                            
 ATRD                                                                          
+ Enter addition trace section criterion to limit trace information reported.  
+             DSN=WDRI.V520PGEN.SZ11.ATF.DSG00                                
:     PLANNAME= ________   ________   ________   ________   ________          
:       AUTHID= WDRI       ________   ________   ________   ________          
:      TSOUSER= ________  TSO UserID      |   JOBNAME= ________  Job Name      
:     CICSTRAN= ____      CICS Trans ID   |  CICSCONN= ________  CICS Conn. ID
:      PSBNAME= ________  IMS PSB Name    |     IMSID= ________  IMS Region ID
+             Press <ENTER> to add additional Filter Options  
               
Fields

DSN
The name of the VSAM dataset containing the trace output to be viewed. This is a read only field.

PLANNAME
The DB2 plan name(s) of the application threads for which data will be selected from the trace dataset.

AUTHID
The DB2 authorization identifier(s) of the application (thread) for which data will be selected.

JOBNAME
The jobname for the application thread to be selected.

CICSTRAN
The name of the CICS transaction for the threads to be selected.

CICSCONN
The connection ID of the CICS region for threads to be selected.

PSBNAME
The IMS PSB name of the threads to be selected.

IMSID
The ID of the IMS region of the threads to be selected.

Press Enter to display this panel:

________________ ZATQE    VTM     O2       V530.#P SZ11 02/09/17  1:11:41   2
>       Help PF1      Back PF3      Up PF7      Down PF8                      
> A-VIEW TRACE       B-VIEW DATASET     C-DELETE ENTRY     D-STOP TRACE        
> *-APPLY FILTERS                                                              
===============================================================================
>                   APPLICATION TRACE APPLY FILTERS                            
 ATRD                                                                          
:       STARTDATE= 02.09.17 (MM.DD.YY) STARTTIME= 00.48.31 (HH.MM.SS)          
:         ENDDATE= 02.09.17 (MM.DD.YY)   ENDTIME= 00.53.31 (HH.MM.SS)          
:           DB2ID= ____     DB2 Subsystem ID                                  
:           MVSID= ____     MVS System ID                                      
:         STATSQL= N        Static SQL?(Y/N| HOSTVARS= N    Host Variable?(Y/N)
:        INDB2TME  GT _____________   (sec)| INDB2CPU  GT _____________   (sec)
:        SQLCALLS  GT _________    SQL Call| ROWSPROC  GT _________    Row Proc
:         NUMSORT  GT _________    Sort    | LOCKSACQ  GT _________    Lock Acq
===============================================================================

Fields:

STARTDATE
The start date of the records to be selected. This field is updateable, but will be initialized with the time the trace was started.

STARTTIME
The start time of the records to be selected. This field is updateable, but will be initialized with the date the trace was started.

ENDDATE
The date after which no records will be selected. This field is updateable, and, if the trace has completed, will be initialized with the end date of the selected trace.

ENDTIME
The time after which no records will be selected. This field is updateable, and, if the trace has completed, will be initialized with the end time of the selected trace.

DB2ID
The DB2 subsystem ID for the records to be selected.

MVSID
The MVS system ID that the DB2 subsystem(s) were running on of the records to be selected.

STATSQL
Flag to indicate if static SQL text should be retrieved from the system catalog.

HOSTVARS
Flag to control if input host variable data is to be displayed. If HOSTVARS=N on the initial collection, no host variable data will be available.

There are six threshold fields on this panel. They are entered in the format:

<OP>b<VALUE>

Where <OP> is a character-based comparison operator, with GT (Greater Than) being the default.

Supported operators are:

Operator Meaning
GT Greater Than
GE Greater Than or Equal To
LT Less Than
LE Less Than or Equal To
EQ Equal To
NE Not Equal

The following filtering thresholds are supported:

INDB2TME
The DB2 Elapsed Time filtering provides the ability to display only units of work which exceed the specified filtering limits. The value is a 13-character numeric field (maximum value is 999999.999999 seconds).
Valid examples of this field are:

  • 999999
  • 999
  • 9.009
  • 0.9
  • .0009
  • .000009
  • 999.999

INDB2CPU

The DB2 CPU Time Filtering provides the ability to display only units of work which exceed the specified filtering limit. A 13 character numeric with a maximum value of 999999.999999. This field has the same format as INDB2TME.

SQLCALLS
Allows filtering on the SQL statement count to display only units of work which exceed the specified filtering limit. The value is a positive integer of 9 digits or less.

ROWSPROC
Allows filtering on the number of rows processed by the UOW to display only units of work which exceed the specified filtering limit. The value is a positive integer of 9 digits or less.

NUMSORT
Allows filtering on the number of sorts requested by the UOW to display only units of work which exceed the specified filtering limit. The value is a positive integer of 9 digits or less.

LOCKSACQ
Allows filtering on the number of locks acquired by the UIW. The value is a positive integer of 9 digits or less.

Press Enter to display a read-only summary of the filters to be applied:

________________ ZATQE    VTM     O2       V530.#P SZ11 02/09/17  1:37:41   2
>       Help PF1      Back PF3      Up PF7      Down PF8                      
> A-VIEW TRACE       B-VIEW DATASET     C-DELETE ENTRY     D-STOP TRACE        
> *-APPLY FILTERS                                                              
===============================================================================
>                   APPLICATION TRACE APPLY FILTERS                            
 ATRD                                                                          
+          DSN=WDRI.V520PGEN.SZ11.ATF.DSG00                (Required)          
+     PLANNAME=DSNESPCS ________ ________ ________ ________                    
+       AUTHID=WDRI     ________ ________ ________ ________                    
+      TSOUSER=________ TSO UserID      |  JOBNAME=________ Job Name          
+     CICSTRAN=____     CICS Trans ID   |  CICSCONN=________ CICS Conn. ID    
+      PSBNAME=________ IMS PSB Name    |    IMSID=________ IMS Region ID      
+       STARTDATE=02.09.17(MM.DD.YY)STARTTIME=00.48.31(HH.MM.SS)              
+         ENDDATE=02.09.17(MM.DD.YY)  ENDTIME=00.53.31(HH.MM.SS)              
+           DB2ID=SZ11    DB2 Subsystem ID                                    
+           MVSID=____    MVS System ID                                        
+        STATSQL=N        Static SQL?(Y/N|HOSTVARS=N   Host Variable?(Y/N)    
+       INDB2TME GT _____________  (sec) |INDB2CPU GT       .100000  (sec)    
+       SQLCALLS GT _________   SQL Call |ROWSPROC GT _________   Row Proc    
+        NUMSORT GT         5   Sort     |LOCKSACQ GT _________   Lock Acq    
===============================================================================

Press Enter to apply the filters. The following panel is displayed:

>       Help PF1      Back PF3      Up PF7      Down PF8                        
> A-VIEW TRACE       B-VIEW DATASET     C-DELETE ENTRY     D-STOP TRACE        
> *-APPLY FILTERS                                                              
===============================================================================
>                   APPLICATION TRACE APPLY FILTERS                            
 ATRD                                                                          
+                                                                              
+      Initialization successful.                                              
+      Please proceed to view dsn.                                              
===============================================================================

Select Option B to use the most recently applied filters to build reports.

Changes to the Main Menu
The main menu for ATF (Panel ZATMENU) has reinstated the options D, E, and F as standard, the “deprecated” reference has been removed.

>       Help PF1                                               Back PF3        
> A.    Current Trace Status: INACTIVE                                          
>                 Enter a selection letter on the top line.                    
===============================================================================
>                       APPLICATION TRACE FACILITY MENU                        
                                                                               
_ A  SPECIFY TRACE ...... Request and start an application trace                
_ B  VIEW TRACE ......... View the active In-memory, non-dataset trace          
_ C  STOP TRACE ......... Stop the active In-memory, non-dataset trace          
                                                                               
_ D  SELECT DATASET ..... Specify a trace dataset to view                      
_ E  VIEW DATASET ....... View the selected trace dataset                      
_ F  STOP VIEW .......... Release the selected dataset                          
                                                                               
_ G  CREATE DSN ......... Create a new VSAM LDS for trace output                
                                                                               
_ H  QUEUED Traces ...... Manage Queued VSAM Application Trace Requests  


Navigation
The following menu options are available. To select an item, enter the appropriate letter on the command line of the panel. For example, enter A to specify a trace.

A - SPECIFY TRACE

Provides a fill-in-the-blank panel to identify the application to trace. Select this option to specify or to start an active trace. You can also capture the trace output for later viewing in a dataset. For more information, see the description of panel “Specify Application Trace” on page 461.

B - VIEW TRACE

Shows an overview of the trace status and output information that is generated by the trace. This option is only available for traces that are not written to a VSAM dataset. For more information, see the description of panel “View the Active In-Memory Non-Dataset Trace” on page 466.

C - STOP TRACE

Stops the active trace of the specified application. This option is only available for traces that are not written to a VSAM dataset. For more information, see the “Stop In-Memory Non-Dataset Trace Requests” on page 467 panel.

D - SELECT DATASET

Select this option to select a data set that previously captured trace output. While this option is still supported, mostly for accessing older traces that where captured to VSAM datasets, use of option “H” is recommended for managing traces written to VSAM datasets. For more information, see the description of panel “Select Data Set and Trace Parameters” on page 468.

E - VIEW DATASET

Select this option to view the data in the selected trace data set. While this option is still supported, mostly for accessing older traces that where captured to VSAM datasets, use of option “H” is recommended for managing traces written to VSAM datasets. For more information, see the description of panel “Application Trace Thread Summary - View Dataset” on page 470.

F - STOP VIEW

Select this option to release a previously selected trace data set from OMEGAMON XE for DB2 PE. While this option is still supported, mostly for accessing older traces that where captured to VSAM datasets, use of option “H” is recommended for managing traces written to VSAM datasets For more information, see the description of panel “Stop Viewing Trace Dataset” on page 471.

G - CREATE DSN

Select this option to create a new VSAM linear data set for storing the trace output. For more information, see the description of panel “Create Application Trace Data Set Name” on page 471.

H - QUEUED TRACES

Select this option to manage the queue of application trace requests that are written to a VSAM dataset.

Note:
In the help panel, and in the documentation, the text should read:
"For traces that are managed by the ATF Queue, option H should be used instead of this function."

and not “this option is deprecated”.

STOP VIEW panel changes

Select option F from the main menu to select the STOP VIEW panel. This panel has been updated to reflect that this function is no longer deprecated.

_______________ ZATSD    VTM     O2       V530.#P SZ11 02/09/17  1:40:43   3  

>       Help PF1                                               Back PF3        
> A.F   Current Trace Status: INACTIVE                                          
> A-SPECIFY TRACE    B-VIEW TRACE       C-STOP TRACE       D-SELECT DSN        
> E-VIEW DATASET     *-STOP VIEW        G-CREATE VSAM LDS  H-QUEUED TRACES      
===============================================================================
>                          STOP VIEWING TRACE DATASET                          
                                                                               
> To release the data set from OMEGAMON, space over the > before ATSD          
> and press ENTER.                                                              
                                                                               
> This panel is available for accessing data in older trace datasets, however,  
> the recommended method to access ATF trace data written to a VSAM dataset is  
> via Option "H", QUEUED TRACES.                                                
                                                                               
>ATSD                                                                          
===============================================================================          
             
__________________________________________________________________________________

Publication number

SH12-7050-00

Copyright date

2005, 2015

Original publication date

2015/5/29

Document information

More support for: DB2 Tools for z/OS
IBM Tivoli OMEGAMON XE for DB2 PE / PM / BPA

Software version: 5.3.0

Operating system(s): z/OS

Software edition: All Editions

Reference #: 7047888

Modified date: 14 February 2017


Translate this page: