184 lines
10 KiB
HTML
184 lines
10 KiB
HTML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html lang="en-us" xml:lang="en-us">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<meta name="security" content="public" />
|
|
<meta name="Robots" content="index,follow" />
|
|
<meta http-equiv="PICS-Label" content='(PICS-1.1 "http://www.icra.org/ratingsv02.html" l gen true r (cz 1 lz 1 nz 1 oz 1 vz 1) "http://www.rsac.org/ratingsv01.html" l gen true r (n 0 s 0 v 0 l 0) "http://www.classify.org/safesurf/" l gen true r (SS~~000 1))' />
|
|
<meta name="DC.Type" content="reference" />
|
|
<meta name="DC.Title" content="Trace class" />
|
|
<meta name="abstract" content="The Trace class allows the Java program to log trace points and diagnostic messages. This information helps reproduce and diagnose problems." />
|
|
<meta name="description" content="The Trace class allows the Java program to log trace points and diagnostic messages. This information helps reproduce and diagnose problems." />
|
|
<meta name="DC.Relation" scheme="URI" content="progtips.htm" />
|
|
<meta name="copyright" content="(C) Copyright IBM Corporation 2006" />
|
|
<meta name="DC.Rights.Owner" content="(C) Copyright IBM Corporation 2006" />
|
|
<meta name="DC.Format" content="XHTML" />
|
|
<meta name="DC.Identifier" content="trace" />
|
|
<meta name="DC.Language" content="en-us" />
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
|
<!-- US Government Users Restricted Rights -->
|
|
<!-- Use, duplication or disclosure restricted by -->
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
|
<link rel="stylesheet" type="text/css" href="./ibmdita.css" />
|
|
<link rel="stylesheet" type="text/css" href="./ic.css" />
|
|
<title>Trace class</title>
|
|
</head>
|
|
<body id="trace"><a name="trace"><!-- --></a>
|
|
<!-- Java sync-link --><script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
|
<h1 class="topictitle1">Trace class</h1>
|
|
<div><p>The Trace class allows the Java™ program to log trace points and diagnostic
|
|
messages. This information helps reproduce and diagnose problems.</p>
|
|
<div class="section"><p><a href="javadoc/com/ibm/as400/access/Trace.html#NAVBAR_TOP">Trace</a> class</p>
|
|
<div class="note"><span class="notetitle">Note:</span> You can also set tracing by using
|
|
the <a href="systemproperties.htm#systemproperties__traceprops">trace
|
|
system properties</a>.</div>
|
|
<p>The Trace class logs the following categories
|
|
of information:</p>
|
|
|
|
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" width="100%" frame="border" border="1" rules="all"><thead align="left"><tr class="tablemainheaderbar"><th valign="top" width="50%" id="d0e36">Information category</th>
|
|
<th valign="top" width="50%" id="d0e38">Description</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody><tr><td valign="top" width="50%" headers="d0e36 ">Conversion</td>
|
|
<td valign="top" width="50%" headers="d0e38 ">Logs character set conversions between Unicode and code pages. This
|
|
category is used only by the IBM<sup>®</sup> Toolbox for Java classes.</td>
|
|
</tr>
|
|
<tr><td valign="top" width="50%" headers="d0e36 ">Datastream</td>
|
|
<td valign="top" width="50%" headers="d0e38 ">Logs the data that flows between the iSeries™ and the Java program.
|
|
This category is used only by the IBM Toolbox for Java classes.</td>
|
|
</tr>
|
|
<tr><td valign="top" width="50%" headers="d0e36 ">Diagnostic</td>
|
|
<td valign="top" width="50%" headers="d0e38 ">Logs state information.</td>
|
|
</tr>
|
|
<tr><td valign="top" width="50%" headers="d0e36 ">Error</td>
|
|
<td valign="top" width="50%" headers="d0e38 ">Logs additional errors that cause an exception.</td>
|
|
</tr>
|
|
<tr><td valign="top" width="50%" headers="d0e36 ">Information</td>
|
|
<td valign="top" width="50%" headers="d0e38 ">Traces the flow through a program.</td>
|
|
</tr>
|
|
<tr><td valign="top" width="50%" headers="d0e36 ">PCML</td>
|
|
<td valign="top" width="50%" headers="d0e38 ">This category is used to determine how PCML interprets the data that
|
|
is sent to and from the server.</td>
|
|
</tr>
|
|
<tr><td valign="top" width="50%" headers="d0e36 ">Proxy</td>
|
|
<td valign="top" width="50%" headers="d0e38 ">This category is used by IBM Toolbox for Java classes to log data flow between the
|
|
client and the proxy server.</td>
|
|
</tr>
|
|
<tr><td valign="top" width="50%" headers="d0e36 ">Warning</td>
|
|
<td valign="top" width="50%" headers="d0e38 ">Logs information about errors the program was able to recover from.</td>
|
|
</tr>
|
|
<tr><td valign="top" width="50%" headers="d0e36 ">All</td>
|
|
<td valign="top" width="50%" headers="d0e38 ">This category is used to enable or disable tracing for all of the above
|
|
categories at once. Trace information cannot be directly logged to this
|
|
category.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<p>The IBM Toolbox
|
|
for Java classes
|
|
also use the trace categories. When a Java program enables logging, IBM Toolbox for Java information
|
|
is included with the information that is recorded by the application.</p>
|
|
<p><strong>You
|
|
can enable the trace for a single category or a set of categories</strong>. Once
|
|
the categories are selected, use the <a href="javadoc/com/ibm/as400/access/Trace.html#SETTRACEON(BOOLEAN)"> setTraceOn</a> method to turn tracing on and off. Data is
|
|
written to the log using the <a href="javadoc/com/ibm/as400/access/Trace.html#LOG(INT, JAVA.LANG.STRING)"> log</a> method.</p>
|
|
<p><strong>You can send trace data for different
|
|
components to separate logs.</strong> Trace data, by default, is written to the
|
|
default log. Use component tracing to write application-specific trace data
|
|
to a separate log or standard output. By using component tracing, you can
|
|
easily separate trace data for a specific application from other data.</p>
|
|
<p><strong>Excessive
|
|
logging can impact performance.</strong> Use the <a href="javadoc/com/ibm/as400/access/Trace.html#ISTRACEON()"> isTraceOn</a> method to query the current state of the trace.
|
|
Your Java program
|
|
can use this method to determine whether it builds the trace record before
|
|
it calls the log method. Calling the log method when logging is off is not
|
|
an error, but it takes more time.</p>
|
|
<p><strong>The default is to write log information
|
|
to standard out.</strong> To redirect the log to a file, call the <a href="javadoc/com/ibm/as400/access/Trace.html#SETFILENAME(JAVA.LANG.STRING)"> setFileName()</a> method from your Java application.
|
|
In general, this works only for Java applications because most browsers
|
|
do not give applets access to write to the local file system.</p>
|
|
<p><strong>Logging
|
|
is off by default.</strong> Java programs provide a way for the user
|
|
to turn on logging so that it is easy to enable logging. For example, the
|
|
application can parse for a command line parameter that indicates which category
|
|
of data is logged. The user can set this parameter when log information is
|
|
needed.</p>
|
|
</div>
|
|
<div class="section"><h4 class="sectiontitle">Examples</h4><div class="note"><span class="notetitle">Note:</span> Read the <a href="codedisclaimer.htm#codedisclaimer">Code
|
|
example disclaimer</a> for important legal information.</div>
|
|
<p>The following
|
|
examples show how to use the Trace class.</p>
|
|
</div>
|
|
<div class="section" id="trace__traceex1"><a name="trace__traceex1"><!-- --></a><p><strong>Example Using setTraceOn() and writing data to
|
|
a log by using the log method</strong></p>
|
|
<pre> // Enable diagnostic, information, and warning logging.
|
|
Trace.setTraceDiagnosticOn(true);
|
|
Trace.setTraceInformationOn(true);
|
|
Trace.setTraceWarningOn(true);
|
|
|
|
// Turn tracing on.
|
|
Trace.setTraceOn(true);
|
|
|
|
// ... At this point in the Java program, write to the log.
|
|
Trace.log(Trace.INFORMATION, "Just entered class xxx, method xxx");
|
|
|
|
// Turning tracing off.
|
|
Trace.setTraceOn(false);</pre>
|
|
</div>
|
|
<div class="section"><p id="trace__traceex2"><a name="trace__traceex2"><!-- --></a><strong>Example: Using Trace</strong></p>
|
|
<p>In the following
|
|
code, Method 2 is the preferable way to use Trace.</p>
|
|
<pre> // Method 1 - build a trace record
|
|
// then call the log method and let the trace class determine if the
|
|
// data should be logged. This will work but will be slower than the
|
|
// following code.
|
|
String traceData = new String("Just entered class xxx, data = ");
|
|
traceData = traceData + data + "state = " + state;
|
|
Trace.log(Trace.INFORMATION, traceData);
|
|
|
|
// Method 2 - check the log status before building the information to
|
|
// log. This is faster when tracing is not active.
|
|
if (Trace.isTraceOn() && Trace.isTraceInformationOn())
|
|
{
|
|
String traceData = new String("just entered class xxx, data = ");
|
|
traceData = traceData + data + "state = " + state;
|
|
Trace.log(Trace.INFORMATION, traceData);
|
|
}</pre>
|
|
</div>
|
|
<div class="section" id="trace__traceex3"><a name="trace__traceex3"><!-- --></a><p><strong>Example: Using component tracing</strong></p>
|
|
<pre> // Create a component string. It is more efficient to create an
|
|
// object than many String literals.
|
|
String myComponent1 = "com.myCompany.xyzComponent";
|
|
String myComponent2 = "com.myCompany.abcComponent";
|
|
|
|
// Send IBM Toolbox for Java and the component trace data each to separate files.
|
|
// The trace will contain all trace information, while each
|
|
// component log file will only contain trace information specific to
|
|
// that component. If a Trace file is not specified, all trace data
|
|
// will go to standard out with the component specified in front of
|
|
// each trace message.
|
|
|
|
// Trace.setFileName("c:\\bit.bucket");
|
|
// Trace.setFileName(myComponent1, "c:\\Component1.log");
|
|
// Trace.setFileName(myComponent2, "c:\\Component2.log");
|
|
|
|
Trace.setTraceOn(true); // Turn trace on.
|
|
Trace.setTraceInformationOn(true); // Enable information messages.
|
|
|
|
// Log component specific trace data or general IBM Toolbox for Java
|
|
// trace data.
|
|
|
|
Trace.setFileName("c:\\bit.bucket");
|
|
Trace.setFileName(myComponent1, "c:\\Component1.log");</pre>
|
|
</div>
|
|
</div>
|
|
<div>
|
|
<div class="familylinks">
|
|
<div class="parentlink"><strong>Parent topic:</strong> <a href="progtips.htm" title="This section features a variety of tips that can help you use IBM Toolbox for Java.">Tips for programming</a></div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html> |