friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
master
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/xjobntfy.htm

669 lines
20 KiB
HTML
Raw Permalink Blame History

<!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>Job Notification Exit Point</title>
<!-- 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. -->
<!-- Begin Header Records ========================================= -->
<!-- WM SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- File cleanup completed Nov 2001 by v2cdijab -->
<!-- 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>Job Notification Exit Point</h2>
<div class="box" style="width: 60%;">
<br>
&nbsp;&nbsp;Required Parameter: None<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;QSYSINC Member Name: EJOBNTFY<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Exit Point Name: QIBM_QWT_JOBNOTIFY<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Exit Point Format Name: NTFY0100<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Job Notification exit point can be used to log notification messages to
data queues when i5/OS jobs go through the following transitions:</p>
<ul>
<li>A job is placed on a job queue.</li>
<li>A job starts.</li>
<li>A job ends.</li>
</ul>
<p>The QIBM_QWT_JOBNOTIFY exit point registers a data queue and library, rather
than an exit program and library. The program data that is associated with the
data queue must contain the notification type, subsystem description, and
subsystem description library.</p>
<p>The information will be retrieved from the registration facility when the
subsystem starts, so the data queues must be registered before starting the
subsystem. Any queues added to the registration facility after a subsystem is
started will not be retrieved until the next time the subsystem starts.
The length of the data queue(s) is retrieved by the subsystem when it is started. If a data queue
is deleted and recreated with a different length, the subsystem must be restarted in order to use
the new data queue size. Otherwise, it will continue sending the same size message.</p>
<p>While multiple subsystems can use the same data queue, each subsystem is
limited to using a maximum of eight data queues. If more than eight data queues
are registered for a subsystem, the specific data queues that will be selected
are undefined.</p>
<p>If a job is submitted to a job queue or ended from a job queue that is not allocated by an active
subsystem, a job queue notification message will be sent to a default data
queue of QSYSDTAQ in library QSYS.</p>
<p>Use the Create Data Queue (CRTDTAQ) command to create any data queues to be
used by this function, including the QSYSDTAQ mentioned previously. See <a
href="#HDRJNTYDQA">Data Queue Attributes</a> for additional information about
the attributes of the data queues.</p>
<p>For the format of the job start and job end notification messages, see <a
href="#HDRJNTYF1">Format of Job Start and Job End Notification Messages</a>.
For the format of the job queue notification messages, see <a href=
"#HDRJNTYF2">Format of Job Queue Notification Messages</a>.</p>
<br>
<h3>Authorities and Locks</h3>
<p>None.</p>
<br>
<h3>Required Parameter</h3>
<p>None.</p>
<br>
<h3>Program Data</h3>
<p>When you register the data queue, the following is required for the program
data.</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(4)</td>
<td align="left" valign="top" width="60%">Notification type</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Subsystem description</td>
</tr>
<tr>
<td align="center" valign="top">14</td>
<td align="center" valign="top">E</td>
<td align="left" valign="top">CHAR(10)</td>
<td align="left" valign="top">Subsystem description library</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRJNTYD0">Field Descriptions</a></h3>
<p><strong>Notification type.</strong> The type of notifications that are to be
sent to the data queue. The following values are supported:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>0001</em></td>
<td align="left" valign="top">Job start notifications are sent to this data
queue.</td>
</tr>
<tr>
<td align="left" valign="top"><em>0002</em></td>
<td align="left" valign="top">Job end notifications are sent to this data
queue.</td>
</tr>
<tr>
<td align="left" valign="top"><em>0003</em></td>
<td align="left" valign="top">Job start and job end notifications are sent to
this data queue.</td>
</tr>
<tr>
<td align="left" valign="top"><em>0004</em></td>
<td align="left" valign="top">Job queue notifications are sent to this data
queue.</td>
</tr>
<tr>
<td align="left" valign="top"><em>0005</em></td>
<td align="left" valign="top">Job start and job queue notifications are sent to
this data queue.</td>
</tr>
<tr>
<td align="left" valign="top"><em>0006</em></td>
<td align="left" valign="top">Job end and job queue notifications are sent to
this data queue.</td>
</tr>
<tr>
<td align="left" valign="top"><em>0007</em></td>
<td align="left" valign="top">Job start, job end, and job queue notifications
are sent to this data queue.</td>
</tr>
</table>
<p><strong>Subsystem description.</strong> The name of the subsystem
description for which this data queue is to be used. The following special
value is supported:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*ANY</em></td>
<td align="left" valign="top">The data queue is used for all subsystems. When
this value is specified, the subsystem description library is ignored.</td>
</tr>
</table>
<p><strong>Subsystem description library.</strong> The name of the library that
contains the subsystem description. The following special value is
supported:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*ANY</em></td>
<td align="left" valign="top">The data queue is used for any subsystems that
match the subsystem description name, regardless of the library.</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRJNTYDQA">Data Queue Attributes</a></h3>
<p>The following table lists several data queue attributes and the required
values for the data queues that are used by this exit point.</p>
<table border width="50%">
<!-- width="50" -->
<tr>
<th align="left" valign="top">Attribute</th>
<th align="left" valign="top">Value</th>
</tr>
<tr>
<td align="left" valign="top" width="50%">Maximum entry length</td>
<td align="left" valign="top" width="50%">144 or greater
</td>
</tr>
<tr>
<td align="left" valign="top">Sequence</td>
<td align="left" valign="top">*KEYED</td>
</tr>
<tr>
<td align="left" valign="top">Key length</td>
<td align="left" valign="top">4</td>
</tr>
</table>
<p>As shown in the previous table, the data queue entries are received by key.
The following keys are used with these data queues:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>0001</em></td>
<td align="left" valign="top">Data queue message is a job start notification
message.</td>
</tr>
<tr>
<td align="left" valign="top"><em>0002</em></td>
<td align="left" valign="top">Data queue message is a job end notification
message.</td>
</tr>
<tr>
<td align="left" valign="top"><em>0004</em></td>
<td align="left" valign="top">Data queue message is a job queue notification
message.</td>
</tr>
</table>
<br>
<p>The "Maximum entry length" is suggested to be set to 144 or greater. However, the exit point will send as
much message data as there is room for in the data queue if the "Maximum entry length" is less than 144.</p>
<br>
<br>
<h3><a name="HDRJNTYF1">Format of Job Start and Job End Notification
Messages</a></h3>
<p>For more information about this format, see <a href="#HDRJNTYD2">Field
Descriptions</a>.</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%">Message identifier</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="center" valign="top">A</td>
<td align="left" valign="top">CHAR(2)</td>
<td align="left" valign="top">Message format</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">CHAR(16)</td>
<td align="left" valign="top">Internal job identifier</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">CHAR(26)</td>
<td align="left" valign="top">Qualified job name</td>
</tr>
<tr>
<td align="center" valign="top">54</td>
<td align="center" valign="top">36</td>
<td align="left" valign="top">CHAR(20)</td>
<td align="left" valign="top">Qualified job queue name</td>
</tr>
<tr>
<td align="center" valign="top">74</td>
<td align="center" valign="top">4A</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Time-stamp job entered system</td>
</tr>
<tr>
<td align="center" valign="top">82</td>
<td align="center" valign="top">52</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Time-stamp job started</td>
</tr>
<tr>
<td align="center" valign="top">90</td>
<td align="center" valign="top">5A</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Time-stamp job ended</td>
</tr>
<tr>
<td align="center" valign="top">98</td>
<td align="center" valign="top">62</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Job type</td>
</tr>
<tr>
<td align="center" valign="top">99</td>
<td align="center" valign="top">63</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Job subtype</td>
</tr>
<tr>
<td align="center" valign="top">100</td>
<td align="center" valign="top">64</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Job end severity code</td>
</tr>
<tr>
<td align="center" valign="top">104</td>
<td align="center" valign="top">68</td>
<td align="left" valign="top">BINARY(8)</td>
<td align="left" valign="top">Processing time used</td>
</tr>
<tr>
<td align="center" valign="top">112</td>
<td align="center" valign="top">70</td>
<td align="left" valign="top">CHAR(32)</td>
<td align="left" valign="top">Reserved</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRJNTYF2">Format of Job Queue Notification Messages</a></h3>
<p>For more information about this format, see <a href="#HDRJNTYD2">Field
Descriptions</a>.</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%">Message identifier</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="center" valign="top">A</td>
<td align="left" valign="top">CHAR(2)</td>
<td align="left" valign="top">Message format</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">CHAR(16)</td>
<td align="left" valign="top">Internal job identifier</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">CHAR(26)</td>
<td align="left" valign="top">Qualified job name</td>
</tr>
<tr>
<td align="center" valign="top">54</td>
<td align="center" valign="top">36</td>
<td align="left" valign="top">CHAR(20)</td>
<td align="left" valign="top">Qualified job queue name</td>
</tr>
<tr>
<td align="center" valign="top">74</td>
<td align="center" valign="top">4A</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Time-stamp job entered system</td>
</tr>
<tr>
<td align="center" valign="top">82</td>
<td align="center" valign="top">52</td>
<td align="left" valign="top">CHAR(16)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">98</td>
<td align="center" valign="top">62</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Job type</td>
</tr>
<tr>
<td align="center" valign="top">99</td>
<td align="center" valign="top">63</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Job subtype</td>
</tr>
<tr>
<td align="center" valign="top">100</td>
<td align="center" valign="top">64</td>
<td align="left" valign="top">CHAR(44)</td>
<td align="left" valign="top">Reserved</td>
</tr>
</table>
<br>
<br>
<h3><a name="HDRJNTYD2">Field Descriptions</a></h3>
<p><strong>Internal job identifier.</strong> An input value to other APIs to
increase the speed of locating the job on the system. Only i5/OS APIs use this
identifier. The identifier is not valid following an initial program load
(IPL). If you attempt to use it after an IPL, an exception occurs.</p>
<p><strong>Job end severity code.</strong> The return code of the job when it ended. See the CPF1164 message text for possible job ending codes and their meaning. This field will contain hex zeros when a job start notification message is sent.</p>
<p><strong>Job subtype.</strong> Additional information about the job type (if any exists). The possible values are:</p>
<table cellpadding="2">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>blank</em></td>
<td align="left" valign="top">The job has no special subtype or is not a valid
job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>D</em></td>
<td align="left" valign="top">The job is an immediate job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>E</em></td>
<td align="left" valign="top">The job started with a procedure start
request.</td>
</tr>
<tr>
<td align="left" valign="top"><em>F</em></td>
<td align="left" valign="top">The job is an AS/400<sup>(R)</sup> Advanced 36<sup>(R)</sup>
machine server job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>J</em></td>
<td align="left" valign="top">The job is a prestart job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>P</em></td>
<td align="left" valign="top">The job is a print driver job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>T</em></td>
<td align="left" valign="top">The job is a System/36 multiple requester
terminal (MRT) job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>U</em></td>
<td align="left" valign="top">Alternate spool user.</td>
</tr>
</table>
<p><strong>Job type.</strong> The type of job. The possible values for this field are:</p>
<table cellpadding="2">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>blank</em></td>
<td align="left" valign="top">The job is not a valid job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>A</em></td>
<td align="left" valign="top">The job is an autostart job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>B</em></td>
<td align="left" valign="top">The job is a batch job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>I</em></td>
<td align="left" valign="top">The job is an interactive job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>M</em></td>
<td align="left" valign="top">The job is a subsystem monitor job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>R</em></td>
<td align="left" valign="top">The job is a spooled reader job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>S</em></td>
<td align="left" valign="top">The job is a system job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>W</em></td>
<td align="left" valign="top">The job is a spooled writer job.</td>
</tr>
<tr>
<td align="left" valign="top"><em>X</em></td>
<td align="left" valign="top">The job is the SCPF system job.</td>
</tr>
</table>
<p>Refer to
<a href="WMAttrDesc.htm#HDRWRKJOB">Comparing Job Type and Subtype with the Work
with Active Job Command</a> for information about how the job type field and
the job subtype field equate to the type field in the Work with Active Job
(WRKACTJOB) command.</p>
<p><strong>Message format.</strong> The format of the data in the job
notification message. This field is always set to 01 for job start and job end
notification messages, and is always set to 02 for job queue notification
messages.</p>
<p><strong>Message identifier.</strong> The type of message that is represented
by this data queue entry. This field is always set to *JOBNOTIFY.</p>
<p><strong>Processing time used.</strong> The amount of processing unit time used by the job, in milliseconds. This field will contain hex zeros when a job start notification message is sent.</p>
<p><strong>Qualified job name.</strong> The name of the job that is associated
with this notification message. The format of the qualified job name is a
10-character simple job name, a 10-character user name, and a 6-character job
number. Each portion of the qualified job name is left-justified and padded
with blanks on the right.</p>
<p><strong>Qualified job queue name.</strong> The name of the job queue that
the job was placed on, and the name of the library that contains the job queue.
The format of the qualified name is a 10-character simple object name followed
by a 10-character library name. Each portion of the qualified job queue name is
left-justified and padded with blanks on the right. This field is only filled in for job end notification messages when a job is ended from a job queue, and for job queue notification messages.</p>
<p><strong>Reserved.</strong> An ignored field.</p>
<p><strong>Time-stamp job ended.</strong> The date and time the job completed running on the system. This is in system time-stamp format. This field will contain hex zeros when a job start notification message is sent.</p>
<p><strong>Time-stamp job entered system.</strong> The date and time the job entered the system. This is in system time-stamp format.</p>
<p><strong>Time-stamp job started.</strong> The date and time the job began to run on the system. This is in system time-stamp format.</p>
<br>
<h3>Usage Notes</h3>
<ol>
<li>The notification messages may not be logged to the data queue if a DDM data
queue is specified for this exit point.<br><br></li>
<li>It is recommended that the data queue
exist in a library in the system auxiliary storage pool (ASP) or in a basic user ASP. It
will not be found if it exists in a library in an independent ASP.</li>
<li>The Convert Date and Time Format (QWCCVTDT) API can be used to convert date and time values from one format to another format.</li>
<li>When a job is ended from a job queue, the time-stamp job entered system and processing time used fields will contain hex zeros, unless the job has previously run and transferred to the job queue.</li>
</ol>
<hr>
Exit program introduced: V3R7
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"wm1.htm">Work Management APIs</a> | <a href="aplist.htm">
APIs by category</a></td>
</tr>
</table>
</center>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink