690 lines
18 KiB
HTML
690 lines
18 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>Create Problem Log Entry (QsxCreateProblemLogEntry) 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. -->
|
|
<!-- QSXCRTPL SCRIPT A converted by B2H R4.1 (346) (CMS) by KENTALA -->
|
|
<!-- at RCHVMW2 on 2 Oct 1998 at 12:52:23 -->
|
|
<!--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>Create Problem Log Entry (QsxCreateProblemLogEntry) API</h2>
|
|
|
|
<div class="box" style="width: 80%;">
|
|
<br>
|
|
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">Problem log ID</td>
|
|
<td align="left" valign="top">Output</td>
|
|
<td align="left" valign="top">Char(40)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">3</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">4</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">5</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>
|
|
Service Program Name: QSXSRVPL<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: No<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The Create Problem Log Entry (QsxCreateProblemLogEntry) API creates a
|
|
problem log entry and adds the information provided to the problem log files
|
|
using keys. Key 1 (problem log ID) is returned to the user that is required for
|
|
other API operations.</p>
|
|
|
|
<p>The API allows a problem to be created with a status of OPENED, READY, or
|
|
PREPARED. The difference to the user is that the amount of data increases as
|
|
the problem goes from OPENED to PREPARED.</p>
|
|
|
|
<p>The types of problems that may be created are:</p>
|
|
|
|
<ul>
|
|
<li>Machine-detected (problem type 1)</li>
|
|
|
|
<li>User-perceived (problem type 2)</li>
|
|
|
|
<li>PTF orders (problem type 3)</li>
|
|
|
|
<li>User-perceived remote hardware or software problems (problem type 4)</li>
|
|
|
|
<li>Application-detected (problem type 5)</li>
|
|
|
|
<li>Client machine-detected (problem type 6)</li>
|
|
|
|
<li>Client user-detected (problem type 7)</li>
|
|
|
|
<li>User-created general (problem type 8)</li>
|
|
</ul>
|
|
|
|
<p>The keys provided to create a problem are checked for validity and
|
|
applicability to the problem log entry in two ways:</p>
|
|
|
|
<ul>
|
|
<li>Applicability of the type</li>
|
|
|
|
<li>Applicability of the field</li>
|
|
</ul>
|
|
|
|
<p>The fields are checked to verify that they are not null. Some keys allow the
|
|
user to control them (key control). Keys without "key control" support require
|
|
all fields to be filled. Fields not flagged are ignored.(The existence of the
|
|
data is verified; NOT whether or not the data is valid. The problem log APIs do
|
|
not check the validity of the data.) Operations that are unsupported or not
|
|
valid, such as creating a problem in SENT status or not providing all dependent
|
|
keys, result in a diagnostic message for each infraction found and an exception
|
|
or an error notification defining it.</p>
|
|
|
|
<p>The key fields are checked before the problem log entry is created and an
|
|
error is signalled if any required key fields are null.</p>
|
|
|
|
<p>If the maximum number of problem log entries has been reached for this
|
|
particular date (99999), CPF392F E is signaled.</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>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 1 (problem log ID)</strong></dt>
|
|
|
|
<dd>OUTPUT: CHAR(40)
|
|
|
|
<p>This parameter contains the problem log identifier after the problem is
|
|
created. If this parameter is omitted, no problem log ID is returned.</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 parameter 4, Number of keys.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Number of keys</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4)
|
|
|
|
<p>Defines the number of keys that are being 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>Format of the Keys</h3>
|
|
|
|
<p>See <a href="pmkeygroups.htm">Key Groups for Problem Log APIs</a> for a
|
|
description of the keys.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRCRTRULE">Rules for Key Usage</a></h3>
|
|
|
|
<p>To create a problem log entry, specific data is required. The amount of data
|
|
varies depending on the status of the problem log. This section defines the
|
|
data required for each problem type for statuses OPENED and READY. Problems in
|
|
OPENED or READY status may be amplified with the status of PREPARED. The
|
|
supplemental data required for this is defined once and is applicable to either
|
|
OPENED or READY.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h4>General Keys For Problem Log Entry Data</h4>
|
|
|
|
<p>The minimum key data for all problems types is:</p>
|
|
|
|
<ul>
|
|
<li>Key 1 (problem log ID)
|
|
|
|
<p>This key must contain one of the following:</p>
|
|
|
|
<ul>
|
|
<li>Problem log identifier if the problem was created on another system</li>
|
|
|
|
<li>The value "*LOCAL" to indicate that the problem is a local one.</li>
|
|
</ul>
|
|
|
|
<br>
|
|
</li>
|
|
|
|
<li>Key 2 (problem type)
|
|
|
|
<p>This defines the type of problem log entry being created.</p>
|
|
</li>
|
|
|
|
<li>Key 3 (problem status)
|
|
|
|
<p>Defines the status to which the entry will be set. Three values are
|
|
allowed:</p>
|
|
|
|
<ul>
|
|
<li>OPENED. Create a problem in OPENED status.</li>
|
|
|
|
<li>READY. Create a problem in READY status.</li>
|
|
|
|
<li>PREPARED. Create a problem in READY or OPENED status and add supplemental
|
|
data required for PREPARED status.</li>
|
|
</ul>
|
|
|
|
<br>
|
|
</li>
|
|
|
|
<li>Key 5 (problem origin system)
|
|
|
|
<ul>
|
|
<li>Required if key 1 (problem log ID) is not *LOCAL.</li>
|
|
|
|
<li>Prohibited if key 1 (problem log ID) is *LOCAL.</li>
|
|
</ul>
|
|
|
|
<br>
|
|
</li>
|
|
|
|
<li>Key 6 (operational data)
|
|
|
|
<ul>
|
|
<li>If key 1 (problem log ID) is *LOCAL, the Received from system field is
|
|
prohibited. If it is not *LOCAL, the Received from system field is
|
|
required.</li>
|
|
|
|
<li>If key 3 (problem status) indicates the problem is to be in PREPARED status
|
|
the Prepared for system field is required otherwise it is prohibited.</li>
|
|
|
|
<li>The Date and time added field is automatically added by the API.</li>
|
|
|
|
<li>The Date and time closed field is automatically added when the problem is
|
|
closed.</li>
|
|
</ul>
|
|
|
|
<br>
|
|
</li>
|
|
|
|
<li>Key 1002 (problem description message) or key 3001 (text entry), type 1.
|
|
|
|
<p>Either or both are acceptable. Key 3001 is used if both are supplied. When
|
|
both key 1002 and key 3001 are added, only key 3001 is available through the
|
|
command interface, but both key 1002 and key 3001 can be retrieved through
|
|
APIs. When the problem type is machine detected, key 1002 is required.</p>
|
|
</li>
|
|
|
|
<li>Key 5001 (contact information)
|
|
|
|
<p>Required if key 1 (problem log ID) is not *LOCAL. Used to enter contact data
|
|
for the remote system.</p>
|
|
</li>
|
|
|
|
<li>Key 6001 (history information)
|
|
|
|
<p>This information defines the type of create action. One or more history
|
|
entries are allowed. At least one event is required.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>In addition, the following information is needed based on the problem
|
|
type.</p>
|
|
|
|
<h4>Keys for Creating Problem Type 1</h4>
|
|
|
|
<p>Machine detected problems (problem type 1) use the following keys:</p>
|
|
|
|
<p>Data for OPENED status are:</p>
|
|
|
|
<ul>
|
|
<li>Key 1002 (problem description message)
|
|
|
|
<p>Required.</p>
|
|
</li>
|
|
|
|
<li>Key 1003 (problem creation data)
|
|
|
|
<p>Required.</p>
|
|
</li>
|
|
|
|
<li>Key 1005 (failing device)
|
|
|
|
<p>Required to define the device and/or code that is failing.</p>
|
|
</li>
|
|
|
|
<li>Keys 2001-2009 (FRU entries)
|
|
|
|
<p>At least one key of the range 2001 to 2009 is required. The keys may be
|
|
provided in any order but will be stored in probability of fix order, with the
|
|
highest probability FRU record being stored first and the least probability FRU
|
|
record being stored last.</p>
|
|
</li>
|
|
|
|
<li>Keys 4001 and 4002 (supporting data)
|
|
|
|
<p>Optional. Used to define the supporting data that will be associated with
|
|
the problem. Multiple entries are allowed.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<ul>
|
|
<li>Data for READY status are:</li>
|
|
</ul>
|
|
|
|
<p>Post analysis data must be added to a machine detected problem to achieve
|
|
READY status. This data is in addition to the data added to achieve OPENED
|
|
status. Data for READY status are:</p>
|
|
|
|
<ul>
|
|
<li>Key 1004 (reporting device)
|
|
|
|
<p>Defines the machine that will be reported to a service provider as the
|
|
failing machine.</p>
|
|
</li>
|
|
|
|
<li>Key 1005 (failing device) This provides a description of the resource that
|
|
caused the problem.</li>
|
|
|
|
<li>Key 1006 (reporting code)
|
|
|
|
<p>Defines the program/product that is failing. This is required if the highest
|
|
probability FRU is key 2002 (code FRU type).</p>
|
|
</li>
|
|
|
|
<li>Key 1007 (problem analysis data)
|
|
|
|
<p>Required</p>
|
|
</li>
|
|
|
|
<li>Key 1010 (symptom string)
|
|
|
|
<p>Required</p>
|
|
</li>
|
|
|
|
<li>Keys 2001-2009 (FRU entries)
|
|
|
|
<p>At least one key of the range 2001 to 2009 is required. The keys may be
|
|
provided in any order but will be stored in probability of fix order, with the
|
|
highest probability FRU record being stored first and the least probability FRU
|
|
record being stored last.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<br>
|
|
|
|
|
|
<h4>Keys for Creating Problem Type 2</h4>
|
|
|
|
<p>User-perceived hardware or software problems (problem type 2) can be created
|
|
in READY and READY - PREPARED status only. These problems require data similar
|
|
to machine-detected problems (problem type 1) with the following
|
|
exceptions:</p>
|
|
|
|
<ul>
|
|
<li>Key group 2000 (FRU records) is prohibited.</li>
|
|
|
|
<li>Key group 3000 (problem type 1) is required if 1002 is not used.</li>
|
|
</ul>
|
|
|
|
<br>
|
|
|
|
|
|
<h4>Keys for Creating Problem Type 3</h4>
|
|
|
|
<p>PTF orders (problem type 3) are created in READY and READY - PREPARED status
|
|
only and use the following:</p>
|
|
|
|
<ul>
|
|
<li>Key group 1000 (problem description entries), except key 1002 (problem
|
|
description message), is prohibited.</li>
|
|
|
|
<li>Key group 2000 (FRU records) is prohibited.</li>
|
|
|
|
<li>Key group 4000 (supported data records) is prohibited.</li>
|
|
|
|
<li>Key 1011 is optional.</li>
|
|
|
|
<li>Key group 7001 is required.</li>
|
|
</ul>
|
|
|
|
<br>
|
|
|
|
|
|
<h4>Keys for Creating Problem Type 4</h4>
|
|
|
|
<p>User-perceived remote hardware or software problems (problem type 4) can be
|
|
created in READY and READY - PREPARED status only. These problems require data
|
|
similar to machine-detected problems (problem type 1) with the following
|
|
exceptions:</p>
|
|
|
|
<ul>
|
|
<li>Key group 2000 (FRU records) is prohibited.</li>
|
|
|
|
<li>Key group 4000 (supported data records) is prohibited.</li>
|
|
</ul>
|
|
|
|
<br>
|
|
|
|
|
|
<h4>Keys for Creating Problem Type 5</h4>
|
|
|
|
<p>Application detected problems (problem type 5) are used to enter problems
|
|
automatically detected during the execution of a program. They can be created
|
|
in READY and PREPARED status only. These problems require data similar to
|
|
machine-detected problems (problem type 1) with the following exceptions:</p>
|
|
|
|
<ul>
|
|
<li>Key group 2000 (FRU records) is optional.
|
|
|
|
<p>If key group 2000 (FRU records) is specified only key 2002 (code FRU type)
|
|
is permitted.</p>
|
|
</li>
|
|
|
|
<li>Key group 4000 (supported data records) is optional.
|
|
|
|
<p>Key group 4000 (supported data records) may be used to identify APAR data
|
|
that is associated with the problem.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<br>
|
|
|
|
|
|
<h4>Keys for Creating Problem Types 6 and 7</h4>
|
|
|
|
<p>Client machine-detected (problem type 6) and user-created (problem type 7)
|
|
problems are used to create problem log entries for an attached client. These
|
|
problems are generated in the READY status. The data requirements are:</p>
|
|
|
|
<ul>
|
|
<li>Key 1012 is required and must be LOGONLY on the Add Problem Log Entry
|
|
API.</li>
|
|
|
|
<li>Key 1013 is required.</li>
|
|
|
|
<li>Key 1003 (problem creation data)</li>
|
|
|
|
<li>Key 1010</li>
|
|
|
|
<li>Keys 1001, 1002, 1003</li>
|
|
|
|
<li>Keys 4001 and 4002 are optional</li>
|
|
|
|
<li>Key 3001 (text entry) is optional</li>
|
|
|
|
<li>Key 6001 (history information) is optional</li>
|
|
</ul>
|
|
|
|
<br>
|
|
|
|
|
|
<h4>Keys for Creating Problem Type 8</h4>
|
|
|
|
<p>User-created general problems (problem type 8) are used to add data of a
|
|
general nature, that is not applicable to the types already defined. The entry
|
|
can be created in READY and READY - PREPARED status only. The data requirements
|
|
are:</p>
|
|
|
|
<ul>
|
|
<li>Key group 1000 (problem description entries) is prohibited.</li>
|
|
|
|
<li>Key 1002 (problem description message) can be used to create text for the
|
|
problem description of the message.</li>
|
|
|
|
<li>Key 3001 (text entry) type 2 is required to provide a detailed description
|
|
of the problem.
|
|
|
|
<p>Key group 4000 (supported data records) can be used to identify data that is
|
|
associated with the problem.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<br>
|
|
|
|
|
|
<h4><a name="HDRPREPARE">Data for PREPARED Status</a></h4>
|
|
|
|
<p>The supplemental data needed to move a problem from OPENED or READY status
|
|
to PREPARED status are:</p>
|
|
|
|
<ul>
|
|
<li>Key 6 (operational data)</li>
|
|
|
|
<li>Key control</li>
|
|
|
|
<li>Prepared for system
|
|
|
|
<p>Required to define the system that this problem will be sent to.</p>
|
|
</li>
|
|
|
|
<li>Key 1001 (problem severity)</li>
|
|
|
|
<li>Optional. Default is none.</li>
|
|
|
|
<li>Ignored for PTF Order (problem type 3).</li>
|
|
|
|
<li>Key 1011 (PTF media selection)
|
|
|
|
<p>Optional. Default is the contact data base. Typically this is the tape
|
|
device type and model or a description of the media type on which PTFs are
|
|
delivered if the distribution size exceeds a predefined transmit size
|
|
limit.</p>
|
|
</li>
|
|
|
|
<li>Key 5001 (contact information)
|
|
|
|
<p>Optional. Used to override local service contact information.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<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 &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 &1
|
|
API.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF7AAB E</td>
|
|
<td align="left" valign="top">Problem &1 not found.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C4D D</td>
|
|
<td align="left" valign="top">Length &1 for key &2 not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C82 D</td>
|
|
<td align="left" valign="top">Key &1 not valid for API &2.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C86 D</td>
|
|
<td align="left" valign="top">Required key &1 not specified.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPD7A82 D</td>
|
|
<td align="left" valign="top">Value not valid for key &1. (char
|
|
string)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPD7A83 D</td>
|
|
<td align="left" valign="top">Value not valid for key &1. (integer)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPD7A87 D</td>
|
|
<td align="left" valign="top">Key &1 may be added only once.</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 &1 is not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPD7A8B D</td>
|
|
<td align="left" valign="top">Length of data 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 &1 not found.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF9821 E</td>
|
|
<td align="left" valign="top">Not authorized to program &1 in library
|
|
&2.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF9872 E</td>
|
|
<td align="left" valign="top">Program or service program &1 in library
|
|
&2 ended. Reason code &3.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFA320 E</td>
|
|
<td align="left" valign="top">Pointer parameter is null.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<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>
|
|
|