ADDPEXFTR (Add Performance Explorer Filter)

ADDPEXFTR Command syntax diagram

 

Purpose

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 have *SERVICE special authority, or be authorized to the Service Trace function of Operating System/400 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, and *X authority to the directories for JVAFTR, and PATHFTR if these parameters are specified.
4. The following user profiles have private authorities to use the command:
   
   

• QPGMR
  
  
• QSRV
  
  

 

Required Parameters

FTR

Specifies the name of the performance explorer filter to be added. If the specified filter already exists in the QAPEXFTR file in library QUSRSYS, an error condition will occur. The user can either change the filter name or remove the existing filter using the Remove Performance Explorer Filter (RMVPEXFTR) command, and try this command again.

filter-name: Specify the name of the new performance explorer filter.

 

Optional Parameters

PGMTRG

If a procedure entry event (*PRCENTRY) occurs that matches this trigger specification, then PEX will begin collecting all events specified in the PEX definition used for the active PEX session. The events will be collected only for the thread where the trigger occurs. When the procedure exit event (*PRCEXIT) occurs that matches the trigger specification, PEX will stop collecting the events specified in the PEX definition.

If the *PRCENTRY/*PRCEXIT events are not specified in the PEX definition, this trigger will still function correctly. However, you will not see any *PRCENTRY/*PRCEXIT events in your data. If you have specified *PRCENTRY/*PRCEXIT events in your PEX definition, you will see those events in your data only after this trigger has been activated due to the trigger procedure being called.

The *PRCENTRY/*PRCEXIT events are enabled in procedures that are compiled at optimization level 30 and under. For optimization level 40, procedures have these events enabled if the LICOPT on CHGPGM has been set to 'CallTracingAtHighOpt' and the procedure stacks a frame on the invocation stack when called (non-leaf procedures).

Element 1: Program Name

The program name can be qualified by one of the following library values:

*LIBL: The library list of the job that issues the ADDPEXFTR command is searched to find the specified program or service program.

library-name: Specify the library which contains the program or service program.

program-name: Specify the name of the trigger program.

Element 2: Module Name

module-name: Specify the module within the program or service program that contains the procedure that is to be the trigger.

Element 3: Procedure Name

*PEP: The program entry procedure will act as the trigger. This is not valid for programs of type *SRVPGM.

procedure-name: Specify a specific procedure within the specified module that is to be the trigger. Specify the procedure name within single quotes if the procedure name contains lower case characters.

Element 4: Program Type

Indicate the type of program being specified.

*PGM: The program being specified is a program (*PGM) object.

*SRVPGM: The program being specified is a service program (*SRVPGM) object.

Element 5: Trigger Option

*ENTRYEXIT: The specified trigger procedure enables the collection of events at procedure entry time. At procedure exit, the collection of events is disabled.

*ENTRY: The specified trigger procedure enables the collection of events at procedure entry time. The collection of events is enabled for the duration of the PEX session.

PGMFTR

Specifies the program comparisons to use for this filter.

Element 1: Relational Operator

*EQ: Events having program data that matches the specified program are included in the data collected by PEX.

*NE: Events having program data that matches the specified program are excluded from the data collected by PEX. These events will not show up in the *MGTCOL object or the PEX database.

Element 2: Program Name

The program name can be qualified by one of the following library values:

*LIBL: The library list of the job that issues the ADDPEXFTR command is searched to find the specified program or service program.

library-name: Specify the library which contains the program or service program.

*ALL: All programs in the specified library will pass the program filter.

program-name: Specify the name of the program to be used as a compare value for the program filter.

Element 3: Module Name

*ALL: All modules in the program or service program will pass the filter. If filtering an OPM (Original Program Model), specify *ALL for this element.

module-name: Specify a specific module within the program or service program to be used as a compare value for the program filter.

Element 4: Procedure Name

*ALL: All procedures in the specified module are used as a compare value for the program filter.

procedure-name: Specify a procedure to use as the filter compare value. Specify the procedure name within single quotes if the procedure name contains lower case characters.

Element 5: Program Type

Indicate the type of program being specified.

*PGM: The program being specified is a program (*PGM) object.

*SRVPGM: The program being specified is a service program (*SRVPGM) object.

JVAFTR

Specifies the Java package, class, and methods to be used as compare values for the Java filter.

Element 1: Relational Operator

*EQ: Events having Java data that match the specified packages,classes, and methods are included in the data collected by PEX.

*NE: Events having Java data that matches the specified packages, classes, and methods are excluded from the collection and will not show up in the *MGTCOL object or the PEX database.

Element 2: Package Name

package-name: Specify the name of the Java package to be used as a compare value for the filter.

Element 3: Class Name

*ALL: All classes in the specified package will pass the Java filter.

class-name: Specify a class within the package to be used as a compare value for the filter.

Element 4: Method Name

*ALL: All methods in the specified class and package will pass the filter.

method-name: Specify a method to use as the filter compare value.

PATHFTR

Specifies the Integrated File System object path name comparisons to use for this filter.

Element 1: Relational Operator

*EQ: All events that have an object path that matches the specified object path are included in the data collected by PEX.

*NE: All events that have an object path data that matches the specified object path are discarded. These events will not show up in the *MGTCOL object or the PEX database.

Element 2: Path Identifier

object-path: The object path to use as a compare value for this filter.

MEMFTR

Specifies the memory pool comparisons to use for this filter.

Element 1: Relational Operator

*EQ: All events that have pool identifier data that matches the specified pool are included in the data collected by PEX.

*NE: All events that have pool identifier data that matches the specified pool are discarded. These events will not show up in the *MGTCOL object or the PEX database.

Element 2: Pool Identifier

pool-identifier The system pool id to use as a compare value for this filter. This pool ID corresponds to the pool identifier as shown on the WRKACTJOB command or on the output of PRTPEXRPT of type *TRACE.

DSKFTR

Specifies the disk unit comparisons to use for this filter.

Element 1: Relational Operator

*EQ: All events that have disk identifier data that matches the specified disk are included in the data collected by PEX.

*NE: All events that have disk identifier data that matches the specified disk will be discarded. These events will not show up in the *MGTCOL object or the PEX database.

Element 2: Disk Identifier

disk-identifier: The disk identifier used as a compare value for this filter. This disk identifier corresponds to the disk unit as shown on the WRKDSKSTS command or the output of PRTPEXRPT of type *TRACE. If a disk is mirrored, this identifier applies to both disks in the mirrored pair.

ASPFTR

Specifies the ASP (auxiliary storage pool) comparisons to use for this filter.

Element 1: Relational Operator

*EQ: All events with an ASP identifier that matches the specified ASP will be included in the data collected by PEX.

*NE: All events with an ASP identifier that matches the specified ASP will discarded. These events will not show up in the *MGTCOL object or the PEX database.

Element 2: ASP Identifier

ASP-identifier: The ASP identifier to use as a compare value for this filter. This ASP identifier can be set to the name of an independent ASP or to the ASP number that corresponds to the ASP value as shown on the WRKDSKSTS command or in the output of PRTPEXRPT of type *TRACE.

IPFTR

Specifies the IP (internet protocol) information to use as a compare value for this filter.

Element 1: Relational Operator

*EQ: All events with IP data that match the filter compare values will be included in the data collected by PEX.

*NE: All events with IP data that match the filter compare values will be discarded. These events will not show up in the *MGTCOL object or the PEX database.

Element 2: Address Family

*INET: The Internet protocol will be used as part of the compare value.

*INET6: The Internet protocol version 6 will be used as part of the compare value.

*UNIX: The Unix protocol will be used as part of the compare value.

Element 3: Communication Type

*ALL: All communication types will pass this part of the IP filter.

*STREAM: A communication type of SOCK_STREAM will be used as the compare value.

*DGRAM: A communication type of SOCK_DGRAM will be used as the compare value.

*RAW: A communication type of SOCK_RAW will be used as the compare value.

*SEQPACKET: A communication type of SOCK_SEQPACKET will be used as the compare value.

Element 4: Local IP Address

*ALL: All local IP addresses will pass this part of the IP filter.

local-IP-address: The local IP address to be used as part of the IP compare value.

Element 5: Remote IP Address

*ALL: All remote IP addresses will pass this part of the IP filter.

remote-IP-address: The remote IP address to used as part of the IP compare value.

Element 6: Local Port Number

*ALL: All local ports for the specified local address will pass this part of the IP filter.

local-port: The local port number to be used as a compare value.

Element 7: Remote Port Number

*ALL: All remote ports for the specified address will pass this part of the IP filter.

remote-port: The remote port number to be used as the compare value.

USRDFNFTR

Specifies user defined comparisons to use for this filter. This type of filter will require help from IBM service.

Element 1: Relational Operator

*EQ: All events for the specified user filter will be collected if the event data matches the compare value.

*NE: All events for the specified user filter will be discarded if the event data matches the compare value. These events will not show up in the *MGTCOL object or the PEX database.

*GT: All events for the specified user filter will be collected if the event data is greater than the compare value.

*LT: All events for the specified user filter will be collected if the event data is less than the compare value.

Element 2: Event Type

event-type: The event type (1-31) for the event to filter.

Element 3: Event Subtype

event-subtype: The event subtype (1-31) for the event to filter.

Element 4: Data Offset

data-offset: The offset into the event data to be compared against the compare value.

Element 5: Data Type Specifies how to compare the event data to the compare value.

*CHAR: Compare as two character strings, left adjusted and padded on the right with blanks. The maximum length is 30 bytes.

*HEX: Compare as hexadecimal strings, left adjusted and padded on the right with hexadecimal zeroes. The maximum length is 30 hexadecimal digits.

*INT1: The first byte of event data at the specified data offset and the compare value are compared as a signed 1-byte integers.

*INT2: The first two bytes of event data at the specified data offset and the compare value are compared as signed 2-byte integers.

*INT4: The first four bytes of event data at the specified data offset and the compare value are compared as signed 4-byte integers.

*INT8: The first eight bytes of event data at the specified data offset and the compare value are compared as signed 8-byte integers.

*UINT1: The first byte of event data at the specified data offset and the compare value are compared as a unsigned 1-byte integers.

*UINT2: The first two bytes of event data at the specified data offset and the compare value are compared as unsigned 2-byte integers.

*UINT4: The first four bytes of event data at the specified data offset and the compare value are compared as unsigned 4-byte integers.

*UINT8: The first eight bytes of event data at the specified data offset and the compare value are compared as unsigned 8-byte integers.

Element 6: Compare Value

compare-value: The value used to compare against the event data. Up to five compare values can be specified. If multiple values are specified, the comparison will be made with each compare value. If any comparison is true, the event will be filtered.

TEXT

Specifies the text that briefly describes the performance explorer filter More information on this parameter is in Commonly used parameters.

*BLANK: Text is not specified.

'description': Specify no more than 50 characters of text, enclosed in apostrophes.

Examples for ADDPEXFTR

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'.

Error messages for ADDPEXFTR

*ESCAPE Messages