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

585 lines
17 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>Register Filter Notifications (QNMRGFN) 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. -->
<!-- COMM4 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2DCIJB at -->
<!-- RCHVMW2 on 1 Jun 1999 at 17:32:50 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!--File Edited December, 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 type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<h2>Register Filter Notifications (QNMRGFN) API</h2>
<div class="box" style="width: 60%;">
<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%">Qualified filter name</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(20)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Filter type</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">3</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;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Register Filter Notifications (QNMRGFN) API registers a filter to send notifications for a specific event to a data queue. This data queue is defined in the *SNDDTAQ action entry field of the registered filter. These notification records are the asynchronous output of this API. All CL filter commands can be performed against a registered filter.</p>
<p>A filter can only be registered once. If a registered filter is being registered again, an error is returned. No checking is done to see if the registered filter is the same as another filter, such as an active user filter.</p>
<p>A check to prevent duplicate notifications for a single event is made when the registered filters are processed. If a notification record for a registered filter is a duplicate of another notification record (such as an active user filter) the registered filter is not processed.</p>
<p>If an error occurs in accessing a registered filter, or while enqueuing the notification record, the filter is automatically deregistered, and an informational message (CPI91D5) is sent to the system operator (QSYSOPR) message queue. This prevents the system from encountering the error again.</p>
<p>The registration for a filter remains active after the initial program load of a system. This ensures that a product receives all notifications. A product should register its filter either when the product is installed or when the product is started. A product should check to see that its filter is registered at its start-up time to ensure that its filter was not automatically deregistered. You do not have to deregister a filter to change the filter.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Registered Filter</em></dt>
<dd>*USE</dd>
<dt><em>Registered Filter Library</em></dt>
<dd>*USE</dd>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Qualified filter name</strong></dt>
<dd>INPUT; CHAR(20)
<p>The qualified filter name that is being registered. The first 10 characters are the filter name, and the last 10 characters are the library name. Special values *LIBL and *CURLIB are not supported for the library name.</p>
</dd>
<dt><strong>Filter type</strong></dt>
<dd>INPUT; CHAR(10)
<p>The type of filter. The following filter types are specified in the format field.</p>
<p>Special values supported are:</p>
<table cellpadding="3">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*ALR</em></td>
<td valign="top">Alert filter. (See <a href="#HDRALR">Alert Filter</a> for details about the format.)</td>
</tr>
<tr>
<td align="left" valign="top"><em>*PRB</em></td>
<td valign="top">Problem log filter. (See <a href="#HDRPRB">Problem Log Filter</a> for details about the format.)</td>
</tr>
</table>
<br>
</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="HDRDTAQ">Format of Registered Filter Data Queue Notification</a></h3>
<p>See <a href="#HDRRFNFD">Field Descriptions</a> for descriptions of the fields in this format.</p>
<table border width="80%">
<tr>
<th align="center" valign="bottom" colspan="2">Offset</th>
<th align="left" valign="bottom" rowspan="2">Type</th>
<th align="left" valign="bottom" rowspan="2">Field</th>
</tr>
<tr>
<th align="center" valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">0</td>
<td align="center" valign="top" width="10%">0</td>
<td align="left" valign="top" width="20%">CHAR(10)</td>
<td align="left" valign="top" width="60%">Notification name</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">10</td>
<td align="center" valign="top" width="10%">A</td>
<td align="left" valign="top" width="20%">CHAR(2)</td>
<td align="left" valign="top" width="60%">Function code</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">12</td>
<td align="center" valign="top" width="10%">C</td>
<td align="left" valign="top" width="20%">CHAR(8)</td>
<td align="left" valign="top" width="60%">Format</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">20</td>
<td align="center" valign="top" width="10%">14</td>
<td align="left" valign="top" width="20%">CHAR(10)</td>
<td align="left" valign="top" width="60%">Filter name</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">30</td>
<td align="center" valign="top" width="10%">1E</td>
<td align="left" valign="top" width="20%">CHAR(10)</td>
<td align="left" valign="top" width="60%">Filter library name</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">40</td>
<td align="center" valign="top" width="10%">28</td>
<td align="left" valign="top" width="20%">CHAR(10)</td>
<td align="left" valign="top" width="60%">Group name</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">50</td>
<td align="center" valign="top" width="10%">32</td>
<td align="left" valign="top" width="20%">CHAR(8)</td>
<td align="left" valign="top" width="60%">Timestamp</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">58</td>
<td align="center" valign="top" width="10%">3A</td>
<td align="left" valign="top" width="20%">CHAR(22)</td>
<td align="left" valign="top" width="60%">Reserved</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">80</td>
<td align="center" valign="top" width="10%">50</td>
<td align="left" valign="top" width="20%">CHAR(*)</td>
<td align="left" valign="top" width="60%">Event-specific notification data</td>
</tr>
</table>
<p>The types of event-specific notification data used by the format field are described below.</p>
<br>
<h3><a name="HDRALR">Alert Filter</a></h3>
<p>See <a href="#HDRRFNFD">Field Descriptions</a> for descriptions of the fields in this format.</p>
<table border width="80%">
<tr>
<th align="center" valign="bottom" colspan="2">Offset</th>
<th align="left" valign="bottom" rowspan="2">Type</th>
<th align="left" valign="bottom" rowspan="2">Field</th>
</tr>
<tr>
<th align="center" valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">80</td>
<td align="center" valign="top" width="10%">50</td>
<td align="left" valign="top" width="20%">CHAR(512)</td>
<td align="left" valign="top" width="60%">Alert major vector</td>
</tr>
</table>
<br><br>
<h3><a name="HDRPRB">Problem Log Filter</a></h3>
<p>See <a href="#HDRRFNFD">Field Descriptions</a> for descriptions of the fields in this format.</p>
<table border width="80%">
<tr>
<th align="center" valign="bottom" colspan="2">Offset</th>
<th align="left" valign="bottom" rowspan="2">Type</th>
<th align="left" valign="bottom" rowspan="2">Field</th>
</tr>
<tr>
<th align="center" valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">80</td>
<td align="center" valign="top" width="10%">50</td>
<td align="left" valign="top" width="20%">CHAR(30)</td>
<td align="left" valign="top" width="60%">Problem ID</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">110</td>
<td align="center" valign="top" width="10%">6E</td>
<td align="left" valign="top" width="20%">CHAR(1)</td>
<td align="left" valign="top" width="60%">Last event</td>
</tr>
<tr>
<td align="center" valign="top" width="10%">111</td>
<td align="center" valign="top" width="10%">6F</td>
<td align="left" valign="top" width="20%">CHAR(8)</td>
<td align="left" valign="top" width="60%">Last event timestamp</td>
</tr>
</table>
<br><br>
<h3><a name="HDRRFNFD">Field Descriptions</a></h3>
<p><strong>Alert major vector.</strong> The actual alert that caused the notification.</p>
<p><strong>Event-specific notification data.</strong> Data specific to the event identified in the function code. The data is in the format specified by the format variable.</p>
<p><strong>Filter library name.</strong> The library that contains the filter.</p>
<p><strong>Filter name.</strong> The name of the filter that sent the notification.</p>
<p><strong>Format.</strong> The format of the event-specific data of a problem log filter. Valid values are:</p>
<table cellpadding="3">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>RGFN0100</em></td>
<td valign="top">Alert filter</td>
</tr>
<tr>
<td align="left" valign="top"><em>RGFN0200</em></td>
<td valign="top">Problem log filter</td>
</tr>
</table>
<p><strong>Function code.</strong> The event that caused the notification. Valid values are:</p>
<table cellpadding="3">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>01</em></td>
<td valign="top">Alert event</td>
</tr>
<tr>
<td align="left" valign="top"><em>02</em></td>
<td valign="top">Problem log event</td>
</tr>
</table>
<p><strong>Group name.</strong> The group into which the event was filtered.</p>
<p><strong>Last event.</strong> The last event performed on the problem. Valid values are:</p>
<table cellpadding="3">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>01</em></td>
<td valign="top">Problem entry opened</td>
</tr>
<tr>
<td align="left" valign="top"><em>02</em></td>
<td valign="top">Service request received code</td>
</tr>
<tr>
<td align="left" valign="top"><em>03</em></td>
<td valign="top">Opened by alert</td>
</tr>
<tr>
<td align="left" valign="top"><em>10</em></td>
<td valign="top">Problem analyzed</td>
</tr>
<tr>
<td align="left" valign="top"><em>11</em></td>
<td valign="top">Verification test ran</td>
</tr>
<tr>
<td align="left" valign="top"><em>12</em></td>
<td valign="top">Recovery procedure ran</td>
</tr>
<tr>
<td align="left" valign="top"><em>20</em></td>
<td valign="top">Prepared to report</td>
</tr>
<tr>
<td align="left" valign="top"><em>21</em></td>
<td valign="top">Service request sent</td>
</tr>
<tr>
<td align="left" valign="top"><em>22</em></td>
<td valign="top">Problem answered</td>
</tr>
<tr>
<td align="left" valign="top"><em>23</em></td>
<td valign="top">Response sent</td>
</tr>
<tr>
<td align="left" valign="top"><em>24</em></td>
<td valign="top">Reported by voice</td>
</tr>
<tr>
<td align="left" valign="top"><em>25</em></td>
<td valign="top">Fixes transmitted</td>
</tr>
<tr>
<td align="left" valign="top"><em>26</em></td>
<td valign="top">Change request submitted</td>
</tr>
<tr>
<td align="left" valign="top"><em>27</em></td>
<td valign="top">Change request ended</td>
</tr>
<tr>
<td align="left" valign="top"><em>30</em></td>
<td valign="top">Fix verified</td>
</tr>
<tr>
<td align="left" valign="top"><em>41</em></td>
<td valign="top">Remote analysis</td>
</tr>
<tr>
<td align="left" valign="top"><em>42</em></td>
<td valign="top">Remote verification ran</td>
</tr>
<tr>
<td align="left" valign="top"><em>43</em></td>
<td valign="top">Remote recovery ran</td>
</tr>
<tr>
<td align="left" valign="top"><em>50</em></td>
<td valign="top">Alert created</td>
</tr>
<tr>
<td align="left" valign="top"><em>51</em></td>
<td valign="top">APAR created</td>
</tr>
<tr>
<td align="left" valign="top"><em>52</em></td>
<td valign="top">APAR data collected</td>
</tr>
<tr>
<td align="left" valign="top"><em>54</em></td>
<td valign="top">APAR data restored</td>
</tr>
<tr>
<td align="left" valign="top"><em>55</em></td>
<td valign="top">APAR data deleted</td>
</tr>
<tr>
<td align="left" valign="top"><em>60</em></td>
<td valign="top">Changed by CHGPRB</td>
</tr>
<tr>
<td align="left" valign="top"><em>61</em></td>
<td valign="top">Deleted by DLTPRB</td>
</tr>
<tr>
<td align="left" valign="top"><em>62</em></td>
<td valign="top">Recurring problem</td>
</tr>
<tr>
<td align="left" valign="top"><em>70</em></td>
<td valign="top">Status changed</td>
</tr>
<tr>
<td align="left" valign="top"><em>71</em></td>
<td valign="top">Status query sent</td>
</tr>
<tr>
<td align="left" valign="top"><em>80</em></td>
<td valign="top">Auto-PAR done</td>
</tr>
<tr>
<td align="left" valign="top"><em>81</em></td>
<td valign="top">Auto-PAR not done - SRC OFF</td>
</tr>
<tr>
<td align="left" valign="top"><em>82</em></td>
<td valign="top">Auto-PAR not done - SBMJOB</td>
</tr>
<tr>
<td align="left" valign="top"><em>83</em></td>
<td valign="top">Auto-PAR failed</td>
</tr>
<tr>
<td align="left" valign="top"><em>86</em></td>
<td valign="top">Auto-notify done</td>
</tr>
<tr>
<td align="left" valign="top"><em>87</em></td>
<td valign="top">Auto-notify not done - SRC off</td>
</tr>
<tr>
<td align="left" valign="top"><em>88</em></td>
<td valign="top">Auto-notify not done - SBMJOB</td>
</tr>
<tr>
<td align="left" valign="top"><em>89</em></td>
<td valign="top">Auto-notify failed</td>
</tr>
<tr>
<td align="left" valign="top"><em>99</em></td>
<td valign="top">Problem entry closed</td>
</tr>
</table>
<p><strong>Last event timestamp.</strong> The time at which the last event was performed.</p>
<p><strong>Notification name.</strong> The type of notification record. It is set to *RGFN for all registered filter notifications.</p>
<p><strong>Problem ID.</strong> The ID of the problem that caused the notification.</p>
<p><strong>Reserved.</strong> An ignored field.</p>
<p><strong>Timestamp.</strong> The time at which the event was processed.</p>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="3">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td align="left" valign="top">CPF24B4 E</td>
<td valign="top">Severe error while addressing parameter list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C7C E</td>
<td valign="top">User index is full.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C90 E</td>
<td valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF1 E</td>
<td valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF8100 E</td>
<td valign="top">All CPF81xx messages could be returned. xx is from 01 to FF.</td>
</tr>
<tr>
<td align="left" valign="top">CPF91D2 E</td>
<td valign="top">Filter type &amp;3 not correct for this operation.</td>
</tr>
<tr>
<td align="left" valign="top">CPF91D3 E</td>
<td valign="top">Filter &amp;1/&amp;2 with type &amp;3 is already registered.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9800 E</td>
<td valign="top">All CPF98xx messages could be signaled. xx is from 01 to FF.</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="netmg.htm">Network Management APIs</a> | <a href="aplist.htm">APIs
by category</a></td>
</tr>
</table>
</center>
</body>
</html>