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

695 lines
19 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">
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
<title>Add Problem Log Entry (QsxAddProblemLogEntry) 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. -->
<!-- QSXADDPL SCRIPT A converted by B2H R4.1 (346) (CMS) by KENTALA -->
<!-- at RCHVMW2 on 2 Oct 1998 at 12:16:07 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!--File Edited by Kersten Nov 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>Add Problem Log Entry (QsxAddProblemLogEntry) API</h2>
<div class="box" style="width: 80%;">
<br>
&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%">Handle</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Key structures</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Array of Pointers</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Number of keys</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">4</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;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Service Program: QSXSRUPL<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Add Problem Log Entry (QsxAddProblemLogEntry) API adds information to an
existing problem log entry.</p>
<p>The API supports the following data types:</p>
<ul>
<li>Keys 2001-2009 (field replaceable unit (FRU) entries) can be added to the
problem log entry.</li>
<li>Keys 4001 and 4002 (supporting data) entries can be added. Do not add
duplicate information because checking is not performed.</li>
<li>Key 6001 (history information) can be added.</li>
<li>Key 7001 (PTF ID) can be added to a problem log entry. If the PTF entry
already exists, an error is signalled.</li>
</ul>
<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>Handle</strong></dt>
<dd>INPUT; BINARY(4)
<p>An identifier that associates the problem log services started by the Start
Problem Log Services API.</p>
</dd>
<dt><strong>Key structures</strong></dt>
<dd>INPUT; ARRAY of POINTERS
<p>An array of pointers that has the address of each key that contains data to
be written into the problem log. The number of pointers passed in the array
must equal the value passed by the Number of keys parameter. Keys not supported
for the Add Problem Log Entry API cause error messages to be sent to the
caller.</p>
</dd>
<dt><strong>Number of keys</strong></dt>
<dd>INPUT; BINARY(4)
<p>Number of keys passed to the API.</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></p>
</dd>
</dl>
<br>
<h3><a name="HDRADDRULE">Rules for Key Usage</a></h3>
<p>Key 1 (problem log ID) is required to identify the problem log entry to
process.</p>
<p>Data can be added to an existing problem log entry with the Add Problem Log
Entry API. The types of data that may be added with this API are:</p>
<ul>
<li>Keys 2001-2009 (FRU entries)</li>
<li>Supporting data entries (keys 4001 and 4002 (supporting data)</li>
<li>Key 6001 (history information)</li>
<li>Key 7001 (PTF ID)</li>
</ul>
<p>The remaining data contained in a problem can be altered using the Change
API. More information on the above keys can be found in <a href=
"pmkeygroups.htm">Key Groups for Problem Log APIs.</a></p>
<br>
<h4>Keys for Adding FRU Records</h4>
<p>A FRU, field replaceable unit, entry defines an object that may have a
specific machine-detected problem. FRUs have been broken into 9 types and
represented by keys 2001 through 2009.</p>
<p>The types are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top">2001</td>
<td align="left" valign="top">Device FRU type</td>
</tr>
<tr>
<td align="left" valign="top">2002</td>
<td align="left" valign="top">Code FRU type</td>
</tr>
<tr>
<td align="left" valign="top">2003</td>
<td align="left" valign="top">Media FRU type</td>
</tr>
<tr>
<td align="left" valign="top">2004</td>
<td align="left" valign="top">User FRU type</td>
</tr>
<tr>
<td align="left" valign="top">2005</td>
<td align="left" valign="top">FRU name</td>
</tr>
<tr>
<td align="left" valign="top">2006</td>
<td align="left" valign="top">Attached FRU</td>
</tr>
<tr>
<td align="left" valign="top">2007</td>
<td align="left" valign="top">Configuration FRU</td>
</tr>
<tr>
<td align="left" valign="top">2008</td>
<td align="left" valign="top">General FRU</td>
</tr>
<tr>
<td align="left" valign="top">2009</td>
<td align="left" valign="top">Channel attached FRU</td>
</tr>
</table>
<br>
<p>In addition, a FRU or list of FRUs are associated with a problem based upon
an analysis class. The analysis class implies the amount or type of analysis
that has been done on the problem. FRUs are associated with a problem within
the context of a class.</p>
<p>The classes of FRUs are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top">1</td>
<td align="left" valign="top">Point of failure</td>
</tr>
<tr>
<td align="left" valign="top">2</td>
<td align="left" valign="top">Partial isolation</td>
</tr>
<tr>
<td align="left" valign="top">3</td>
<td align="left" valign="top">Isolation</td>
</tr>
<tr>
<td align="left" valign="top">4</td>
<td align="left" valign="top">Verification</td>
</tr>
<tr>
<td align="left" valign="top">5</td>
<td align="left" valign="top">Recovery</td>
</tr>
<tr>
<td align="left" valign="top">6</td>
<td align="left" valign="top">Answer</td>
</tr>
</table>
<br>
<p>To add FRUs for a class of FRUs, the problem log entry must be identified,
the class must be chosen, and the data must be added. These three actions need
to be done for each FRU type. FRUs may be used in any combination, to add data
about individual failing elements to a maximum of 21 FRUs per class.</p>
<p>This API adds FRU entries to the bottom of the list. If they need to be
maintained in probability order, follow these steps:</p>
<ul>
<li>Retrieve the group using the Retrieve Problem Log Entry API.</li>
<li>Modify the FRU records or append additional FRUs to the original list.</li>
<li>Delete the existing FRU entries of that class using the Delete Problem Log
Entry API.</li>
<li>Add the new or updated FRU list using the Add Problem Log Entry API.</li>
</ul>
<br>
<h4>Keys for Adding Supporting Data</h4>
<p>The addition of supporting data is not restricted. Any number of spooled or
data base files can be associated with a problem log entry. Duplicate records
are allowed. If you add a file twice, it is listed twice.</p>
<p>To add supporting data, define the type of record to be added using keys
4001 and 4002 (supporting data). They can be added in any combination.</p>
<br>
<h4>Keys for Adding History Data</h4>
<p>The addition of history data, or events, is restricted because specific
events can occur only when the problem is in a specific status. Some history
data types are applicable to specific problem log types. Any number of events
can be associated with a problem log entry. Duplicate records are allowed since
many events can be repeated. Events are added in the sequence that you supply
them on the API call. The API makes no attempt to put them in order.</p>
<p>To add a history entry, use key 6001 (history information) to supply the
needed data to reflect the action that was taken. If you are adding supporting
data, you can add it in any combination. The time the event is added is entered
by the API.</p>
<p>The history types are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top">0</td>
<td align="left" valign="top">Problem entry closed. Only applicable when the
problem has been closed. Once this status is set, the problem can only be
retrieved.</td>
</tr>
<tr>
<td align="left" valign="top">1</td>
<td align="left" valign="top">Problem entry opened. Can only be used when the
problem is initially opened.</td>
</tr>
<tr>
<td align="left" valign="top">2</td>
<td align="left" valign="top">Service request received. Only applicable when a
problem is received from another system.</td>
</tr>
<tr>
<td align="left" valign="top">3</td>
<td align="left" valign="top">Opened by an alert. Only applicable when the
problem is opened due to an alert.</td>
</tr>
<tr>
<td align="left" valign="top">4</td>
<td align="left" valign="top">Problem analyzed. Applicable each time a problem
is analyzed.</td>
</tr>
<tr>
<td align="left" valign="top">5</td>
<td align="left" valign="top">Verification test ran. Applicable each time a
problem is verified.</td>
</tr>
<tr>
<td align="left" valign="top">6</td>
<td align="left" valign="top">Recovery procedure ran. Applicable each time
recovery is run.</td>
</tr>
<tr>
<td align="left" valign="top">7</td>
<td align="left" valign="top">Prepared to report. Applicable each time a
problem is prepared to be sent to a service provider.</td>
</tr>
<tr>
<td align="left" valign="top">8</td>
<td align="left" valign="top">Service request sent. Applicable only when a
problem is sent to another system. This implies that the service request was
sent, but the service provider has no solution to the problem.</td>
</tr>
<tr>
<td align="left" valign="top">9</td>
<td align="left" valign="top">Problem answered. Applicable only when a problem
is sent to another system. This implies that the service request was sent, and
the service provider has a solution to the problem.</td>
</tr>
<tr>
<td align="left" valign="top">10</td>
<td align="left" valign="top">Response sent. Implies that a reply has been
received from a service provider.</td>
</tr>
<tr>
<td align="left" valign="top">11</td>
<td align="left" valign="top">Reported by voice. Used when a problem is
reported manually.</td>
</tr>
<tr>
<td align="left" valign="top">12</td>
<td align="left" valign="top">Fixes transmitted. Implies that fixes have been
sent to a service requester.</td>
</tr>
<tr>
<td align="left" valign="top">13</td>
<td align="left" valign="top">A change request was submitted for this
problem.</td>
</tr>
<tr>
<td align="left" valign="top">14</td>
<td align="left" valign="top">The change request submitted for this problem has
ended.</td>
</tr>
<tr>
<td align="left" valign="top">15</td>
<td align="left" valign="top">Fix verified. Applicable each time a problem is
verified.</td>
</tr>
<tr>
<td align="left" valign="top">16</td>
<td align="left" valign="top">Remote analysis. Only applicable when a problem
has been analyzed by a remote service representative.</td>
</tr>
<tr>
<td align="left" valign="top">17</td>
<td align="left" valign="top">Remote verification ran. Only applicable when
this system has been used to analyze a problem on another system.</td>
</tr>
<tr>
<td align="left" valign="top">18</td>
<td align="left" valign="top">Remote recovery ran. Only applicable when this
system has been used to perform recovery on another system.</td>
</tr>
<tr>
<td align="left" valign="top">19</td>
<td align="left" valign="top">Alert created. Only applicable when the system
created an alert for this problem.</td>
</tr>
<tr>
<td align="left" valign="top">20</td>
<td align="left" valign="top">APAR created. Only applicable when APAR data is
created during analysis.</td>
</tr>
<tr>
<td align="left" valign="top">21</td>
<td align="left" valign="top">APAR data collected. Only applicable when APAR
data is collected during analysis.</td>
</tr>
<tr>
<td align="left" valign="top">22</td>
<td align="left" valign="top">APAR data restored. Only applicable when APAR
data is restored during analysis.</td>
</tr>
<tr>
<td align="left" valign="top">23</td>
<td align="left" valign="top">APAR data deleted. Only applicable when APAR data
is deleted during analysis.</td>
</tr>
<tr>
<td align="left" valign="top">24</td>
<td align="left" valign="top">Changed by CHGPRB. Only applicable when the
problem was changed by the CHGPRB command or the QsxChangeProblemLogEntry
API.</td>
</tr>
<tr>
<td align="left" valign="top">25</td>
<td align="left" valign="top">Deleted by DLTPRB. Only applicable when the
problem was changed by the DLTPRB command or QsxDeleteProblemLogEntry API.</td>
</tr>
<tr>
<td align="left" valign="top">26</td>
<td align="left" valign="top">This problem has occurred multiple times.</td>
</tr>
<tr>
<td align="left" valign="top">27</td>
<td align="left" valign="top">Status changed. Only applicable when querying the
status of a problem that has been reported to a service provider.</td>
</tr>
<tr>
<td align="left" valign="top">28</td>
<td align="left" valign="top">Status query sent. Only applicable when querying
the status of a problem that has been reported to a service provider.</td>
</tr>
<tr>
<td align="left" valign="top">29</td>
<td align="left" valign="top">Automatic problem analysis has completed
successfully.</td>
</tr>
<tr>
<td align="left" valign="top">30</td>
<td align="left" valign="top">Auto-PAR is not complete; the SRC flag is off.
Problem analysis did not occur because the SRC was turned off.</td>
</tr>
<tr>
<td align="left" valign="top">31</td>
<td align="left" valign="top">Auto-PAR not complete, submit job to QSYSWRK
failed.</td>
</tr>
<tr>
<td align="left" valign="top">32</td>
<td align="left" valign="top">Auto-PAR failed. Problem analysis failed because
an unknown problem occurred.</td>
</tr>
<tr>
<td align="left" valign="top">33</td>
<td align="left" valign="top">Auto-Notify complete. Problem was sent
automatically.</td>
</tr>
<tr>
<td align="left" valign="top">34</td>
<td align="left" valign="top">Auto-Notify not complete, SRC flag is off.
Problem was not sent automatically, the SRC was turned off.</td>
</tr>
<tr>
<td align="left" valign="top">35</td>
<td align="left" valign="top">An attempt to automatically send the problem
failed.</td>
</tr>
<tr>
<td align="left" valign="top">36</td>
<td align="left" valign="top">Auto-Notify failed.</td>
</tr>
<tr>
<td align="left" valign="top">37</td>
<td align="left" valign="top">Problem analysis failed.</td>
</tr>
</table>
<br>
<p>See <a href="../rzal2/rzal2kickoff.htm">Getting started with iSeries</a> for
more information about SRCs.</p>
<br>
<h4>Keys for Adding PTF Entry</h4>
<p>PTF entries can be added to the problem log at any time. Duplicate PTF
records are not allowed and signal an exception condition. To ensure
uniqueness, the PTF identifier and the product data are required.</p>
<p>To add a PTF record, use key 7001 (PTF ID) to add the data required. The PTF
entry is added to the bottom of existing text.</p>
<p>To get the PTF records in a specific order, the records must be retrieved,
sorted and then replaced after the existing PTF records are deleted.</p>
<p>PTF entries can be created using *ONLY*PRODUCT** as the constant for Product
ID and *ONLY as the constant for version, release, and modification level.</p>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<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">CPF3C1E E</td>
<td width="85%" valign="top">Required parameter &amp;1 omitted.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C90 E</td>
<td align="left" 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">CPF3CF2 E</td>
<td align="left" valign="top">Error(s) occurred during running of &amp;1
API.</td>
</tr>
<tr>
<td align="left" valign="top">CPF7AAB E</td>
<td align="left" valign="top">Problem &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C4D D</td>
<td align="left" valign="top">Length &amp;1 for key &amp;2 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C82 D</td>
<td align="left" valign="top">Key &amp;1 not valid for API &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C86 D</td>
<td align="left" valign="top">Required key &amp;1 not specified.</td>
</tr>
<tr>
<td align="left" valign="top">CPD7A82 D</td>
<td align="left" valign="top">Value not valid for key &amp;1. (char
string)</td>
</tr>
<tr>
<td align="left" valign="top">CPD7A83 D</td>
<td align="left" valign="top">Value not valid for key &amp;1. (integer)</td>
</tr>
<tr>
<td align="left" valign="top">CPD7A88 D</td>
<td align="left" valign="top">Incorrect DBCS field format found.</td>
</tr>
<tr>
<td align="left" valign="top">CPD7A8A D</td>
<td align="left" valign="top">Key value &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF7A89 E</td>
<td align="left" valign="top">Incorrect handle for this activation.</td>
</tr>
<tr>
<td align="left" valign="top">CPF7A8A E</td>
<td align="left" valign="top">Problem log services not started.</td>
</tr>
<tr>
<td align="left" valign="top">CPF7AA7 E</td>
<td align="left" valign="top">Problem &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9821 E</td>
<td align="left" valign="top">Not authorized to program &amp;1 in library
&amp;2.</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">CPFA320 E</td>
<td align="left" valign="top">Pointer parameter is null.</td>
</tr>
</table>
<hr>
API introduced: V3R1
<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>