ibm-information-center/dist/eclipse/plugins/i5OS.ic.cl_5.4.0.1/trcjob.htm

484 lines
16 KiB
HTML
Raw Normal View History

2024-04-02 14:02:31 +00:00
<!doctype html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head><META http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Trace Job (TRCJOB)</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="TRCJOB.Top_Of_Page"></a>
<h2>Trace Job (TRCJOB)</h2>
<table width="100%">
<tr>
<td valign="top" align="left"><b>Where allowed to run: </b>All environments (*ALL)<br>
<b>Threadsafe: </b>Yes
</td>
<td valign="top" align="right">
<a href="#TRCJOB.PARAMETERS.TABLE">Parameters</a><br>
<a href="#TRCJOB.COMMAND.EXAMPLES">Examples</a><br>
<a href="#TRCJOB.ERROR.MESSAGES">Error messages</a></td>
</tr>
</table>
<div> <a name="TRCJOB"></a>
<p>The Trace Job (TRCJOB) command controls traces of original program model (OPM) programs and Integrated Language Environment (ILE) procedure calls and returns that occur in the current job or in the job being serviced as a result of the Start Service Job (STRSRVJOB) command directed to that job. The command, which sets a trace on or off, can trace module flow, operating system data acquisition (including CL command traces), or both.
</p>
<p>If the Start Service Job (STRSRVJOB) command is entered before the TRCJOB command, the job that is traced is the one identified by the STRSRVJOB command.
</p>
<p>The TRCJOB command issues under the covers the STRTRC command when SET(*ON) is specified or the ENDTRC command when SET(*OFF) or SET(*END) is specified.
</p>
<p><b>Restrictions:</b>
</p>
<ol>
<li>The record format of the database output file must match the record format of the IBM-supplied output file QATRCJOB.
</li>
<li>The number of trace records processed between the start and end of the trace must not exceed one million.
</li>
<li>The Transfer Job (TFRJOB) command must not be issued while TRCJOB command is active.
</li>
<li>The following user profiles have private authorities to use the command:
<ul>
<li>QPGMR
</li>
<li>QSRV
</li>
<li>QSRVBAS
</li>
<li>QSYSOPR
</li>
<li>QRJE
</li>
</ul>
</li>
</ol>
</div>
<table width="100%">
<tr><td align="right"><a href="#TRCJOB.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div>
<h3><a name="TRCJOB.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="#TRCJOB.SET"><b>SET</b></a></td>
<td valign="top">Trace option setting</td>
<td valign="top"><b><u>*ON</u></b>, *OFF, *END</td>
<td valign="top">Optional, Positional 1</td>
</tr>
<tr>
<td valign="top"><a href="#TRCJOB.TRCTYPE"><b>TRCTYPE</b></a></td>
<td valign="top">Trace type</td>
<td valign="top"><b><u>*ALL</u></b>, *FLOW, *DATA</td>
<td valign="top">Optional, Positional 2</td>
</tr>
<tr>
<td valign="top"><a href="#TRCJOB.MAXSTG"><b>MAXSTG</b></a></td>
<td valign="top">Maximum storage to use</td>
<td valign="top">1-16000, <b><u>4096</u></b></td>
<td valign="top">Optional, Positional 3</td>
</tr>
<tr>
<td valign="top"><a href="#TRCJOB.TRCFULL"><b>TRCFULL</b></a></td>
<td valign="top">Trace full</td>
<td valign="top"><b><u>*WRAP</u></b>, *STOPTRC</td>
<td valign="top">Optional, Positional 4</td>
</tr>
<tr>
<td valign="top" rowspan="3"><a href="#TRCJOB.EXITPGM"><b>EXITPGM</b></a></td>
<td valign="top">Program to call before trace</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: Program to call before trace</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>, *CURLIB</td>
</tr><tr>
<td valign="top" rowspan="5"><a href="#TRCJOB.SLTPRC"><b>SLTPRC</b></a></td>
<td valign="top">Select procedures to trace</td>
<td valign="top">Single values: <b><u>*ALL</u></b>, *NONE<br>Other values (up to 50 repetitions): <i>Element list</i></td>
<td valign="top" rowspan="5">Optional</td>
</tr>
<tr>
<td valign="top">Element 1: Program</td>
<td valign="top">
<i>Qualified object name</i></td>
</tr>
<tr>
<td valign="top" style="padding-left:10pt">Qualifier 1: Program</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>, *CURLIB</td>
</tr><tr>
<td valign="top">Element 2: Type</td>
<td valign="top">
<b><u>*PGM</u></b>, *SRVPGM</td>
</tr>
<tr>
<td valign="top"><a href="#TRCJOB.SLTTHD"><b>SLTTHD</b></a></td>
<td valign="top">Thread ID to include</td>
<td valign="top">Single values: <b><u>*ALL</u></b>, *SELECT<br>Other values (up to 20 repetitions): <i>Hexadecimal value</i></td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top"><a href="#TRCJOB.OUTPUT"><b>OUTPUT</b></a></td>
<td valign="top">Output</td>
<td valign="top"><b><u>*PRINT</u></b>, *OUTFILE</td>
<td valign="top">Optional</td>
</tr>
<tr>
<td valign="top" rowspan="3"><a href="#TRCJOB.OUTFILE"><b>OUTFILE</b></a></td>
<td valign="top">File to receive output</td>
<td valign="top"><i>Qualified object name</i></td>
<td valign="top" rowspan="3">Optional</td>
</tr>
<tr>
<td valign="top">Qualifier 1: File to receive output</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>, *CURLIB</td>
</tr><tr>
<td valign="top" rowspan="3"><a href="#TRCJOB.OUTMBR"><b>OUTMBR</b></a></td>
<td valign="top">Output member options</td>
<td valign="top"><i>Element list</i></td>
<td valign="top" rowspan="3">Optional</td>
</tr>
<tr>
<td valign="top">Element 1: Member to receive output</td>
<td valign="top">
<i>Name</i>, <b><u>*FIRST</u></b></td>
</tr>
<tr>
<td valign="top">Element 2: Replace or add records</td>
<td valign="top">
<b><u>*REPLACE</u></b>, *ADD</td>
</tr>
</table>
<table width="100%">
<tr><td align="right"><a href="#TRCJOB.Top_Of_Page">Top</a></td></tr>
</table>
</div>
<div> <a name="TRCJOB.SET"></a>
<h3>Trace option setting (SET)</h3>
<p>Specifies whether the collection of trace records starts or stops.
</p>
<dl>
<dt><b><u>*ON</u></b></dt>
<dd>The collection of trace records is started.
</dd>
<dt><b>*OFF</b></dt>
<dd>The collection of trace records is stopped, and the trace records are written to the spooled printer file or output file.
</dd>
<dt><b>*END</b></dt>
<dd>The collection of trace records is stopped, and all existing trace records are deleted. No spooled printer file is created.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#TRCJOB.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="TRCJOB.TRCTYPE"></a>
<h3>Trace type (TRCTYPE)</h3>
<p>Specifies the type of trace data to store in a trace file.
</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 control.
</dd>
<dt><b>*DATA</b></dt>
<dd>The data is provided at predefined trace points within the operating system stored in trace records. This includes trace records for the CL commands that have run.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#TRCJOB.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="TRCJOB.MAXSTG"></a>
<h3>Maximum storage to use (MAXSTG)</h3>
<p>Specifies the maximum amount of storage used for collected trace records.
</p>
<dl>
<dt><b><u>4096</u></b></dt>
<dd>A maximum of 4096 kilobytes of storage is used.
</dd>
<dt><b><i>1-16000</i></b></dt>
<dd>Specify the maximum amount of storage, in kilobytes, used to store trace records. (One kilobyte equals 1024 bytes.)
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#TRCJOB.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="TRCJOB.TRCFULL"></a>
<h3>Trace full (TRCFULL)</h3>
<p>Specifies whether the trace records are to wrap (replace oldest records with new records) or to set trace off when all of the storage has been used.
</p>
<dl>
<dt><b><u>*WRAP</u></b></dt>
<dd>When the trace file 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 file is full of trace records.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#TRCJOB.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="TRCJOB.EXITPGM"></a>
<h3>Program to call before trace (EXITPGM)</h3>
<p>This parameter is no longer used.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#TRCJOB.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="TRCJOB.SLTPRC"></a>
<h3>Select procedures to trace (SLTPRC)</h3>
<p>This parameter is no longer used.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#TRCJOB.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="TRCJOB.SLTTHD"></a>
<h3>Thread ID to include (SLTTHD)</h3>
<p>Specifies a list of up to twenty threads whose calls and returns are included in the trace. Only trace records for the specified thread identifiers are included.
</p>
<p><b>Single values</b>
</p>
<dl>
<dt><b><u>*ALL</u></b></dt>
<dd>All threads calls and returns are included in the trace.
</dd>
<dt><b>*SELECT</b></dt>
<dd>A list of thread identifiers is shown from which the user can select up to twenty whose trace records are to be included.
</dd>
</dl>
<p><b>Other values</b>
</p>
<dl>
<dt><b><i>hexadecimal-value</i></b></dt>
<dd>Specify the identifiers of up to twenty threads whose trace records are to be included.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#TRCJOB.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="TRCJOB.OUTPUT"></a>
<h3>Output (OUTPUT)</h3>
<p>Specifies whether the output from the command is printed with the job's spooled output or sent to a database file.
</p>
<dl>
<dt><b><u>*PRINT</u></b></dt>
<dd>The output is printed with the job's spooled output.
</dd>
</dl>
<dl>
<dt><b>*OUTFILE</b></dt>
<dd>The output is directed to the database file specified for the <b>File to receive output (OUTFILE)</b> parameter.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#TRCJOB.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="TRCJOB.OUTFILE"></a>
<h3>File to receive output (OUTFILE)</h3>
<p>Specifies the database file to which the output of the command is directed. If the file does not exist, this command creates a database file in the specified library. If the file is created, the public authority for the file is the same as the create authority specified for the library in which the file is created. Use the Display Library Description (DSPLIBD) command to show the library's create authority.
</p>
<p><b>Qualifier 1: File to receive output</b>
</p>
<dl>
<dt><b><i>name</i></b></dt>
<dd>Specify the name of the database file to which the command output is directed.
</dd>
</dl>
<p><b>Qualifier 2: Library</b>
</p>
<dl>
<dt><b><u>*LIBL</u></b></dt>
<dd>The library list is used to locate the file. If the file is not found, one is created in the current library. If no current library exists, the file will be created in the QGPL library.
</dd>
<dt><b>*CURLIB</b></dt>
<dd>The current library for the thread is used to locate the file. If no library is specified as the current library for the thread, the QGPL library is used.
</dd>
</dl>
<dl>
<dt><b><i>name</i></b></dt>
<dd>Specify the name of the library to be searched.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#TRCJOB.Top_Of_Page">Top</a></td></tr>
</table>
<div> <a name="TRCJOB.OUTMBR"></a>
<h3>Output member options (OUTMBR)</h3>
<p>Specifies the name of the database file member that receives the output of the command.
</p>
<p><b>Element 1: Member to receive output</b>
</p>
<dl>
<dt><b><u>*FIRST</u></b></dt>
<dd>The first member in the file receives the output. If OUTMBR(*FIRST) is specified and the member does not exist, the system creates a member with the name of the file specified for the <b>File to receive output (OUTFILE)</b> parameter. If the member already exists, you have the option to add new records to the end of the existing member or clear the member and then add the new records.
</dd>
</dl>
<dl>
<dt><b><i>name</i></b></dt>
<dd>Specify the name of the file member that receives the output. If it does not exist, the system creates it.
</dd>
</dl>
<p><b>Element 2: Replace or add records</b>
</p>
<dl>
<dt><b><u>*REPLACE</u></b></dt>
<dd>The system clears the existing member and adds the new records.
</dd>
</dl>
<dl>
<dt><b>*ADD</b></dt>
<dd>The system adds the new records to the end of the existing records.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#TRCJOB.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div><h3><a name="TRCJOB.COMMAND.EXAMPLES">Examples</a> </h3>
<p><b>Example 1: Tracing Flow of Control</b>
</p>
<p>
<pre>
TRCJOB TRCTYPE(*FLOW) MAXSTG(40)
</pre>
</p>
<p>This command traces the flow of the current job. Trace records are collected for each OPM program and ILE procedure call and return that occurs in the job. The trace file contains 40K of storage and wraps (oldest records are replaced by new records) if that amount of storage is filled with trace records.
</p>
<p><b>Example 2: Stopping the Trace Operation</b>
</p>
<p>
<pre>
TRCJOB SET(*OFF) OUTPUT(*OUTFILE)
OUTFILE(QGPL/TRCJOB) OUTMBR(TRCDTA)
</pre>
</p>
<p>This command stops the trace and directs the output to the database file QGPL/TRCJOB. The output is directed to the member TRCDTA.
</p>
<p><b>Example 3: Tracing One Thread</b>
</p>
<p>
<pre>
TRCJOB SET(*ON) SLTTHD(00000001)
</pre>
</p>
<p>This command traces only the specified thread of the current job.
</p>
</div>
<table width="100%">
<tr><td align="right"><a href="#TRCJOB.Top_Of_Page">Top</a></td></tr>
</table>
<hr size="2" width="100%">
<div><h3><a name="TRCJOB.ERROR.MESSAGES">Error messages</a> </h3>
<p><b><u>*ESCAPE Messages</u></b>
</p>
<dl>
<dt><b>CPF2C94</b></dt>
<dd>Error occurred during OUTFILE processing. Trace stopped.
</dd>
<dt><b>CPF2C95</b></dt>
<dd>Trace already active.
</dd>
<dt><b>CPF2C96</b></dt>
<dd>Trace already off.
</dd>
<dt><b>CPF3510</b></dt>
<dd>User exit program not found in specified library.
</dd>
<dt><b>CPF3511</b></dt>
<dd>Trace already active.
</dd>
<dt><b>CPF3512</b></dt>
<dd>Trace already off.
</dd>
<dt><b>CPF3513</b></dt>
<dd>Cannot set Trace Off, trace started from another job.
</dd>
<dt><b>CPF3521</b></dt>
<dd>Not enough storage for the trace table.
</dd>
<dt><b>CPF3530</b></dt>
<dd>Conflicting entries in index QSERVICE.
</dd>
<dt><b>CPF3542</b></dt>
<dd>Job not traced because it is being serviced.
</dd>
<dt><b>CPF3548</b></dt>
<dd>Serviced job completed running.
</dd>
<dt><b>CPF3675</b></dt>
<dd>Cannot allocate QSYS library.
</dd>
<dt><b>CPF3909</b></dt>
<dd>Service command will not be processed.
</dd>
<dt><b>CPF3918</b></dt>
<dd>Service request canceled.
</dd>
<dt><b>CPF3925</b></dt>
<dd>Cannot open file &amp;1.
</dd>
<dt><b>CPF3936</b></dt>
<dd>Job being serviced ended before trace started.
</dd>
<dt><b>CPF3950</b></dt>
<dd>Error message &amp;2 received for file &amp;1. Request ended.
</dd>
<dt><b>CPF3951</b></dt>
<dd>File &amp;1 cannot be overridden by file name &amp;2.
</dd>
<dt><b>CPF3957</b></dt>
<dd>Not authorized to use exit program library &amp;2.
</dd>
<dt><b>CPF3969</b></dt>
<dd>Error during close of file &amp;1. Output may not be complete.
</dd>
<dt><b>CPF6611</b></dt>
<dd>Error occurred during OUTFILE processing, trace ended.
</dd>
<dt><b>CPF6801</b></dt>
<dd>Command prompting ended when user pressed &amp;1.
</dd>
<dt><b>CPF9810</b></dt>
<dd>Library &amp;1 not found.
</dd>
<dt><b>CPF98A4</b></dt>
<dd>Thread restrictions exist for some other process.
</dd>
</dl>
</div>
<table width="100%">
<tr><td align="right"><a href="#TRCJOB.Top_Of_Page">Top</a></td></tr>
</table>
</body>
</html>