ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/qpdloger.htm

545 lines
14 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">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>Log Software Error (QPDLOGER) API</title>
<!-- Begin Header Records ========================================== -->
<!-- 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. -->
<!-- QPDLOGER SCRIPT A converted by B2H R4.1 (346) (CMS) by KENTALA -->
<!-- at RCHVMW2 on 2 Oct 1998 at 13:33:20 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!--File Edited April 2001 -->
<!--End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a>
<!-- Java sync-link -->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<h2>Log Software Error (QPDLOGER) API</h2>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Required Parameter Group:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">1</td>
<td align="left" valign="top" width="50%">Suspected program name</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Detection ID</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(12)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Message reference key</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(4)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Point of failure</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Print job log</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(1)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Data items</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Data item offset and length</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Array of Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">Number of data items</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">9</td>
<td align="left" valign="top">Object name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Array of Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="left" valign="top">Number of object names</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">11</td>
<td align="left" valign="top">Error code</td>
<td align="left" valign="top">I/O</td>
<td align="left" valign="top">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Optional Parameter:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">12</td>
<td align="left" valign="top" width="50%">ILE module name</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(10)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Conditional; see <a href="#usage_notes">Usage Notes</a>.<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Log Software Error (QPDLOGER) API allows a program to report a software
problem to the local iSeries server and provide the data needed to resolve the
problem. When this API is called, any error data provided is spooled to one or
more spooled files, a symptom string is created, an entry is created in the
problem log, and a message is sent to the QSYSOPR message queue indicating that
a software error has been detected.</p>
<p>Error data can be provided on the API call by using the data item offset and
length and object name parameters.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>API Public Authority</em></dt>
<dd>*USE</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Suspected program name</strong></dt>
<dd>INPUT; CHAR(10)
<p>The name of the program in which the error is suspected. Service programs
are not supported. The Report Software Error (QpdReportSoftwareError) API must
be used to report a problem against a service program. If a service program is
specified on the QPDLOGER API, the service program will not be found and the
suspected program will be used instead.</p>
<p>Valid values are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*SAME</em></td>
<td align="left" valign="top">The reporting program.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*PRV</em></td>
<td align="left" valign="top">The program that called the reporting
program.</td>
</tr>
<tr>
<td align="left" valign="top"><em>program name</em></td>
<td align="left" valign="top">The name of the suspected program.</td>
</tr>
</table>
<br>
<p>The suspected program name is included in the symptom string (as
F/<em>name</em>) created when this API is called.</p>
</dd>
<dt><strong>Detection ID</strong></dt>
<dd>INPUT; CHAR(12)
<p>A message ID or other value defined by the reporting program that further
identifies the problem. This value is included in the symptom string (as
MSG<em>detectionid</em>) created when this API is called.</p>
</dd>
<dt><strong>Message reference key</strong></dt>
<dd>INPUT; CHAR(4)
<p>The message key associated with the message that is being reported (if a
message is being reported). This parameter is used to verify that message
CPF9999 (a function check) was not caused by a damage exception (CPF81xx). If
message CPF9999 is caused by a damage exception, the problem will not be
reported. This value is ignored if it does not contain a key for a CPF9999
message.</p>
<p><strong>Note:</strong> The detection ID should not contain blanks. The API
ignores characters after the first blank.</p>
</dd>
<dt><strong>Point of failure</strong></dt>
<dd>INPUT; BINARY(4)
<p>A return code, statement number, or other value defined by the reporting
program that assists in locating the problem. This value is converted to zoned
decimal and included in the symptom string (as RC<em>nnnnnnnn</em>) created
when this API is called.</p>
</dd>
<dt><strong>Print job log</strong></dt>
<dd>INPUT; CHAR(1)
<p>Whether the job log and other job information is to be spooled to a spooled
file.</p>
<p>Valid values are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>Y</em></td>
<td align="left" valign="top">Print the job log and job information.</td>
</tr>
<tr>
<td align="left" valign="top"><em>N</em></td>
<td align="left" valign="top">Do not print the job log and job
information.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Data items</strong></dt>
<dd>INPUT; CHAR(*)
<p>The data to be spooled.</p>
</dd>
<dt><strong>Data item offset and length</strong></dt>
<dd>INPUT; ARRAY of CHAR(*)
<p>An array of the offsets to and lengths of the data items to be spooled to a
spooled file. The array can contain up to 32 elements.</p>
<p>Each element has the following structure:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>Data offset</em></td>
<td align="left" valign="top">BINARY(4).</td>
</tr>
<tr>
<td align="left" valign="top"></td>
<td align="left" valign="top">The offset to the data item from the start of the
data.</td>
</tr>
<tr>
<td align="left" valign="top"><em>Data length</em></td>
<td align="left" valign="top">BINARY(4).</td>
</tr>
<tr>
<td align="left" valign="top"></td>
<td align="left" valign="top">The length of this data item (must be greater
than 0).</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Number of data items</strong></dt>
<dd>INPUT; BINARY(4)
<p>The number of elements in the array of data item offsets and lengths. The
number must be between 0 and 32, inclusive.</p>
</dd>
<dt><strong>Object name</strong></dt>
<dd>INPUT; ARRAY of CHAR(*)
<p>An array of object names whose contents are to be spooled to a spooled file.
The array can contain up to 32 elements.</p>
<p>Each element has the following structure:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>Object name</em></td>
<td align="left" valign="top">CHAR(30).</td>
</tr>
<tr>
<td align="left" valign="top"></td>
<td align="left" valign="top">The name of the object to be spooled.</td>
</tr>
<tr>
<td align="left" valign="top"><em>Library</em></td>
<td align="left" valign="top">CHAR(30).</td>
</tr>
<tr>
<td align="left" valign="top"></td>
<td align="left" valign="top">The library in which the object resides.<br>
<br>
Valid values for the library name are:
<table cellpadding="5">
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td align="left" valign="top">The job's current library.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">The library list.</td>
</tr>
<tr>
<td align="left" valign="top"><em>library name</em></td>
<td align="left" valign="top">The specific library that contains the
object.</td>
</tr>
</table>
</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Object type</strong></dt>
<dd>CHAR(10). The object type. For a complete list of the available
object types, see <a href="../rbam6/rbam6objecttypes.htm">Object Types</a> in the CL topic.<br>
<br>
</dd>
<dt><strong>Number of object names</strong></dt>
<dd>INPUT; BINARY(4)
<p>The number of object names in the array of object names. The number must be
between 0 and 32, inclusive.</p>
</dd>
<dt><strong>Error code</strong></dt>
<dd>I/O; CHAR(*)
<p>The structure in which to return error information. For the format of the
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>. If this
parameter is omitted, diagnostic and escape messages are issued to the
application.</p>
</dd>
</dl>
<br>
<h3>Optional Parameter</h3>
<dl>
<dt><strong>ILE module name</strong></dt>
<dd>INPUT; CHAR(10)
<p>The name of the integrated language environment (ILE) module in which the
error is suspected. This value is included in the symptom string created when
this API is called.</p>
</dd>
</dl>
<br>
<h3><a name="usage_notes">Usage Notes</a></h3>
<p>When this API runs within a threaded job, no problem log entry is created.
When the API is called, the following occurs:</p>
<ul>
<li>Any error data that is provided is spooled to one or more spooled
files.</li>
<li>A symptom string is created.</li>
<li>A message is sent to the job log and to the QSYSOPR message queue, which
indicates that a software error has been detected.</li>
</ul>
<p>Error data can be provided on the call to the API by using the data item
offset and length parameters. (No object dumping support is available).</p>
<p>Also, dump job output is provided to help with problem determination.</p>
<p>The following parameters are ignored:</p>
<ul>
<li>Print job log</li>
<li>Object name</li>
<li>Number of object names</li>
</ul>
<p>Current API users do not have to make any changes.</p>
<br>
<h3>Error Messages</h3>
<table cellpadding="5">
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td width="15%" valign="top">CPF3C90 E</td>
<td width="85%" valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF1 E</td>
<td align="left" valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF93C0 E</td>
<td align="left" valign="top">Software error logging not active.</td>
</tr>
<tr>
<td align="left" valign="top">CPF93C2 E</td>
<td align="left" valign="top">&amp;1 is not a valid number of data items.</td>
</tr>
<tr>
<td align="left" valign="top">CPF93C3 E</td>
<td align="left" valign="top">&amp;1 is not a valid number of object
names.</td>
</tr>
<tr>
<td align="left" valign="top">CPF93C4 E</td>
<td align="left" valign="top">Error already logged.</td>
</tr>
<tr>
<td align="left" valign="top">CPF93C5 E</td>
<td align="left" valign="top">Software problem logging (QPDLOGER) API error
occurred.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPI93B2 I</td>
<td align="left" valign="top">Software problem data for &amp;4 has been
detected.</td>
</tr>
<tr>
<td align="left" valign="top">CPI93CA I</td>
<td align="left" valign="top">Suspected program &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPI93CB I</td>
<td align="left" valign="top">Point-of-failure value not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPI93CC I</td>
<td align="left" valign="top">Object &amp;1 in library &amp;2 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPI93CF I</td>
<td align="left" valign="top">Data length or data offset not valid.</td>
</tr>
</table>
<br>
<hr>
API introduced: V2R3
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#top_of_page">Top</a> | <a href=
"pm1.htm">Problem Management API list</a><br>
<a href=
"aplist.htm">APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>