friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
master
ibm-information-center/dist/eclipse/plugins/i5OS.ic.cl_5.4.0.1/addtrcftr.htm

506 lines
16 KiB
HTML
Raw Permalink Blame History

<!doctype html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head><META http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Add Trace Filter (ADDTRCFTR)</title>
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body bgcolor="white">
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
<a name="ADDTRCFTR.Top_Of_Page"></a>
<h2>Add Trace Filter (ADDTRCFTR)</h2>
<table width="100%">
<tr>
<td valign="top" align="left"><b>Where allowed to run: </b>All environments (*ALL)<br>
<b>Threadsafe: </b>No
</td>
<td valign="top" align="right">
<a href="#ADDTRCFTR.PARAMETERS.TABLE">Parameters</a><br>
<a href="#ADDTRCFTR.COMMAND.EXAMPLES">Examples</a><br>
<a href="#ADDTRCFTR.ERROR.MESSAGES">Error messages</a></td>
</tr>
</table>
<div> <a name="ADDTRCFTR"></a>
<p>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.
</p>
<p><b>Restrictions:</b>
</p>
<ul>
<li>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.
</li>
</ul>
</div>
<table width="100%">
<tr><td align="right"><a href="#ADDTRCFTR.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div>
<h3><a name="ADDTRCFTR.PARAMETERS.TABLE">Parameters</a></h3>
<table border="1" cellpadding="4" cellspacing="0">
<!-- col1="10" col2="15" col3="30" col4="10" -->
<tr>
<th bgcolor="aqua" valign="bottom" align="left">Keyword</th>
<th bgcolor="aqua" valign="bottom" align="left">Description</th>
<th bgcolor="aqua" valign="bottom" align="left">Choices</th>
<th bgcolor="aqua" valign="bottom" align="left">Notes</th>
</tr>
<tr>
<td valign="top"><a href="#ADDTRCFTR.FTR"><b>FTR</b></a></td>
<td valign="top">Filter</td>
<td valign="top"><i>Name</i></td>
<td valign="top">Required, Positional 1</td>
</tr>
<tr>
<td valign="top" rowspan="8"><a href="#ADDTRCFTR.PGMTRG"><b>PGMTRG</b></a></td>
<td valign="top">Program trigger</td>
<td valign="top"><i>Element list</i></td>
<td valign="top" rowspan="8">Optional</td>
</tr>
<tr>
<td valign="top">Element 1: Filter entry</td>
<td valign="top">
<i>Qualified object name</i></td>
</tr>
<tr>
<td valign="top" style="padding-left:10pt">Qualifier 1: Filter entry</td>
<td valign="top"><i>Name</i></td>
</tr><tr>
<td valign="top" style="padding-left:10pt">Qualifier 2: Library</td>
<td valign="top"><i>Name</i>, <b><u>*LIBL</u></b></td>
</tr><tr>
<td valign="top">Element 2: Module</td>
<td valign="top">
<i>Name</i></td>
</tr>
<tr>
<td valign="top">Element 3: Procedure</td>
<td valign="top">
<i>Character value</i></td>
</tr>
<tr>
<td valign="top">Element 4: Type</td>
<td valign="top">
<b><u>*PGM</u></b>, *SRVPGM</td>
</tr>
<tr>
<td valign="top">Element 5: Trigger option</td>
<td valign="top">
<b><u>*ENTRYEXIT</u></b>, *ENTRY</td>
</tr>
<tr>
<td valign="top" rowspan="5"><a href="#ADDTRCFTR.JVATRG"><b>JVATRG</b></a></td>
<td valign="top">Java trigger</td>
<td valign="top"><i>Element list</i></td>
<td valign="top" rowspan="5">Optional</td>
</tr>
<tr>
<td valign="top">Element 1: Java package</td>
<td valign="top">
<i>Character value</i>, <b><u>*NONE</u></b></td>
</tr>
<tr>
<td valign="top">Element 2: Java class</td>
<td valign="top">
<i>Character value</i>, <b><u>*ALL</u></b></td>
</tr>
<tr>
<td valign="top">Element 3: Java method</td>
<td valign="top">
<i>Character value</i>, <b><u>*ALL</u></b></td>
</tr>
<tr>
<td valign="top">Element 4: Trigger option</td>
<td valign="top">
<b><u>*ENTRYEXIT</u></b>, *ENTRY, *ENTRYEXITNOPGM, *ENTRYNOPGM</td>
</tr>
<tr>
<td valign="top" rowspan="9"><a href="#ADDTRCFTR.PGMFTR"><b>PGMFTR</b></a></td>
<td valign="top">Program filter</td>
<td valign="top"><i>Element list</i></td>
<td valign="top" rowspan="9">Optional</td>
</tr>
<tr>
<td valign="top">Element 1: Relational operator</td>
<td valign="top">
<b><u>*EQ</u></b>, *NE</td>
</tr>
<tr>
<td valign="top">Element 2: </td>
<td valign="top">
Values (up to 16 repetitions): <i>Element list</i></td>
</tr>
<tr>
<td valign="top" style="padding-left:10pt">Element 1: Filter entry</td>
<td valign="top">
<i>Qualified object name</i></td>
</tr>
<tr>
<td valign="top" style="padding-left:20pt">Qualifier 1: Filter entry</td>
<td valign="top"><i>Name</i></td>
</tr><tr>
<td valign="top" style="padding-left:20pt">Qualifier 2: Library</td>
<td valign="top"><i>Name</i>, <b><u>*LIBL</u></b></td>
</tr><tr>
<td valign="top" style="padding-left:10pt">Element 2: Module</td>
<td valign="top">
<i>Name</i>, <b><u>*ALL</u></b></td>
</tr>
<tr>
<td valign="top" style="padding-left:10pt">Element 3: Procedure</td>
<td valign="top">
<i>Character value</i>, <b><u>*ALL</u></b></td>
</tr>
<tr>
<td valign="top" style="padding-left:10pt">Element 4: Type</td>
<td valign="top">
<b><u>*PGM</u></b>, *SRVPGM</td>
</tr>
<tr>
<td valign="top" rowspan="6"><a href="#ADDTRCFTR.JVAFTR"><b>JVAFTR</b></a></td>
<td valign="top">Java method filter</td>
<td valign="top"><i>Element list</i></td>
<td valign="top" rowspan="6">Optional</td>
</tr>
<tr>
<td valign="top">Element 1: Relational operator</td>
<td valign="top">
<b><u>*EQ</u></b>, *NE</td>
</tr>
<tr>
<td valign="top">Element 2: </td>
<td valign="top">
Values (up to 5 repetitions): <i>Element list</i></td>
</tr>
<tr>
<td valign="top" style="padding-left:10pt">Element 1: Java package</td>
<td valign="top">
<i>Character value</i></td>
</tr>
<tr>
<td valign="top" style="padding-left:10pt">Element 2: Java class</td>
<td valign="top">
<i>Character value</i>, <b><u>*ALL</u></b></td>
</tr>
<tr>
<td valign="top" style="padding-left:10pt">Element 3: Java method</td>
<td valign="top">
<i>Character value</i>, <b><u>*ALL</u></b></td>
</tr>
</table>
<table width="100%">
<tr><td align="right"><a href="#ADDTRCFTR.Top_Of_Page">Top</a></td></tr>
</table>
</div>
<div> <a name="ADDTRCFTR.FTR"></a>
<h3>Filter (FTR)</h3>
<p>Specifies the trace filter to be added. If the specified filter already exists, an error message is issued. An existing trace filter can be removed by using the Remove Trace Filter (RMVTRCFTR) command.
</p>
<p>This is a required parameter.
</p>
<dl>
<dt><b><i>name</i></b></dt>
<dd>Specify the name of the new trace filter.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#ADDTRCFTR.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="ADDTRCFTR.PGMTRG"></a>
<h3>Program trigger (PGMTRG)</h3>
<p>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.
</p>
<p>When the procedure returns and it matches the trigger specification, STRTRC will stop collecting the flow trace records.
</p>
<p><b>Element 1: Filter entry</b>
</p>
<dl>
<dt><b></b></dt>
<dd><b>Qualifier 1: Filter entry</b>
<dl>
<dt><b><i>name</i></b></dt>
<dd>Specify the name of the program which, if called, will cause trace flow records to start being collected.
</dd>
</dl>
</dd>
<dt><b></b></dt>
<dd><b>Qualifier 2: Library</b>
<dl>
<dt><b><u>*LIBL</u></b></dt>
<dd>The library list of the job that issues the STRTRC command is searched to find the specified program or service program.
</dd>
<dt><b><i>name</i></b></dt>
<dd>Specify the name of the library which contains the program or service program.
</dd>
</dl>
</dd>
</dl>
<p><b>Element 2: Module</b>
</p>
<dl>
<dt><b><i>name</i></b></dt>
<dd>Specify the name of the module within the program or service program that contains the procedure that is to be the trigger.
</dd>
</dl>
<p><b>Element 3: Procedure</b>
</p>
<dl>
<dt><b><i>character-value</i></b></dt>
<dd>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.
</dd>
</dl>
<p><b>Element 4: Type</b>
</p>
<dl>
<dt><b><u>*PGM</u></b></dt>
<dd>The program being specified is a program (*PGM) object.
</dd>
<dt><b>*SRVPGM</b></dt>
<dd>The program being specified is a service program (*SRVPGM) object.
</dd>
</dl>
<p><b>Element 5: Trigger option</b>
</p>
<dl>
<dt><b><u>*ENTRYEXIT</u></b></dt>
<dd>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.
</dd>
<dt><b>*ENTRY</b></dt>
<dd>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.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#ADDTRCFTR.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="ADDTRCFTR.JVATRG"></a>
<h3>Java trigger (JVATRG)</h3>
<p>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.
</p>
<p>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'.
</p>
<p>For code compiled for direct execution, specify ENBPFRCOL(*ENTRYEXIT) on the Create Java Program (CRTJVAPGM) CL command.
</p>
<p><b>Element 1: Java package</b>
</p>
<dl>
<dt><b><i>package-name</i></b></dt>
<dd>Specify the name of the Java package that contains the method to use as the trigger.
</dd>
</dl>
<p><b>Element 2: Java class</b>
</p>
<dl>
<dt><b><i>class-name</i></b></dt>
<dd>Specify a class within the package that contains the method to use as the trigger.
</dd>
</dl>
<p><b>Element 3: Java method</b>
</p>
<dl>
<dt><b><i>method-name</i></b></dt>
<dd>Specify a method to use as the trigger.
</dd>
</dl>
<p><b>Element 4: Trigger option</b>
</p>
<dl>
<dt><b><u>*ENTRYEXIT</u></b></dt>
<dd>The specified trigger method enables the collection of events at Java method entry time. At Java method exit, the collection of events is disabled.
</dd>
<dt><b>*ENTRY</b></dt>
<dd>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.
</dd>
<dt><b>*ENTRYEXITNOPGM</b></dt>
<dd>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.
</dd>
<dt><b>*ENTRYNOPGM</b></dt>
<dd>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.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#ADDTRCFTR.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="ADDTRCFTR.PGMFTR"></a>
<h3>Program filter (PGMFTR)</h3>
<p>Specifies the program comparisons to use for this filter.
</p>
<p><b>Element 1: Relational operator</b>
</p>
<dl>
<dt><b><u>*EQ</u></b></dt>
<dd>Flow trace records having program data that matches the specified program are included in the data collected.
</dd>
<dt><b>*NE</b></dt>
<dd>Flow trace records having program data that matches the specified program are excluded from the data collected. These trace records will not show up.
</dd>
</dl>
<p><b>Element 2:</b>
</p>
<p>You can specify up to 16 values for this element set.
</p>
<dl>
<dt><b></b></dt>
<dd>
<p><b>Element 1: Filter entry</b>
</p>
<dl>
<dt><b></b></dt>
<dd>
<p><b>Qualifier 1: Filter entry</b>
</p>
<dl>
<dt><b><i>name</i></b></dt>
<dd>Specify the name of the program to be used as a compare value for the program filter.
</dd>
</dl>
</dd>
<dt><b></b></dt>
<dd>
<p><b>Qualifier 2: Library</b>
</p>
<dl>
<dt><b><u>*LIBL</u></b></dt>
<dd>The library list of the job that issues the STRTRC command is searched to find the specified program or service program.
</dd>
<dt><b><i>name</i></b></dt>
<dd>Specify the name of the library which contains the program or service program.
</dd>
</dl>
</dd>
</dl>
</dd>
<dt><b></b></dt>
<dd>
<p><b>Element 2: Module</b>
</p>
<dl>
<dt><b><u>*ALL</u></b></dt>
<dd>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.
</dd>
<dt><b><i>name</i></b></dt>
<dd>Specify a specific module within the program or service program to be used as a compare value for the program filter.
</dd>
</dl>
</dd>
<dt><b></b></dt>
<dd>
<p><b>Element 3: Procedure</b>
</p>
<dl>
<dt><b><u>*ALL</u></b></dt>
<dd>All procedures in the specified module are used as a compare value for the program filter.
</dd>
<dt><b><i>character-value</i></b></dt>
<dd>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.
</dd>
</dl>
</dd>
<dt><b></b></dt>
<dd>
<p><b>Element 4: Type</b>
</p>
<dl>
<dt><b><u>*PGM</u></b></dt>
<dd>The program being specified is a program (*PGM) object.
</dd>
<dt><b>*SRVPGM</b></dt>
<dd>The program being specified is a service program (*SRVPGM) object.
</dd>
</dl>
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#ADDTRCFTR.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="ADDTRCFTR.JVAFTR"></a>
<h3>Java method filter (JVAFTR)</h3>
<p>Specifies the Java package, class, and methods to be used as compare values for the Java filter.
</p>
<p><b>Element 1: Relational operator</b>
</p>
<dl>
<dt><b><u>*EQ</u></b></dt>
<dd>Flow trace records having Java data that match the specified packages, classes, and methods are included in the data collected.
</dd>
<dt><b>*NE</b></dt>
<dd>Flow trace records having Java data that matches the specified packages, classes, and methods are excluded from the collection and will not show up.
</dd>
</dl>
<p><b>Element 2:</b>
</p>
<p>You can specify up to 5 values for this element set.
</p>
<dl>
<dt><b></b></dt>
<dd>
<p><b>Element 1: Java package</b>
</p>
<dl>
<dt><b><i>character-value</i></b></dt>
<dd>Specify the name of the Java package to be used as a compare value for the filter.
</dd>
</dl>
</dd>
<dt><b></b></dt>
<dd>
<p><b>Element 2: Java class</b>
</p>
<dl>
<dt><b><u>*ALL</u></b></dt>
<dd>All classes in the specified package will pass the Java filter.
</dd>
<dt><b><i>character-value</i></b></dt>
<dd>Specify the name of a class within the package to be used as a compare value for the filter.
</dd>
</dl>
</dd>
<dt><b></b></dt>
<dd>
<p><b>Element 3: Java method</b>
</p>
<dl>
<dt><b><u>*ALL</u></b></dt>
<dd>All methods in the specified class and package will pass the filter.
</dd>
<dt><b><i>character-value</i></b></dt>
<dd>Specify the name of a method to use as the filter compare value.
</dd>
</dl>
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#ADDTRCFTR.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div><h3><a name="ADDTRCFTR.COMMAND.EXAMPLES">Examples</a> </h3>
<p><b>Example 1: Adding a Trace Filter for a Program Trigger</b>
</p>
<p>
<pre>
ADDTRCFTR FTR(PGMFTR)
PGMTRG(MYLIB/MYPGM MYMODL *PEP *PGM *ENTRY)
</pre>
</p>
<p>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.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#ADDTRCFTR.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div>
<h3><a name="ADDTRCFTR.ERROR.MESSAGES">Error messages</a></h3>Unknown
</div>
<table width="100%">
<tr><td align="right"><a href="#ADDTRCFTR.Top_Of_Page">Top</a></td></tr>
</table>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink