1052 lines
44 KiB
HTML
1052 lines
44 KiB
HTML
|
|
||
|
|
<!doctype html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head><META http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<title>Start Trace (STRTRC)</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="STRTRC.Top_Of_Page"></a>
|
||
|
|
<h2>Start Trace (STRTRC)</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="#STRTRC.PARAMETERS.TABLE">Parameters</a><br>
|
||
|
|
<a href="#STRTRC.COMMAND.EXAMPLES">Examples</a><br>
|
||
|
|
<a href="#STRTRC.ERROR.MESSAGES">Error messages</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<div> <a name="STRTRC"></a>
|
||
|
|
<p>The Start Trace (STRTRC) command starts traces of original program model (OPM) programs and Integrated Language Environment (ILE) procedures and Java programs (both compiled and JIT). Tracing can be done for multiple jobs using this command. Any number of trace sessions can be started, but active trace session identifiers must be unique across the system. This command can trace call-return flow, data returned by trace points defined in the operating system, component trace information or all three.
|
||
|
|
</p>
|
||
|
|
<p>The trace session continues until ended with the End Trace (ENDTRC) command or automatically by the watch for trace event functionality. A trace session can be ended from the same job or a different job.
|
||
|
|
</p>
|
||
|
|
<p><b>Restrictions:</b>
|
||
|
|
</p>
|
||
|
|
<ul>
|
||
|
|
<li>To use this command, 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>
|
||
|
|
<li>If you specify a generic user name for the <b>Job name (JOB)</b> parameter, you must have all object (*ALLOBJ) special authority, or be authorized to the Trace Any User function of Operating System through iSeries Navigator's Application Administration support. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_ALLOBJ_TRACE_ANY_USER, can also be used to change the list of users that are allowed to perform trace operations.
|
||
|
|
</li>
|
||
|
|
<li>A trace cannot be defined to trace all job names and all users.
|
||
|
|
</li>
|
||
|
|
<li>At least one generic job name must be specified if *YES has been specified for the <b>Restart after next IPL (RESTRIPL)</b> parameter.
|
||
|
|
</li>
|
||
|
|
<li>Watch-related parameters cannot be specified if *YES is specified for the RESTRIPL parameter.
|
||
|
|
</li>
|
||
|
|
<li>Only one STRTRC command across the system can be specified to restart after the next IPL.
|
||
|
|
</li>
|
||
|
|
<li>When the <b>Watched job (WCHJOB)</b> parameter is specified, the issuer of the command must be running under a user profile which is the same as the job user identity of the job being watched, or the issuer of the command must be running under a user profile which has job control (*JOBCTL) special authority. Job control (*JOBCTL) special authority is also required if a generic user name is specified for the WCHJOB parameter.
|
||
|
|
</li>
|
||
|
|
<li>If you specify a generic user name in the WCHJOB parameter, you must have all object (*ALLOBJ) special authority, or be authorized to the Watch Any Job function of Operating System through iSeries Navigator's Application Administration support. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_WATCH_ANY_JOB, can also be used to change the list of users that are allowed to start and end watch operations.
|
||
|
|
</li>
|
||
|
|
<li>You must have operational (*OBJOPR) and execute (*EXECUTE) authorities to the user exit program if specified in <b>Trace program (TRCPGM)</b> parameter, and execute (*EXECUTE) authority to the library where the program is located.
|
||
|
|
</li>
|
||
|
|
<li>You must have use (*USE) authority to the message queues specified in <b>Watched message queue (WCHMSGQ)</b> parameter, and use (*USE) authority to the library where the message queue is located.
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<hr size="2" width="100%">
|
||
|
|
|
||
|
|
<div>
|
||
|
|
<h3><a name="STRTRC.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="#STRTRC.SSNID"><b>SSNID</b></a></td>
|
||
|
|
<td valign="top">Session ID</td>
|
||
|
|
<td valign="top"><i>Name</i>, *GEN</td>
|
||
|
|
<td valign="top">Required, Positional 1</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top" rowspan="6"><a href="#STRTRC.JOB"><b>JOB</b></a></td>
|
||
|
|
<td valign="top">Jobs</td>
|
||
|
|
<td valign="top">Single values: <b><u>*</u></b><br>Other values (up to 8 repetitions): <i>Element list</i></td>
|
||
|
|
<td valign="top" rowspan="6">Optional</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">Element 1: Job name</td>
|
||
|
|
<td valign="top">
|
||
|
|
<i>Qualified job name</i></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top" style="padding-left:10pt">Qualifier 1: Job name</td>
|
||
|
|
<td valign="top"><i>Generic name, name</i>, *ALL</td>
|
||
|
|
</tr><tr>
|
||
|
|
<td valign="top" style="padding-left:10pt">Qualifier 2: User</td>
|
||
|
|
<td valign="top"><i>Generic name, name</i>, *ALL</td>
|
||
|
|
</tr><tr>
|
||
|
|
<td valign="top" style="padding-left:10pt">Qualifier 3: Number</td>
|
||
|
|
<td valign="top">000001-999999, <b><u>*ALL</u></b></td>
|
||
|
|
</tr><tr>
|
||
|
|
<td valign="top">Element 2: Thread ID to include</td>
|
||
|
|
<td valign="top">
|
||
|
|
Values (up to 20 repetitions): <i>Character value</i>, <b><u>*ALL</u></b>, *INITIAL, *SELECT</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><a href="#STRTRC.JOBTYPE"><b>JOBTYPE</b></a></td>
|
||
|
|
<td valign="top">Job types</td>
|
||
|
|
<td valign="top"><b><u>*ALL</u></b>, *ACTIVE, *NEW</td>
|
||
|
|
<td valign="top">Optional</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><a href="#STRTRC.MAXSTG"><b>MAXSTG</b></a></td>
|
||
|
|
<td valign="top">Maximum storage to use</td>
|
||
|
|
<td valign="top">1024-4000000, <b><u>10000</u></b></td>
|
||
|
|
<td valign="top">Optional</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><a href="#STRTRC.TRCFULL"><b>TRCFULL</b></a></td>
|
||
|
|
<td valign="top">Trace full</td>
|
||
|
|
<td valign="top">*STOPTRC, <b><u>*WRAP</u></b></td>
|
||
|
|
<td valign="top">Optional</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><a href="#STRTRC.JOBTRCTYPE"><b>JOBTRCTYPE</b></a></td>
|
||
|
|
<td valign="top">Trace type</td>
|
||
|
|
<td valign="top">Values (up to 2 repetitions): <b><u>*ALL</u></b>, *FLOW, *DATA, *TRCTYPE</td>
|
||
|
|
<td valign="top">Optional</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top" rowspan="3"><a href="#STRTRC.TRCTYPE"><b>TRCTYPE</b></a></td>
|
||
|
|
<td valign="top">Trace type</td>
|
||
|
|
<td valign="top">Single values: <b><u>*NONE</u></b><br>Other values (up to 50 repetitions): <i>Element list</i></td>
|
||
|
|
<td valign="top" rowspan="3">Optional</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">Element 1: Component</td>
|
||
|
|
<td valign="top">
|
||
|
|
<i>Character value</i>, *ASPMGT, *CLUSTER, *CMTCTL, *DBHSVR, *DBSQL, *DEVCFG, *DIRSRV, *EDRSQL, *ENVVAR, *FILESVR, *FLIGHTRCD, *HPT, *HTTP, *IFS, *IPC, *IPPDRV, *LOCKSPACE, *NETSVR, *NPS, *OPASSIST, *OPENSSL, *POSIXMISC, *POSIXPROC, *PTHREAD, *QNTC, *QSHELL, *RAS, *REGFAC, *SECURITY, *SERVICE, *SOCKETS, *TCPIPCFG, *THREADMGT, *WRKMGT</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">Element 2: Trace level</td>
|
||
|
|
<td valign="top">
|
||
|
|
*ERROR, *INFO, *VERBOSE</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><a href="#STRTRC.TRCFTR"><b>TRCFTR</b></a></td>
|
||
|
|
<td valign="top">Trace filter</td>
|
||
|
|
<td valign="top"><i>Name</i>, <b><u>*NONE</u></b></td>
|
||
|
|
<td valign="top">Optional</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><a href="#STRTRC.RESTRIPL"><b>RESTRIPL</b></a></td>
|
||
|
|
<td valign="top">Restart after next IPL</td>
|
||
|
|
<td valign="top"><b><u>*NO</u></b>, *YES</td>
|
||
|
|
<td valign="top">Optional</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top" rowspan="4"><a href="#STRTRC.WCHMSG"><b>WCHMSG</b></a></td>
|
||
|
|
<td valign="top">Watch for message</td>
|
||
|
|
<td valign="top">Single values: <b><u>*NONE</u></b><br>Other values (up to 5 repetitions): <i>Element list</i></td>
|
||
|
|
<td valign="top" rowspan="4">Optional</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">Element 1: Message identifier</td>
|
||
|
|
<td valign="top">
|
||
|
|
<i>Name</i></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">Element 2: Comparison data</td>
|
||
|
|
<td valign="top">
|
||
|
|
<i>Character value</i>, <b><u>*NONE</u></b></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">Element 3: Compare against</td>
|
||
|
|
<td valign="top">
|
||
|
|
<b><u>*MSGDTA</u></b>, *FROMPGM, *TOPGM</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top" rowspan="4"><a href="#STRTRC.WCHMSGQ"><b>WCHMSGQ</b></a></td>
|
||
|
|
<td valign="top">Watched message queue</td>
|
||
|
|
<td valign="top">Values (up to 3 repetitions): <i>Element list</i></td>
|
||
|
|
<td valign="top" rowspan="4">Optional</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">Element 1: Message queue</td>
|
||
|
|
<td valign="top">
|
||
|
|
Single values: <b><u>*SYSOPR</u></b>, *JOBLOG, *HSTLOG<br>Other values: <i>Qualified object name</i></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top" style="padding-left:10pt">Qualifier 1: Message queue</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" rowspan="5"><a href="#STRTRC.WCHJOB"><b>WCHJOB</b></a></td>
|
||
|
|
<td valign="top">Watched job</td>
|
||
|
|
<td valign="top">Single values: <b><u>*</u></b><br>Other values (up to 5 repetitions): <i>Element list</i></td>
|
||
|
|
<td valign="top" rowspan="5">Optional</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">Element 1: Job name</td>
|
||
|
|
<td valign="top">
|
||
|
|
<i>Qualified job name</i></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top" style="padding-left:10pt">Qualifier 1: Job name</td>
|
||
|
|
<td valign="top"><i>Generic name, name</i></td>
|
||
|
|
</tr><tr>
|
||
|
|
<td valign="top" style="padding-left:10pt">Qualifier 2: User</td>
|
||
|
|
<td valign="top"><i>Generic name, name</i></td>
|
||
|
|
</tr><tr>
|
||
|
|
<td valign="top" style="padding-left:10pt">Qualifier 3: Number</td>
|
||
|
|
<td valign="top">000001-999999, <b><u>*ALL</u></b></td>
|
||
|
|
</tr><tr>
|
||
|
|
<td valign="top" rowspan="4"><a href="#STRTRC.WCHLICLOG"><b>WCHLICLOG</b></a></td>
|
||
|
|
<td valign="top">Watch for LIC log entry</td>
|
||
|
|
<td valign="top">Single values: <b><u>*NONE</u></b><br>Other values (up to 5 repetitions): <i>Element list</i></td>
|
||
|
|
<td valign="top" rowspan="4">Optional</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">Element 1: Major code</td>
|
||
|
|
<td valign="top">
|
||
|
|
<i>Character value</i>, *ALL</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">Element 2: Minor code</td>
|
||
|
|
<td valign="top">
|
||
|
|
<i>Character value</i>, *ALL</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">Element 3: Comparison data</td>
|
||
|
|
<td valign="top">
|
||
|
|
<i>Character value</i>, <b><u>*NONE</u></b></td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top"><a href="#STRTRC.WCHTIMO"><b>WCHTIMO</b></a></td>
|
||
|
|
<td valign="top">Length of time to watch</td>
|
||
|
|
<td valign="top">1-43200, <b><u>*NOMAX</u></b></td>
|
||
|
|
<td valign="top">Optional</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top" rowspan="3"><a href="#STRTRC.TRCPGM"><b>TRCPGM</b></a></td>
|
||
|
|
<td valign="top">Trace program</td>
|
||
|
|
<td valign="top">Single values: <b><u>*NONE</u></b><br>Other values: <i>Qualified object name</i></td>
|
||
|
|
<td valign="top" rowspan="3">Optional</td>
|
||
|
|
</tr>
|
||
|
|
<tr>
|
||
|
|
<td valign="top">Qualifier 1: Trace program</td>
|
||
|
|
<td valign="top"><i>Name</i></td>
|
||
|
|
</tr><tr>
|
||
|
|
<td valign="top">Qualifier 2: Library</td>
|
||
|
|
<td valign="top"><i>Name</i>, <b><u>*LIBL</u></b></td>
|
||
|
|
</tr><tr>
|
||
|
|
<td valign="top"><a href="#STRTRC.TRCPGMITV"><b>TRCPGMITV</b></a></td>
|
||
|
|
<td valign="top">Time interval</td>
|
||
|
|
<td valign="top">1-9999, <b><u>*NONE</u></b></td>
|
||
|
|
<td valign="top">Optional</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
</div>
|
||
|
|
<div> <a name="STRTRC.SSNID"></a>
|
||
|
|
<h3>Session ID (SSNID)</h3>
|
||
|
|
<p>Specifies a session identifier for this trace. This identifier must be unique across all active traces on the system.
|
||
|
|
</p>
|
||
|
|
<p>This is a required parameter.
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b>*GEN</b></dt>
|
||
|
|
<dd>The system will generate a unique session identifier for this trace.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>name</i></b></dt>
|
||
|
|
<dd>Specify the session identifier for this trace.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="STRTRC.JOB"></a>
|
||
|
|
<h3>Job name (JOB)</h3>
|
||
|
|
<p>Specifies which jobs are to be traced.
|
||
|
|
</p>
|
||
|
|
<p><b>Single values</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*</u></b></dt>
|
||
|
|
<dd>Only the job that issues the STRTRC (Start Trace) command is to be traced.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p><b>Element 1: Job name</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b></b></dt>
|
||
|
|
<dd>
|
||
|
|
<p><b>Qualifier 1: Job name</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><i>generic-name</i></b></dt>
|
||
|
|
<dd>Specify the generic name of the jobs to be traced. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic job name specifies all jobs with job names that begin with the generic prefix.
|
||
|
|
</dd>
|
||
|
|
<dt><b><u>*ALL</u></b></dt>
|
||
|
|
<dd>All jobs names with the specified job user name are traced. *ALL for the job name is considered to be a generic job specification because it will trace all jobs that meet the job user name qualifiers that you specified.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>name</i></b></dt>
|
||
|
|
<dd>Specify the name of the job to be traced. Up to eight job names may be specified, but only one generic job name is allowed.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</dd>
|
||
|
|
<dt><b></b></dt>
|
||
|
|
<dd>
|
||
|
|
<p><b>Qualifier 2: User</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><i>generic-name</i></b></dt>
|
||
|
|
<dd>Specify the generic user name of the jobs from which trace records are to be collected. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic user name specifies all jobs with user names that begin with the generic prefix.
|
||
|
|
</dd>
|
||
|
|
<dt><b><u>*ALL</u></b></dt>
|
||
|
|
<dd>All job user name with the specified job name are traced. *ALL for the job user name is considered to be a generic job specification because it will trace all jobs that meet the job name qualifiers that you specified.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>name</i></b></dt>
|
||
|
|
<dd>Specify the user name of the job to be traced.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</dd>
|
||
|
|
<dt><b></b></dt>
|
||
|
|
<dd>
|
||
|
|
<p><b>Qualifier 3: Number</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*ALL</u></b></dt>
|
||
|
|
<dd>All jobs with the specified job name and user name are traced. *ALL for the job number is considered to be a generic job specification because it will trace all jobs that meet the job name and job user name qualifiers that you specified.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>000001-999999</i></b></dt>
|
||
|
|
<dd>Specify the job number to further qualify the job name and user name. You cannot specify a job number if a generic job name qualifier or generic user name qualifier is specified.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p><b>Element 2: Thread ID to include</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*ALL</u></b></dt>
|
||
|
|
<dd>All threads within the specified job name and user name are traced.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*INITIAL</b></dt>
|
||
|
|
<dd>Only the initial thread within the specified job name and user name is traced.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*SELECT</b></dt>
|
||
|
|
<dd>A list of thread identifiers is shown from which the user can select up to twenty to be traced. This value is only valid if the command is run in an interactive job.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>thread-identifier</i></b></dt>
|
||
|
|
<dd>Specify the identifiers of up to twenty threads whose information is to be included.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="STRTRC.JOBTYPE"></a>
|
||
|
|
<h3>Job types (JOBTYPE)</h3>
|
||
|
|
<p>Specifies the types of jobs for which trace data is to be collected.
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*ALL</u></b></dt>
|
||
|
|
<dd>All jobs that meet the job name selection criteria will be included in this trace collection. This includes jobs that are currently active on the system. If a generic job name was specified, new jobs that start after this trace session begins and meet the generic job name selection criteria, will be included in the trace collection as well.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*ACTIVE</b></dt>
|
||
|
|
<dd>Only jobs that are currently active at the time this trace session is being activated and meet the job name selection criteria will be included in this trace collection.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*NEW</b></dt>
|
||
|
|
<dd>Only new jobs that begin after this trace session is activated and meet the generic job name selection criteria will be included in this trace collection.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="STRTRC.MAXSTG"></a>
|
||
|
|
<h3>Maximum storage to use (MAXSTG)</h3>
|
||
|
|
<p>Specifies the requested maximum amount of storage, in kilobytes (K), to use for the collected trace records. The system will calculate the minimum amount of storage that is necessary for the trace; this minimum storage size calculation is dependent upon the system's processor configuration. The minimum amount of storage may be significantly larger than the size specified on the MAXSTG parameter; the system will use the larger of the two values.
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>10000</u></b></dt>
|
||
|
|
<dd>Up to 10,000 kilobytes of storage is used.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>1024-4000000</i></b></dt>
|
||
|
|
<dd>Specify the maximum amount of storage, in kilobytes, to be used to store trace records (one kilobyte equals 1024 bytes).
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="STRTRC.TRCFULL"></a>
|
||
|
|
<h3>Trace full (TRCFULL)</h3>
|
||
|
|
<p>Specifies whether the trace records wrap (replace the oldest records with new records) or whether the trace stops when all of the storage specified by the MAXSTG parameter has been used.
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*WRAP</u></b></dt>
|
||
|
|
<dd>When the trace storage is full, the trace wraps to the beginning. The oldest trace records are written over by new ones as they are collected.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*STOPTRC</b></dt>
|
||
|
|
<dd>Tracing stops when the trace storage is full of trace records.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="STRTRC.JOBTRCTYPE"></a>
|
||
|
|
<h3>Trace type (JOBTRCTYPE)</h3>
|
||
|
|
<p>Specifies the types of job trace data to be stored in the trace file.
|
||
|
|
</p>
|
||
|
|
<p>You can specify 2 values for this parameter.
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*ALL</u></b></dt>
|
||
|
|
<dd>All the trace data collected is stored in trace records. This includes tracing the flow of control and the trace data itself.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*FLOW</b></dt>
|
||
|
|
<dd>The flow of control is traced when OPM programs and ILE procedures are called and when they return.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*DATA</b></dt>
|
||
|
|
<dd>The data that is provided at predefined trace points within the operating system is stored in trace records. This includes trace records for the CL commands that have run.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*TRCTYPE</b></dt>
|
||
|
|
<dd>Trace the specific components specified for the <b>Trace type (TRCTYPE)</b> parameter.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="STRTRC.TRCTYPE"></a>
|
||
|
|
<h3>Trace type (TRCTYPE)</h3>
|
||
|
|
<p>Specifies the component to trace and the level to use. You can specify up to 50 trace components to be traced.
|
||
|
|
</p>
|
||
|
|
<p><b>Single values</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*NONE</u></b></dt>
|
||
|
|
<dd>No component trace is specified.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p><b>Element 1: Component</b>
|
||
|
|
</p>
|
||
|
|
<p>Each trace type is identified by a special value. Specify trace component special values from the following table:
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<pre>
|
||
|
|
TRACE DESCRIPTION SPECIAL VALUE
|
||
|
|
ASP Management *ASPMGT
|
||
|
|
Cluster Resource Services *CLUSTER
|
||
|
|
Commitment Control *CMTCTL
|
||
|
|
Database Host Server *DBHSVR
|
||
|
|
Database SQL *DBSQL
|
||
|
|
Device Configuration *DEVCFG
|
||
|
|
Directory Services *DIRSRV
|
||
|
|
Extended Dynamic Remote SQL (EDRS) *EDRSQL
|
||
|
|
Environment Variable APIs *ENVVAR
|
||
|
|
File Server *FILESVR
|
||
|
|
Flight Recorder *FLIGHTRCD
|
||
|
|
Host Print Transform *HPT
|
||
|
|
HTTP Server powered by Apache *HTTP
|
||
|
|
Integrated File System *IFS
|
||
|
|
Interprocess Communication APIs *IPC
|
||
|
|
Internet Print Protocol Driver *IPPDRV
|
||
|
|
Lock Space Management *LOCKSPACE
|
||
|
|
iSeries NetServer *NETSVR
|
||
|
|
Network Print Server *NPS
|
||
|
|
Operational Assistant *OPASSIST
|
||
|
|
OpenSSL APIs *OPENSSL
|
||
|
|
POSIX Miscellaneous APIs *POSIXMISC
|
||
|
|
POSIX Process-Related APIs *POSIXPROC
|
||
|
|
POSIX Thread APIs *PTHREAD
|
||
|
|
QNTC File System *QNTC
|
||
|
|
Qshell *QSHELL
|
||
|
|
Remote Access Services *RAS
|
||
|
|
Registration Facility *REGFAC
|
||
|
|
Software Security *SECURITY
|
||
|
|
Service Facility *SERVICE
|
||
|
|
Sockets APIs *SOCKETS
|
||
|
|
TCP/IP Configuration *TCPIPCFG
|
||
|
|
Thread Management *THREADMGT
|
||
|
|
Work Management *WRKMGT
|
||
|
|
</pre>
|
||
|
|
</p>
|
||
|
|
<p><b>Element 2: Trace level</b>
|
||
|
|
</p>
|
||
|
|
<p>Specifies the trace level to be used for the specified component.
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b>*ERROR</b></dt>
|
||
|
|
<dd>The trace level ERROR will be used. Components typically trace error return codes, exception conditions, and invalid input. The amount of data is usually small.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*INFO</b></dt>
|
||
|
|
<dd>The trace level INFO will be used, which also includes ERROR trace level data. Components typically trace entry and exit from interfaces, parameters and return codes, and major changes of flow or semantics caused by input or other decisions. The amount of data is moderate.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*VERBOSE</b></dt>
|
||
|
|
<dd>The trace level VERBOSE will be used, which also includes INFO and ERROR trace level data. Components typically trace detailed data that could assist in debugging control flow, data corruption, data structures, environment, call stacks, and resource allocations. The amount of data can be large.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="STRTRC.TRCFTR"></a>
|
||
|
|
<h3>Trace filter (TRCFTR)</h3>
|
||
|
|
<p>Specifies the trace filter to be used. The Add Trace Filter (ADDTRCFTR) command must be issued to define the trace filter. The filter determines what information is collected in the trace based on the filter values. The filter values are compared to the actual trace data. If a filter is not specified, then all trace information is collected.
|
||
|
|
</p>
|
||
|
|
<p>The trace filter parameter can only be specified if *ALL or *FLOW has been specified for the <b>Trace type (JOBTRCTYPE)</b> parameter. The trace filter applies to the *FLOW (call/return) trace only.
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*NONE</u></b></dt>
|
||
|
|
<dd>No trace filter will be used.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>name</i></b></dt>
|
||
|
|
<dd>Specify the name of the trace filter to be used.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="STRTRC.RESTRIPL"></a>
|
||
|
|
<h3>Restart after next IPL (RESTRIPL)</h3>
|
||
|
|
<p>Specifies if the trace will be restarted after the next initial program load (IPL) of the operating system.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<b>Note: </b>Only one STRTRC command can be specified to restart after the next IPL. If another STRTRC command was previously specified with RESTRIPL(*YES), an error message is sent and this STRTRC command fails. This parameter can be specified only if at least one generic job name is specified in the <b>Job name (JOB)</b> parameter. You must run the End Trace (ENDTRC) command for the trace session which specified RESTRIPL(*YES) to clear the storage used to hold the STRTRC command string to be restarted after an IPL. This parameter cannot be specified if any watch-related parameters have been specified.
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<b>Note: </b>If the IPL is associated with an install or upgrade of the operating system, the trace will not be restarted.
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*NO</u></b></dt>
|
||
|
|
<dd>The trace will not be restarted after an IPL.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*YES</b></dt>
|
||
|
|
<dd>The trace will be restarted after the next IPL. The trace being started by this STRTRC automatically ends if an IPL of the operating system is performed. The trace started after the next IPL will be a new trace session with new trace data. You can use the ENDTRC command to end the trace.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="STRTRC.WCHMSG"></a>
|
||
|
|
<h3>Watch for message (WCHMSG)</h3>
|
||
|
|
<p>Specifies up to five message identifiers which are to be watched for. If a value other than *NONE is specified, you must specify where to watch for the message on the WCHMSGQ parameter. When the watched for message is added to the specified message queue or log, the trace exit program is called; if no trace exit program is defined, the trace stops.
|
||
|
|
</p>
|
||
|
|
<p><b>Single values</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*NONE</u></b></dt>
|
||
|
|
<dd>No messages will be watched for.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p><b>Element 1: Message identifier</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><i>name</i></b></dt>
|
||
|
|
<dd>Specify the 7-character message identifier to be watched for.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p><b>Element 2: Comparison data</b>
|
||
|
|
</p>
|
||
|
|
<p>Specify comparison data to be used if a message matching the specified message ID is added to the specified message queue or log. If the message data, the "From program" or the "To program" includes the specified text, the watched for condition is true. If the message data, the "From program" or the "To program" does not contain the specified text, the trace function continues.
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*NONE</u></b></dt>
|
||
|
|
<dd>No comparison data is specified. If a message matching the specified message ID is added to the specified message queue or log, the watched for condition is true.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>character-value</i></b></dt>
|
||
|
|
<dd>Specify the text string used to compare against the message data, the "From program" or the "To program" of the watched for message. This text is case sensitive and can be quoted in order to specify imbedded or trailing blanks.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p><b>Element 3: Compare against</b>
|
||
|
|
</p>
|
||
|
|
<p>Specify which part of the message the comparison data specified for element 2 is to be compared against.
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*MSGDATA</u></b></dt>
|
||
|
|
<dd>The comparison data will be compared against the message replacement data.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*FROMPGM</b></dt>
|
||
|
|
<dd>The comparison data will be compared against the name of the program sending the message, or the name of the ILE program that contains the procedure sending the message.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*TOPGM</b></dt>
|
||
|
|
<dd>The comparison data will be compared against the name of the program the message was sent to, or the name of the ILE program that contains the procedure the message was sent to.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="STRTRC.WCHMSGQ"></a>
|
||
|
|
<h3>Watched message queue (WCHMSGQ)</h3>
|
||
|
|
<p>Specifies where to watch for the message identifiers specified on the WCHMSG parameter. You can specify to watch the message being added to the system operator message queue, the history log, other message queues, and job logs. Up to three message queues or special values can be specified.
|
||
|
|
</p>
|
||
|
|
<p><b>Element 1: Message queue</b>
|
||
|
|
</p>
|
||
|
|
<p><b>Single values</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*SYSOPR</u></b></dt>
|
||
|
|
<dd>Watch messages added to the system operator message queue (QSYSOPR message queue in library QSYS).
|
||
|
|
</dd>
|
||
|
|
<dt><b>*JOBLOG</b></dt>
|
||
|
|
<dd>Watch messages added to the job logs of the jobs specified for the <b>Watched job (WCHJOB)</b> parameter.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*HSTLOG</b></dt>
|
||
|
|
<dd>Watch messages added to the history log (QHST message queue in library QSYS).
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<dl>
|
||
|
|
<dt><b></b></dt>
|
||
|
|
<dd>
|
||
|
|
<p><b>Qualifier 1: Message queue</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><i>name</i></b></dt>
|
||
|
|
<dd>Specify the name of the message queue to watch.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</dd>
|
||
|
|
<dt><b></b></dt>
|
||
|
|
<dd>
|
||
|
|
<p><b>Qualifier 2: Library</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*LIBL</u></b></dt>
|
||
|
|
<dd>All libraries in the library list for the current thread are searched until the first match is found.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<dl>
|
||
|
|
<dt><b><i>name</i></b></dt>
|
||
|
|
<dd>Specify the name of the library where the message queue is located.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="STRTRC.WCHJOB"></a>
|
||
|
|
<h3>Watched job (WCHJOB)</h3>
|
||
|
|
<p>Specifies the job whose job log is watched for the messages specified on the WCHMSG parameter. The specified job will only be watched if *JOBLOG is specified on the WCHMSGQ parameter. Up to five job names may be specified.
|
||
|
|
</p>
|
||
|
|
<p><b>Single values</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*</u></b></dt>
|
||
|
|
<dd>Only the job log of the job that issued this trace command is watched.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p><b>Element 1: Job name</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b></b></dt>
|
||
|
|
<dd>
|
||
|
|
<p><b>Qualifier 1: Job name</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><i>generic-name</i></b></dt>
|
||
|
|
<dd>Specify the generic name of the job to be watched. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic job name specifies all jobs with job names that begin with the generic prefix.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>name</i></b></dt>
|
||
|
|
<dd>Specify the name of the job to be watched.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</dd>
|
||
|
|
<dt><b></b></dt>
|
||
|
|
<dd>
|
||
|
|
<p><b>Qualifier 2: User</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><i>generic-name</i></b></dt>
|
||
|
|
<dd>Specify the generic name of the user name of the job to be watched. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic user name specifies all jobs with the specified job name and with user names that begin with the generic prefix.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>name</i></b></dt>
|
||
|
|
<dd>Specify the user name of the job to be watched.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</dd>
|
||
|
|
<dt><b></b></dt>
|
||
|
|
<dd>
|
||
|
|
<p><b>Qualifier 3: Number</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*ALL</u></b></dt>
|
||
|
|
<dd>All jobs with the specified job name and user name are watched.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>000001-999999</i></b></dt>
|
||
|
|
<dd>Specify the job number to further qualify the job name and user name. You cannot specify a job number if a generic job name or a generic user name qualifier is specified.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="STRTRC.WCHLICLOG"></a>
|
||
|
|
<h3>Watch for LIC log entry (WCHLICLOG)</h3>
|
||
|
|
<p>Specifies up to five licensed internal code (LIC) log entry identifiers which are to be watched for. Each LIC log entry contains a major and a minor code. The watched for condition will be met if a LIC log entry is added that matches the specified major and minor codes and any comparison data specified. When the watched for log entry is added to the LIC log, the trace exit program is called, even when the comparison data specified does not match; if no trace exit program is defined, the trace stops.
|
||
|
|
</p>
|
||
|
|
<p><b>Single values </b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*NONE</u></b></dt>
|
||
|
|
<dd>No LIC log entries will be watched for.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p><b>Element 1: Major code</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b>*ALL</b></dt>
|
||
|
|
<dd>Any LIC log entry major code will be considered to be a match. If *ALL is specified for the major code, you cannot specify *ALL for the LIC log entry minor code.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>character-value</i></b></dt>
|
||
|
|
<dd>Specify the LIC log major code to be watched for. You can specify either a hexadecimal digit or a question mark for each character in the four-digit code. A question mark is a wildcard character that will match any digit in that position. Up to three wildcard characters can be specified.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p><b>Element 2: Minor code</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b>*ALL</b></dt>
|
||
|
|
<dd>Any LIC log entry minor code will be considered to be a match. If *ALL is specified for the minor code, you cannot specify *ALL for the LIC log entry major code.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>character-value</i></b></dt>
|
||
|
|
<dd>Specify the LIC log minor code to be watched for. You can specify either a hexadecimal digit or a question mark for each character in the four-digit code. A question mark is a wildcard character that will match any digit in that position. Up to three wildcard characters can be specified.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p><b>Element 3: Comparison data</b>
|
||
|
|
</p>
|
||
|
|
<p>Specify comparison data to be used if a log entry matching the specified major and minor codes is added to the licensed internal code (LIC) log. If this text is found in the LIC log entry data fields of the watched for log entry, the watched for condition is true. If this text is not found in the LIC log entry data fields of the watched for log entry and no exit program is specified on the TRCPGM parameter, the trace function continues. If the log entry matches the specified major and minor codes and an exit program is specified on the TRCPGM parameter, but the entry data does not contain the specified text, the exit program is called to determine if the trace should continue or stop.
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*NONE</u></b></dt>
|
||
|
|
<dd>No comparison data is specified. If a LIC log entry matching the specified major and minor codes is added to the LIC log, the watched for condition is true.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>character-value</i></b></dt>
|
||
|
|
<dd>Specify the text string used to compare against the entry data of the watched for log entry. If this text is found in the LIC log entry data fields compared of a watched for log entry, the watch condition is considered to be true. This text is case sensitive. The LIC log fields which can be compared are TDE number, task name, server type, job name, user ID, job number, thread ID, exception ID, LIC module compile timestamp, LIC module offset, LIC module RU name, LIC module name, LIC module entry point name. The comparison data cannot be used to match across two fields, and can match an entire field or a substring of any field.
|
||
|
|
<p>When watching for an exception ID, all four hexadecimal digits of the exception ID must be specified. Also, the prefix MCH may be specified if you want to compare only against the exception ID field and avoid possible substring matches with the other fields.
|
||
|
|
</p>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="STRTRC.WCHTIMO"></a>
|
||
|
|
<h3>Length of time to watch (WCHTIMO)</h3>
|
||
|
|
<p>Specifies the time limit, in minutes, for watching for a message or a licensed internal code (LIC) log entry. When the specified amount of time has elapsed, the trace exit program is called (if one was specified on the TRCPGM parameter), the trace is ended, and message CPI3999 is sent to the system operator message queue.
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*NOMAX</u></b></dt>
|
||
|
|
<dd>There is no time limit for watching for a particular message or LIC log entry.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>1-43200</i></b></dt>
|
||
|
|
<dd>Specify the number of minutes that the trace will remain active while none of the watched for conditions have been met.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="STRTRC.TRCPGM"></a>
|
||
|
|
<h3>Trace program (TRCPGM)</h3>
|
||
|
|
<p>Specifies the program to be called for user-defined trace commands and procedures.
|
||
|
|
</p>
|
||
|
|
<p>The trace program will be called:
|
||
|
|
</p>
|
||
|
|
<ul>
|
||
|
|
<li>Before the application trace starts.
|
||
|
|
</li>
|
||
|
|
<li>After a match of a message identifier specified for the WCHMSG parameter, or a match of a Licensed Internal Code (LIC) log entry specified for the WCHLICLOG parameter occurs.
|
||
|
|
</li>
|
||
|
|
<li>When the time interval specified on the TRCPGMITV parameter is reached.
|
||
|
|
</li>
|
||
|
|
<li>When the length of time to watch specified on WCHTIMO parameter is reached.
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
<p>There are three input parameters and one output parameter associated with the trace program. The four parameters are required:
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<pre>
|
||
|
|
1 Trace option setting Input Char(10)
|
||
|
|
2 Reserved Input Char(10)
|
||
|
|
3 Error detected Output Char(10)
|
||
|
|
4 Comparison data Input Char(*)
|
||
|
|
</pre>
|
||
|
|
</p>
|
||
|
|
<p>Allowed values for the "Trace option setting" parameter are:
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b>*ON</b></dt>
|
||
|
|
<dd>The watch for trace facility is starting when the collection of trace information is started.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*MSGID</b></dt>
|
||
|
|
<dd>A match on a message id specified on WCHMSG parameter occurred.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*LICLOG</b></dt>
|
||
|
|
<dd>A match on a LIC log specified on the WCHLICLOG parameter occurred.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*CMPDATA</b></dt>
|
||
|
|
<dd>The major and minor code of a LIC log matched, but the comparison data did not.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*INTVAL</b></dt>
|
||
|
|
<dd>The time interval specified on TRCPGMITV parameter is elapsed.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*WCHTIMO</b></dt>
|
||
|
|
<dd>The length of time to watch specified on WCHTIMO parameter is elapsed.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p>The "Reserved" parameter must be set to blanks.
|
||
|
|
</p>
|
||
|
|
<p>Allowed values for the "Error detected" parameter are:
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b>*CONTINUE</b></dt>
|
||
|
|
<dd>The trace and the watch for trace event facility will continue running.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*STOP</b></dt>
|
||
|
|
<dd>The trace and the watch for trace event facility will be ended.
|
||
|
|
</dd>
|
||
|
|
<dt><b>*ERROR</b></dt>
|
||
|
|
<dd>Error detected by customer trace program.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p>Allowed values for the "Comparison data" parameter when *MSGID is specified for the "Trace option setting" parameter will be the following structure:
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<pre>
|
||
|
|
OFFSET TYPE FIELD
|
||
|
|
Dec Hex
|
||
|
|
0 0 BINARY(4) Length of trace information
|
||
|
|
4 4 CHAR(7) Message ID
|
||
|
|
11 B CHAR(9) Reserved
|
||
|
|
20 14 BINARY(4) Offset to comparison data
|
||
|
|
24 18 BINARY(4) Length of comparison data
|
||
|
|
* * CHAR(*) Message comparison data
|
||
|
|
</pre>
|
||
|
|
</p>
|
||
|
|
<p>Allowed values for the "Comparison data" parameter when *LICLOG or *CMPDATA is specified for the "Trace option setting" parameter will be the following structure:
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<pre>
|
||
|
|
OFFSET TYPE FIELD
|
||
|
|
Dec Hex
|
||
|
|
0 0 BINARY(4) Length of trace information
|
||
|
|
4 4 CHAR(4) LIC Log major code
|
||
|
|
8 8 CHAR(4) LIC Log minor code
|
||
|
|
12 C CHAR(8) LIC Log identifier
|
||
|
|
20 14 BINARY(4) Offset to comparison data
|
||
|
|
24 18 BINARY(4) Length of comparison data
|
||
|
|
* * CHAR(*) LIC log comparison data
|
||
|
|
</pre>
|
||
|
|
</p>
|
||
|
|
<p>Allowed values for the "Comparison data" parameter when *ON, *INTVAL or *WCHTIMO is specified for the "Trace option setting" parameter will be the following structure:
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<pre>
|
||
|
|
OFFSET TYPE FIELD
|
||
|
|
Dec Hex
|
||
|
|
0 0 BINARY(4) Length of trace information (always 4).
|
||
|
|
</pre>
|
||
|
|
</p>
|
||
|
|
<p>For more information on the trace exit program interface, refer to the System API Reference information in the iSeries Information Center at http://www.iseries.ibm.com/infocenter .
|
||
|
|
</p>
|
||
|
|
<p><b>Single values</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*NONE</u></b></dt>
|
||
|
|
<dd>No trace exit program is defined. If a watched for message or licensed internal code (LIC) log entry is added, or if the specified watch time limit is exceeded, the trace function ends.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p><b>Qualifier 1: Trace program</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><i>name</i></b></dt>
|
||
|
|
<dd>Specify the name of the trace exit program.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
<p><b>Qualifier 2: Library</b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*LIBL</u></b></dt>
|
||
|
|
<dd>All libraries in the job's library list are searched until the first match is found.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>name</i></b></dt>
|
||
|
|
<dd>Specify the name of the library where the user exit program is located.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<div> <a name="STRTRC.TRCPGMITV"></a>
|
||
|
|
<h3>Time interval (TRCPGMITV)</h3>
|
||
|
|
<p>Specifies how often the trace exit program will be called.
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b><u>*NONE</u></b></dt>
|
||
|
|
<dd>No time interval is specified. The trace exit program will not be called because a time interval has elapsed.
|
||
|
|
</dd>
|
||
|
|
<dt><b><i>1-9999</i></b></dt>
|
||
|
|
<dd>Specify the interval of time, in seconds, of how often the trace exit program will be called. This must be less than the amount of time specified for the <b>Length of time to watch (WCHTIMO)</b> parameter.
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<hr size="2" width="100%">
|
||
|
|
<div><h3><a name="STRTRC.COMMAND.EXAMPLES">Examples</a> </h3>
|
||
|
|
<p><b>Example 1: Start a Trace on Your Job</b>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<pre>
|
||
|
|
STRTRC SSNID(*GEN)
|
||
|
|
</pre>
|
||
|
|
</p>
|
||
|
|
<p>This command starts a trace on the job that called the STRTRC command. A unique trace session identifier will be generated. The session identifier will be returned in the message data of a completion message sent after the trace session starts successfully.
|
||
|
|
</p>
|
||
|
|
<p><b>Example 2: Start a Trace of Another Job</b>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<pre>
|
||
|
|
STRTRC JOB(123456/QSYS/QSYSARB) SSNID(ARBTRACE)
|
||
|
|
</pre>
|
||
|
|
</p>
|
||
|
|
<p>This command starts a new trace on the job with job name QSYSARB, job user name of QSYS, and job number of 123456. Only this one job is traced. The trace session identifier is ARBTRACE.
|
||
|
|
</p>
|
||
|
|
<p><b>Example 3: Start a Generic Job Trace</b>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<pre>
|
||
|
|
STRTRC SSNID(*GEN) JOB(*ALL/QSYS/QTVTELNET*) MAXSTG(80000)
|
||
|
|
</pre>
|
||
|
|
</p>
|
||
|
|
<p>This command starts a new trace on all jobs on the system that have a job name that begins with QTVTELNET and are running under the QSYS user profile. The maximum storage used for the trace will be 80000 kilobytes. A unique session identifier will be generated.
|
||
|
|
</p>
|
||
|
|
<p><b>Example 4: Start a Job Trace with a Filter</b>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<pre>
|
||
|
|
ADDTRCFTR FTR(MYFTR) PGMTRG(*EQ MYLIB/MYPGM *ALL *PGM *ENTRY)
|
||
|
|
STRTRC SSNID(MYTRACE)JOB(123456/MYUSER/MYJOB) TRCFTR(MYFTR)
|
||
|
|
</pre>
|
||
|
|
</p>
|
||
|
|
<p>These commands add a trace filter for MYPGM in MYLIB. When the trace is started, call/return trace records will not be collected until MYLIB/MYPGM is called. Once MYLIB/MYPGM is called, the trace will collect call/return trace records until the trace is ended.
|
||
|
|
</p>
|
||
|
|
<p><b>Example 5: Start a Job Trace with Component Defined</b>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<pre>
|
||
|
|
STRTRC JOB(123456/MYUSER/MYJOB) SSNID(MYTRACE)
|
||
|
|
TRCTYPE(*ENVVAR *VERBOSE)
|
||
|
|
</pre>
|
||
|
|
</p>
|
||
|
|
<p>This command starts a new trace on the job with job name MYJOB, job user name of MYUSER, and job number of 123456. Only this one job is traced. The trace session identifier is MYTRACE. The trace will collect call/return trace information as well as information for the ENVVAR component at VERBOSE level.
|
||
|
|
</p>
|
||
|
|
<p><b>Example 6: Start a Job Trace with Threads Selection</b>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<pre>
|
||
|
|
STRTRC JOB((123456/MYUSER/MYJOB (11111111 22222222)))
|
||
|
|
SSNID(MYTRACE)
|
||
|
|
</pre>
|
||
|
|
</p>
|
||
|
|
<p>This command starts a new trace on the job with job name MYJOB, job user name of MYUSER, and job number of 123456. Only threads 11111111 and 22222222 are traced. The trace session identifier is MYTRACE.
|
||
|
|
</p>
|
||
|
|
<p><b>Example 7: Start a Trace and Watch for a Message to End the Trace</b>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<pre>
|
||
|
|
STRTRC SSNID(*GEN) WCHMSG((MCH2804))
|
||
|
|
WCHMSGQ((*SYSOPR) (*JOBLOG))
|
||
|
|
WCHJOB((*ALL/MYUSER/MYJOBNAME))
|
||
|
|
TRCPGM(MYLIB/TRCEXTPGM)
|
||
|
|
</pre>
|
||
|
|
</p>
|
||
|
|
<p>This command starts a trace on the job that called the STRTRC command. The trace will be ended when MCH2804 message is found on the System Operator message queue or within the *ALL/MYUSER/MYJOBNAME job log. Also, MYLIB/TRCEXTPGM is specified as a trace exit program.
|
||
|
|
</p>
|
||
|
|
<p><b>Example 8: Start a Trace and Watch for a LIC Log Entry to End the Trace</b>
|
||
|
|
</p>
|
||
|
|
<p>
|
||
|
|
<pre>
|
||
|
|
STRTRC SSNID(*GEN) WCHLICLOG(('99??' 9932 MYJOBNAME))
|
||
|
|
WCHTIMO(*NOMAX)
|
||
|
|
</pre>
|
||
|
|
</p>
|
||
|
|
<p>This command starts a trace on the job that called the STRTRC command. The trace will be ended when a Licensed Internal Code (LIC) log entry that has a major code starting with 99 and a minor code of 9932 is generated on the system. Also, the LIC log information should contain the text "MYJOBNAME". *NOMAX on WCHTIMO parameter indicates that the trace will be active until the event occurs or ENDTRC command is issued manually.
|
||
|
|
</p>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
<hr size="2" width="100%">
|
||
|
|
<div><h3><a name="STRTRC.ERROR.MESSAGES">Error messages</a> </h3>
|
||
|
|
<p><b><u>*ESCAPE Messages</u></b>
|
||
|
|
</p>
|
||
|
|
<dl>
|
||
|
|
<dt><b>CPC3921</b></dt>
|
||
|
|
<dd>STRTRC session ID &1 successfully started.
|
||
|
|
</dd>
|
||
|
|
<dt><b>CPC3922</b></dt>
|
||
|
|
<dd>STRTRC session ID &1 started but some jobs not found.
|
||
|
|
</dd>
|
||
|
|
<dt><b>CPF0006</b></dt>
|
||
|
|
<dd>Errors occurred in command.
|
||
|
|
</dd>
|
||
|
|
<dt><b>CPF39C7</b></dt>
|
||
|
|
<dd>STRTRC session ID &1 already exists.
|
||
|
|
</dd>
|
||
|
|
<dt><b>CPF39C9</b></dt>
|
||
|
|
<dd>Unexpected STRTRC failure, see low-level messages.
|
||
|
|
</dd>
|
||
|
|
<dt><b>CPF39C5</b></dt>
|
||
|
|
<dd>Job name *ALL and user *ALL not allowed
|
||
|
|
</dd>
|
||
|
|
<dt><b>CPF39C6</b></dt>
|
||
|
|
<dd>Not autorized to trace with generic job users.
|
||
|
|
</dd>
|
||
|
|
<dt><b>CPF39CC</b></dt>
|
||
|
|
<dd>No active jobs found, STRTRC session not started.
|
||
|
|
</dd>
|
||
|
|
<dt><b>CPI36CE</b></dt>
|
||
|
|
<dd>Job &3/&2/&1 not found.
|
||
|
|
</dd>
|
||
|
|
<dt><b>CPF39F2</b></dt>
|
||
|
|
<dd>Cannot allocate library &1
|
||
|
|
</dd>
|
||
|
|
<dt><b>CPF98A2</b></dt>
|
||
|
|
<dd>Not authorized to &1 command.
|
||
|
|
</dd>
|
||
|
|
<dt><b>CPF39D3</b></dt>
|
||
|
|
<dd>Unable to start/end the trace.
|
||
|
|
</dd>
|
||
|
|
<dt><b>CPF39D4</b></dt>
|
||
|
|
<dd>Another trace session is already active that specified RESTRIPL(*YES).
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
</div>
|
||
|
|
<table width="100%">
|
||
|
|
<tr><td align="right"><a href="#STRTRC.Top_Of_Page">Top</a></td></tr>
|
||
|
|
</table>
|
||
|
|
</body>
|
||
|
|
</html>
|