CL Command Reference - ADDPEXFTR
CL Command List > ADDPEXFTR Reference
Description:
The Add Performance Explorer Filter (ADDPEXFTR) command adds a new Performance Explorer (PEX) filter to the system. Each filter is stored as a member in the QAPEXFTR file in library QUSRSYS. A Performance Explorer filter identifies the performance data that is to be collected during a Performance Explorer session, and is meant to limit the amount of data collected by specifying a compare value for specific events. If the data in the event matches the compare value, then the data will be collected. If not, the data is discarded. The filter is specified on the STRPEX (Start Performance Explorer) command.
Restrictions:
1. This command is shipped with public *EXCLUDE authority.
2. To use this command you must have *SERVICE special authority, or be authorized to the Service Trace function of i5/OS through iSeries Navigator¡¯s Application Administration support. The Change Function Usage Information (QSYCHFUI) API, with a function ID of QIBM_SERVICE_TRACE, can also be used to change the list of users that are allowed to perform trace operations.
3. You must have *EXECUTE authority to the libraries for PGMTRG, PGMFTR, OBJFTR, and *X authority to the directories for JVATRG, JVAFTR, JVACLSFTR, and PATHFTR if these parameters are specified.
4. The following user profiles have private authorities to use the command:
. QPGMR
. QSRV
5. Two threads within the same job will not be allowed to run ADDPEXFTR at the same time. The thread that issued ADDPEXFTR first will run the command to completion while the second ADDPEXFTR waits.
Examples:
Example 1: Adding Disk and Memory Pool Filters
ADDPEXFTR FTR(FILTER1) DSKFTR(*EQ (1 2)) MEMFTR(*EQ 3)
This command adds a new performance explorer filter named FILTER1 which will result in a member named FILTER1 being added to file QAPEXFTR in library QUSRSYS. If this filter is used when starting a performance explorer session (STRPEX command), then events will be collected if they contain disk device identifier data of ¡¯1¡¯ or ¡¯2¡¯. In addition, the pool data for that event must contain ¡¯3¡¯. If either the disk data or the memory pool data do not match the specified filter, then that event will not be recorded.
If an event does not contain disk device or memory pool data, then the filter does not apply to that event and those events will be collected. For example, the base event *TASKSWTIN does not contain any disk or memory pool data, so this event would still be collected.
Example 2: Adding a Disk Filter
ADDPEXFTR FTR(DISKFILTER) DSKFTR(*NE (1 2))
This command adds a new performance explorer filter named DISKFILTER. If this filter is used when starting a performance explorer session (STRPEX command), then events will be collected if the event contains disk device name data that does not match ¡¯1¡¯ and does not match ¡¯2¡¯.
If an event does not contain disk device name data, then the filter does not apply to that event and those events will be collected. For example, the base event *TASKSWTIN does not contain any disk data, so this event would still be collected.
Example 3: Adding an IP Filter
ADDPEXFTR FTR(IPFILTER)
IPFTR(*EQ (*INET *STREAM ¡¯1.2.3.4¡¯))
This command adds a new performance explorer filter named IPFILTER. If this filter is used when starting a performance explorer session (STRPEX command), then events will be collected if a communications event has an address family of *INET, the communication type is *STREAM, and the local IP address is ¡¯1.2.3.4¡¯.
Example 4: Adding a User-Defined Filter
ADDPEXFTR FTR(USERFILTER)
USRDFNFTR((*EQ 1 2 20 *CHAR (¡¯BOB¡¯ ¡¯SAM¡¯)))
This command adds a new performance explorer filter named USERFILTER. If this filter is used when starting a performance explorer session (STRPEX command), then events will be collected if the event type is ¡¯1¡¯, the event subtype is ¡¯2¡¯ and the data at offset 20 is either ¡¯BOB¡¯ or ¡¯SAM¡¯.