Add Trace Filter (ADDTRCFTR)

The Add Trace Filter (ADDTRCFTR) command adds a new trace filter to the system. A trace filter identifies the trace flow (call/return) data that is to be collected during a trace session, and is meant to limit the amount of data collected by specifying a compare value. If the data in the trace record matches the compare value, then the data will be collected. If not, the data is discarded. The filter is specified on the STRTRC (Start Trace) command.

Restrictions:

You must have service (*SERVICE) special authority, or be authorized to the Service trace function of Operating System through iSeries Navigator's Application Administration support. The Change Function Usage (CHGFCNUSG) command, 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.

Parameters

Keyword	Description	Choices	Notes
FTR	Filter	Name	Required, Positional 1
PGMTRG	Program trigger	Element list	Optional
	Element 1: Filter entry	Qualified object name
	Qualifier 1: Filter entry	Name
	Qualifier 2: Library	Name, *LIBL
	Element 2: Module	Name
	Element 3: Procedure	Character value
	Element 4: Type	PGM, SRVPGM
	Element 5: Trigger option	ENTRYEXIT, ENTRY
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: Filter entry	Qualified object name
	Qualifier 1: Filter entry	Name
	Qualifier 2: Library	Name, *LIBL
	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
	Element 2: Java class	Character value, *ALL
	Element 3: Java method	Character value, *ALL

Top

Program trigger (PGMTRG)

If a procedure is called that matches this trigger specification, then STRTRC will begin collecting flow trace records for this STRTRC session. The flow trace records will be collected only for the thread where the trigger occurs.

When the procedure returns and it matches the trigger specification, STRTRC will stop collecting the flow trace records.

Element 1: Filter entry

Qualifier 1: Filter entry

name: Specify the name of the program which, if called, will cause trace flow records to start being collected.

Qualifier 2: Library

*LIBL: The library list of the job that issues the STRTRC command is searched to find the specified program or service program.
name: Specify the name of the library which contains the program or service program.

Element 2: Module

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

Element 3: Procedure

character-value: Specify the name of 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

*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 flow trace records at procedure entry time. At procedure exit, the collection of flow trace records is disabled.
*ENTRY: The specified trigger procedure enables the collection of flow trace records at procedure entry time. The collection of flow trace records continues for the duration of the trace session.

Java trigger (JVATRG)

If a Java method entry event (*JVAENTRY) occurs that matches this trigger specification, then STRTRC will begin collecting all events for this STRTRC 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, STRTRC will stop collecting the events.

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 STRTRC 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 STRTRC session. This option is not valid for STATS mode.

Program filter (PGMFTR)

Specifies the program comparisons to use for this filter.

Element 1: Relational operator

*EQ: Flow trace records having program data that matches the specified program are included in the data collected.
*NE: Flow trace records having program data that matches the specified program are excluded from the data collected. These trace records will not show up.

Element 2:

You can specify up to 16 values for this element set.

Element 1: Filter entry

Qualifier 1: Filter entry

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

Qualifier 2: Library

*LIBL: The library list of the job that issues the STRTRC command is searched to find the specified program or service program.
name: Specify the name of 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) program, specify *ALL for this element.
name: Specify a specific module within the program or service program to be used as a compare value for the program filter.

Element 3: Procedure

*ALL: All procedures in the specified module are used as a compare value for the program filter.
character-value: 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

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

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: Flow trace records having Java data that match the specified packages, classes, and methods are included in the data collected.
*NE: Flow trace records having Java data that matches the specified packages, classes, and methods are excluded from the collection and will not show up.

Element 2:

You can specify up to 5 values for this element set.

Element 1: Java package

character-value: 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.
character-value: Specify the name of 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.
character-value: Specify the name of a method to use as the filter compare value.

Examples

Example 1: Adding a Trace Filter for a Program Trigger

ADDTRCFTR   FTR(PGMFTR)
            PGMTRG(MYLIB/MYPGM MYMODL *PEP *PGM *ENTRY)

This command adds a new trace filter named PGMFTR. If this filter is used in the Start Trace (STRTRC) command, the collection of data will begin when the program entry of MYMODL module of MYPGM is called.