Add PEX Filter (ADDPEXFTR)

Where allowed to run: All environments (*ALL)
Threadsafe: Conditional
Parameters
Examples
Error messages

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

Parameters

Keyword Description Choices Notes
FTR Filter Name Required, Positional 1
PGMTRG Program trigger Element list Optional
Element 1: Program Qualified object name
Qualifier 1: Program Name
Qualifier 2: Library Name
Element 2: Module Name, *ALL
Element 3: Procedure Character value, *PEP, *ALL
Element 4: Type *PGM, *SRVPGM
Element 5: Trigger option *ENTRYEXIT, *ENTRY, *ENTRYEXITNOPGM, *ENTRYNOPGM
JVATRG Java trigger Element list Optional
Element 1: Java package Character value, *NONE
Element 2: Java class Character value, *ALL
Element 3: Java method Character value, *ALL
Element 4: Trigger option *ENTRYEXIT, *ENTRY, *ENTRYEXITNOPGM, *ENTRYNOPGM
PGMFTR Program filter Element list Optional
Element 1: Relational operator *EQ, *NE
Element 2: Values (up to 16 repetitions): Element list
Element 1: Program Qualified object name
Qualifier 1: Program Name, *ALL
Qualifier 2: Library Name
Element 2: Module Name, *ALL
Element 3: Procedure Character value, *ALL
Element 4: Type *PGM, *SRVPGM
JVAFTR Java method filter Element list Optional
Element 1: Relational operator *EQ, *NE
Element 2: Values (up to 5 repetitions): Element list
Element 1: Java package Character value, *NONE
Element 2: Java class Character value, *ALL
Element 3: Java method Character value, *ALL
JVACLSFTR Java class filter Element list Optional
Element 1: Relational operator *EQ, *NE
Element 2: Values (up to 5 repetitions): Element list
Element 1: Java package Character value, *NONE
Element 2: Java class Character value, *ALL
Element 3: Array Character value, *NOARRAY, *CLASSARRAY, *VOIDARRAY, *BOOLEANARRAY, *CHARARRAY, *FLOATARRAY, *DOUBLEARRAY, *BYTEARRAY, *SHORTARRAY, *INTARRAY, *LONGARRAY
OBJFTR Object filter Element list Optional
Element 1: Relational operator *EQ, *NE
Element 2: Values (up to 5 repetitions): Element list
Element 1: Object Qualified object name
Qualifier 1: Object Name, *ALL
Qualifier 2: Library Name
Element 2: Member, if data base file Name
Element 3: Object type *DTAARA, *DTAQ, *FILE, *FLR, *JRN, *JRNRCV, *LIB, *MSGQ, *PGM, *SRVPGM, *USRPRF, *USRIDX, *USRQ, *USRSPC
PATHFTR Path filter Element list Optional
Element 1: Relational operator *EQ, *NE
Element 2: Path Values (up to 5 repetitions): Path name
MEMFTR Memory filter Element list Optional
Element 1: Relational operator *EQ, *NE
Element 2: Pool identifier Values (up to 5 repetitions): 1-64
DSKFTR Disk filter Element list Optional
Element 1: Relational operator *EQ, *NE
Element 2: Disk identifier Values (up to 5 repetitions): Integer
ASPFTR ASP filter Element list Optional
Element 1: Relational operator *EQ, *NE
Element 2: ASP identifier Values (up to 5 repetitions): Integer
IPFTR IP filter Element list Optional
Element 1: Relational operator *EQ, *NE
Element 2: Values (up to 5 repetitions): Element list
Element 1: Address family 1-255, *INET, *INET6, *UNIX
Element 2: Communication type 1-255, *STREAM, *DGRAM, *RAW, *SEQPACKET
Element 3: Local internet address Character value, *ALL
Element 4: Remote internet address Character value, *ALL
Element 5: Local port 1-65535, *ALL
Element 6: Remote port 1-65535, *ALL
USRDFNFTR User defined filter Values (up to 10 repetitions): Element list Optional
Element 1: Relational operator *EQ, *NE, *LT, *GT
Element 2: Event type 1-31
Element 3: Event subtype 1-31
Element 4: Data offset Integer
Element 5: Data type *CHAR, *HEX, *INT1, *INT2, *INT4, *INT8, *UINT1, *UINT2, *UINT4, *UINT8
Element 6: Compare value Values (up to 5 repetitions): Character value
Element 7: Trigger option 0-8, *NONE, *START, *END, *COLLSTART, *COLLEND
TEXT Text 'description' Character value, *BLANK Optional
Top

Filter (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.

This is a required parameter.

filter-name
Specify the name of the new Performance Explorer filter.
Top

Program trigger (PGMTRG)

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

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

The *MIENTRY/*MIEXIT events are enabled in procedures that are compiled with the ENBPFRCOL parameter set to *PEP, *FULL, or *ENTRYEXIT.

Element 1: Program

Qualifier 1: Program

program-name
Specify the name of the trigger program.

Qualifier 2: Library

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

Element 2: Module

*ALL
All modules in the specified program will act as the trigger.
module-name
Specify the module within the program or service program that contains the procedure that is to be the trigger. This is required only for ILE programs and service programs.

Element 3: Procedure

*PEP
The program entry procedure will act as the trigger. This is not valid for programs of type *SRVPGM.
*ALL
All procedures in the specified module will act as the trigger.
'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: 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 Performance Explorer session.
*ENTRYEXITNOPGM
The specified trigger procedure enables the collection of events (except program events) at procedure entry time. At procedure exit, the collection of events is disabled. This option is not valid for STATS mode.
*ENTRYNOPGM
The specified trigger procedure enables the collection of events (except program events) at procedure entry time. The collection of events is enabled for the duration of the Performance Explorer session. This option is not valid for STATS mode.
Top

Java trigger (JVATRG)

If a Java method entry event (*JVAENTRY) occurs that matches this trigger specification, then Performance Explorer will begin collecting all events specified in the Performance Explorer definition used for the active Performance Explorer session. The events will be collected only for the thread where the trigger occurs. When the Java method exit event (*JVAEXIT) occurs that matches the trigger specification, Performance Explorer will stop collecting the events specified in the Performance Explorer definition.

The *JVAENTRY and *JVAEXIT hooks are always enabled in interpreted Java. You can also enable these hooks when running in JIT mode by specifying the property 'os400.enbpfrcol=1'.

For code compiled for direct execution, specify ENBPFRCOL(*ENTRYEXIT) on the Create Java Program (CRTJVAPGM) CL command.

Element 1: Java package

package-name
Specify the name of the Java package that contains the method to use as the trigger.

Element 2: Java class

class-name
Specify a class within the package that contains the method to use as the trigger.

Element 3: Java method

method-name
Specify a method to use as the trigger.

Element 4: Trigger option

*ENTRYEXIT
The specified trigger method enables the collection of events at Java method entry time. At Java method exit, the collection of events is disabled.
*ENTRY
The specified trigger method enables the collection of events at Java method entry time. The collection of events is enabled for the duration of the Performance Explorer session.
*ENTRYEXITNOPGM
The specified trigger method enables the collection of events (except program events) at method entry time. At method exit, the collection of events is disabled. This option is not valid for STATS mode.
*ENTRYNOPGM
The specified trigger method enables the collection of events (except program events) at method entry time. The collection of events is enabled for the duration of the Performance Explorer session. This option is not valid for STATS mode.
Top

Program filter (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 Performance Explorer.
*NE
Events having program data that matches the specified program are excluded from the data collected by Performance Explorer. These events will not show up in the *MGTCOL object or the Performance Explorer database.

Element 2: Filter entry

Specify the elements for each filter entry.

Element 1: Program

Qualifier 1: Program

program-name
Specify the name of the program to be used as a compare value for the program filter.
*ALL
All programs in the specified library will pass the filter.

Qualifier 2: Library

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

Element 2: Module

*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. This is required only for ILE programs and service programs.

Element 3: Procedure

*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 4: 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.
Top

Java method filter (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 Performance Explorer.
*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 Performance Explorer database.

Element 2: Filter entry

Specify the elements for each filter entry.

Element 1: Java package

*NONE
The Java class and methods are not in a package.
package-name
Specify the name of the Java package to be used as a compare value for the filter.

Element 2: Java class

*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 3: Java method

*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.
Top

Java class filter (JVACLSFTR)

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

Element 1: Relational operator

*EQ
Events having Java data that match the specified packages and classes are included in the data collected by Performance Explorer.
*NE
Events having Java data that matches the specified packages and classes are excluded from the collection and will not show up in the *MGTCOL object or the Performance Explorer database.

Element 2: Filter entry

Specify the elements for each filter entry.

Element 1: Java package

*NONE
The Java classes are not in a package.
package-name
Specify the name of the Java package to be used as a compare value for the filter.

Element 2: Java class

*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 3: Array

*NOARRAY
The specified class is not an array of classes.
*CLASSARRAY
The specified class is an array of classes.
*VOIDARRAY
The array of void primitive class is to be used as a compare value for the filter.
*BOOLEANARRAY
The array of boolean primitive class is to be used as a compare value for the filter.
*CHARARRAY
The array of char primitive class is to be used as a compare value for the filter.
*FLOATARRAY
The array of float primitive class is to be used as a compare value for the filter.
*DOUBLEARRAY
The array of double primitive class is to be used as a compare value for the filter.
*BYTEARRAY
The array of byte primitive class is to be used as a compare value for the filter.
*SHORTARRAY
The array of short primitive class is to be used as a compare value for the filter.
*INTARRAY
The array of int primitive class is to be used as a compare value for the filter.
*LONGARRAY
The array of long primitive class is to be used as a compare value for the filter.
Top

Object filter (OBJFTR)

Specifies the object comparisons to use for this filter.

Element 1: Relational operator

*EQ
Events whose object name, library name, member (if a file) and object type matches this specification will be included in the collected trace data.
*NE
Events whose object name, library name, member (if a file) and object type matches this specification will be excluded from the collected trace data. These events will not show up in the *MGTCOL object or the Performance Explorer database.

Element 2: Filter entry

Specify the elements for each filter entry.

Element 1: Object

Qualifier 1: Object

object-name
The name of the object to be used as a compare value in the object filter.
*ALL
All objects in the specified library will pass the filter. Object type must be blank if *ALL is specified for the object.

Qualifier 2: Library

library-name
The library which contains the object to use as a compare value.

Element 2: Member, if data base file

member-name
The member name to use as the compare value. This value is valid for physical or logical *FILE objects only. Specify *N for other objects.

Element 3: Object type

*DTAARA
The specified object is a data area.
*DTAQ
The specified object is a data queue.
*FILE
The specified object is a physical or logical database file.
*FLR
The specified object is a folder.
*JRN
The specified object is a journal.
*JRNRCV
The specified object is a journal receiver.
*LIB
The specified object is a library. Note: this filters on the library object only, not on the objects contained in the library. Use an object name of *ALL to filter on all objects contained in a library.
*MSGQ
The specified object is a message queue.
*PGM
The specified object is a program.
*SRVPGM
The specified object is a service program.
*USRPRF
The specified object is a user profile.
*USRIDX
The specified object is a user index.
*USRSPC
The specified object is a user space.
*USRQ
The specified object is a user queue.
Top

Path filter (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 Performance Explorer.
*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 Performance Explorer database.

Element 2: Path

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

Memory 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 Performance Explorer.
*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 Performance Explorer 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.
Top

Disk filter (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 Performance Explorer.
*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 Performance Explorer 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.
Top

ASP filter (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 Performance Explorer.
*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 Performance Explorer 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.
Top

IP filter (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 Performance Explorer.
*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 Performance Explorer database.

Element 2: Filter entry

Specify the elements for each filter entry.

Element 1: 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 2: 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 3: Local internet 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 4: Remote internet 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 5: Local port

*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 6: Remote port

*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.
Top

User defined filter (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 Performance Explorer 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 zeros. 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.

Element 7: Trigger option

*NONE
The information in this filter is not used as a trigger.
*START
If an event occurs that meets the criteria in the filter information, subsequent events will be stored to the database. Previous to this, no events will be recorded. This option can be used to start collecting events once a certain condition has occurred. This option affects only the task or process where the trigger event occured.
*END
If an event occurs that meets the criteria in the filter information, subsequent events will not be stored to the database. This can be used to stop collecting data once a certain condition has occurred. This option affects only the task or process where the trigger event occured.
*COLLSTART
If an event occurs that meets the criteria in the filter information, subsequent events will be stored to the database. Previous to this, no events will be recorded. This option can be used to start collecting events once a certain condition has occurred. This option affects all tasks and processes in the collection.
*COLLEND
If an event occurs that meets the criteria in the filter information, subsequent events will not be stored to the database. This can be used to stop collecting data once a certain condition has occurred. This option affects all tasks and processes in the collection.
Top

Text 'description' (TEXT)

Specifies the text that briefly describes the Performance Explorer definition.

*BLANK
Text is not specified.
'description'
Specify no more than 50 characters of text, enclosed in apostrophes.
Top

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

Top

Error messages

*ESCAPE Messages

CPFAF10
Definition or filter already exists.
Top