INCLUDE and EXCLUDE subcommand options

The INCLUDE and EXCLUDE subcommand options define a list of identifier values that are included or excluded.

Usage

The INCLUDE and EXCLUDE subcommand options are used to include or exclude data associated with specific OMEGAMON for Db2 PE identifiers. If you omit this subcommand option, all records are included.

Use INCLUDE to define a list of identifier values that are included in processing. Use EXCLUDE to define a list of identifier values that are excluded from processing.

Usage notes

  • You can specify list names, set names, values, or range values for each identifier. If you include some identifier values and omit EXCLUDE, only those records described in INCLUDE are processed. If you exclude some identifier values and omit INCLUDE, all records are processed except those described in EXCLUDE.
  • Use GLOBAL INCLUDE, or EXCLUDE carefully with IFCID. Because many IFCID records are paired events, BEGIN and END records are necessary to get a valid report or trace. All IFCIDs that share a common END record must be used together with INCLUDE or EXCLUDE.

Syntax

INCLUDE/EXCLUDE block
Read syntax diagramSkip visual syntax diagram INCLUDEEXCLUDE (PE_identifier(valueL( list name)G( set name)R( from_value, to_value)GT( value)LT( value)GE( value)LE( value)))

Options

The following options are available with INCLUDE and EXCLUDE:
PE_identifier
Specifies the OMEGAMON for Db2 PE identifiers that you want to include in, or exclude from, your output. Identifiers valid for each report are listed in this section. Definitions of identifiers are described in OMEGAMON for Db2 PE identifiers.

If you do not specify an identifier when using the REDUCE, REPORT, TRACE, or FILE subcommand, OMEGAMON for Db2 PE uses the identifiers specified for GLOBAL INCLUDE or EXCLUDE.

You can use an OMEGAMON for Db2 PE identifier in either INCLUDE or EXCLUDE, but not with both in the same command or subcommand.

value
A value for the specified OMEGAMON for Db2 PE identifier, or an asterisk (*) indicating all values.

Identifier values must consist of the following characters: A — Z, #, $, @, >, <, or 0 — 9. If the value you want to include contains a character that is not in this list, use an asterisk in its place.

L
The name of a list containing values for the specified OMEGAMON for Db2 PE identifier. The list name must be defined by a LIST command in the same job step.
G
The name of a set of values for the selected OMEGAMON for Db2 PE identifier. The set name must be defined by a GROUP command in the same job step.
If a set name is specified in a value block, only that set is processed. If you want all identifier values that are not contained in any set specification to be reduced and reported individually, enter an asterisk (*) in the INCLUDE or EXCLUDE options following the last set name. For example: 
⋮
INCLUDE (
PRIMAUTH (G(AUTHGRP1)
	     G(AUTHGRP2)
	     *))
⋮
This indicates that the authorization IDs contained in the sets AUTHGRP1 and AUTHGRP2 are processed as sets, and all other authorization IDs are processed individually.
R
Denotes a range of values beginning with from_value and ending with to_value. The from_value must be less than to_value. The generic form can be used only in the last character position in range values. For example, R(AUTH1*,AUTH2*) is acceptable, but R(AUTH*1,AUTH*2) is not.
GT
Denotes values greater than the given value.

This is only valid for SQLCODE.

LT
Denotes values less than the given value.

This is only valid for SQLCODE.

GE
Denotes values equal to, or greater than the given value.

This is only valid for SQLCODE.

LE
Denotes values equal to, or less than the given value.

This is only valid for SQLCODE.

Rules

The following table shows which OMEGAMON for Db2 PE identifiers can be used with the different commands and subcommands.

Table 1. OMEGAMON for Db2 PE identifiers used with INCLUDE and EXCLUDE subcommand option
OMEGAMON for Db2 PE identifier ACCT AUD I/O LOCK RT SQL STAT UTIL
ACE (Agent control element address)         t,f t,p    
CLASS (Db2 trace class)         t,f      
CONNECT (Connection ID) r,t,p,f r,t,p,f r,p r,t,p,f t,f t,p   r,t,p
CONNTYPE (Connection type) r,t,p,f r,t,p,f r,p r,t,p,f t,f t,p   r,t,p
CORRNAME (Correlation name) r,t,p,f r,t,p,f r,p r,t,p,f t,f t,p   r,t,p
CORRNMBR (Correlation number) r,t,p,f r,t,p,f r,p r,t,p,f t,f t,p   r,t,p
DATABASE (Database name)     r,p r,t,p,f        
DATASET (Data set name)     r,p          
ENDUSER (End user ID) r,t,p,f r,t,p,f   r,t,p,f t,f t,p    
FIELD (Comparison with data in a record field)         t,f      
GROUP (Group name) r,t,p,f r,t,p,f r,p r,t,p,f t,f t,p r,t,p,f r,t,p
IFCID (Instrumentation Facility Component Identifier)         t,f t,p    
INSTANCE (Instance number) r,t,f r,t,p,f   t,f t,f t,p   r,t,p
LOCATION (Location name) r,t,p,f r,t,p,f r,p r,t,p,f t,f t,p r,t,p,f r,t,p
MAINPACK (Main package) r,t,p,f              
MEMBER (Member name) r,t,p,f r,t,p,f r,p r,t,p,f t,f t,p r,t,p,f r,t,p
ORIGAUTH (Original authorization ID) r,t,p,f r,t,p,f r,p r,t,p,f t,f t,p   r,t,p
PACKAGE (Package information) or PROGRAM (Program information) r,t,p,f              
PAGESET (Page set name)     r,p r,t,p,f        
PLANNAME (Plan name) r,t,p,f r,t,p,f r,p r,t,p,f t,f t,p   r,t,p
PRIMAUTH (Primary authorization ID) or AUTHID (Authorization ID) r,t,p,f r,t,p,f r,p r,t,p,f t,f t,p   r,t,p
REQLOC (Requester location) r,t,p,f r,t,p,f r,p r,t,p,f t,f t,p   r,t,p
RESOURCETYPE (Resource type)       r,t,p,f        
RMID (Resource manager identifier)         t,f      
SQLCODE         t,f t    
SUBSYSTEMID (Subsystem ID) r,t,p,f r,t,p,f r,p r,t,p,f t,f t,p r,t,p,f r,t,p
THREADTYPE (Thread type) r,t,p,f r,t,p,f r,p r,t,p,f t,f t,p   r,t,p
TRANSACT (End user transaction name) r,t,p,f t,p,f r,p t,f t,f      
TYPE (Event type)       r,t,f        
WSNAME (End user workstation name) r,t,p,f t,p,f   r,t,p,f t,f t,p    
Note:
  1. The use of PLANNAME as a filter for Accounting reports in a DDF environment can cause unexpected results. See Special considerations for DDF trace data.
  2. The commands are abbreviated as follows: ACCT (ACCOUNTING), AUD (AUDIT), I/O (IOACTIVITY), LOCK (LOCKING), RT (RECTRACE), SQL (SQLACTIVITY), STAT (STATISTICS), and UTIL (UTILITY).
  3. Subcommands are abbreviated as r (REDUCE), t (TRACE), p (REPORT), and f (FILE), whereas all applies to all subcommands.

Considerations when using the DATABASE, PACKAGE, PROGRAM, PAGESET, or RESOURCETYPE identifier

If you use the INCLUDE or EXCLUDE subcommand option with one of these OMEGAMON for Db2 PE identifiers, note that the scope of these identifiers affects only the relevant parts of trace records, but not the entire trace records. This means that all records are processed, but only the parts of the records specified by one of the identifiers are included in or excluded from processing. Consequently, remaining record information (specifically included or not excluded) from all trace records is shown in the resulting reports.

Example: INCLUDE/EXCLUDE with PACKAGE

As an example, take Accounting trace records that might contain information about packages P1, P2, and P3:
  • If you specify INCLUDE PACKAGE(P1), information about packages other than P1 is filtered from each trace record. All trace records (possibly containing information about package P1) are considered for report processing. If you specify INCLUDE PACKAGE(Px), where Px is an identifier that is not included in any trace record, the resulting report shows no package information, but all remaining information.
  • If you specify EXCLUDE PACKAGE(P1), information about package P1 is filtered from each trace record. All trace records (possibly containing information about packages other than P1) are considered for report processing. If you specify EXCLUDE PACKAGE(Px), where Px is an identifier that is not included in any trace record, the resulting report shows package information, if they exist in the trace records.

With these identifiers, specified parts of the trace records are included, respectively excluded. The trace records themselves, with the remaining parts, pass the filter. Consequently, this information is shown in the resulting reports.

Example: INCLUDE and EXCLUDE: Specifying plan and primary authorization ID

The following example produces an Accounting long report. The only plan reported is QMF311. All primary authorization IDs are reported except those on the list called PRODUSER.

⋮
LIST (PRIMAUTH(PRODUSER(USER1,USER2)))
ACCOUNTING
   REDUCE
   REPORT
      LAYOUT	(LONG)
      INCLUDE (PLAN(QMF311))
      EXCLUDE (PRIMAUTH(L(PRODUSER)))
⋮