982 lines
34 KiB
HTML
982 lines
34 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>Control Job Log Output (QMHCTLJL) 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. -->
|
|
<!-- MH1TEMP SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
|
|
<!-- RCHVMW2 on 26 Jan 1999 at 10:37:34 -->
|
|
<!-- Change History: -->
|
|
<!-- YYMMDD USERID Change description -->
|
|
<!--File Edited Sept 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 language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
|
</script>
|
|
|
|
<h2>Control Job Log Output (QMHCTLJL) API</h2>
|
|
|
|
<div class="box" style="width: 70%;">
|
|
<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%">Output file names structure</td>
|
|
<td align="left" valign="top" width="20%">Input</td>
|
|
<td align="left" valign="top" width="20%">Char(65)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">2</td>
|
|
<td align="left" valign="top">Output file name structure format</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(8)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">3</td>
|
|
<td align="left" valign="top">Message filter array</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">Number of message filter elements</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">Qualified error message queue name</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(20)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">6</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>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: Conditional; see <a href="#usage_notes">Usage Notes</a>.<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The Control Job Log Output (QMHCTLJL) API controls the production of a job
|
|
log when the related job ends or when the job message queue becomes full and
|
|
the print-wrap option is in effect for the job. The API can only influence the
|
|
job log for the job in which it is used. The API can be used to control:</p>
|
|
|
|
<ul>
|
|
<li>The destination of the job log.</li>
|
|
|
|
<li>The amount of message information written to the job log.</li>
|
|
|
|
<li>The occurrence of messages in the job log.</li>
|
|
</ul>
|
|
|
|
<p>To have an effect on the job log, the API must be called before the job
|
|
ends. It can be called in an initial program for the job.</p>
|
|
|
|
<p>This API does not produce a job log; rather, the API captures the control
|
|
information specified on the parameters and retains the information until job
|
|
log production. The API also prepares the output files for job log production.
|
|
When job log production occurs, such as at end of job, the control information
|
|
and the prepared output files direct the job log to the output file.</p>
|
|
|
|
<p>If the API is not used, normal job log production occurs. That is, all
|
|
messages in the job message queue for the job are written to a spooled file
|
|
from which the job log can be printed. If the API is used, no spooled file is
|
|
produced. Instead, the messages are written into one or two output files,
|
|
depending upon the amount of information requested. Once the API is used, the
|
|
options selected remain in effect for the current job until the API is called
|
|
again. Each time the API is used, the selected options can be changed. The
|
|
options in effect when the job ends or when the job message queue becomes full
|
|
are the ones used to produce the job log.</p>
|
|
|
|
<p>One or two output files can be produced at job log production time.</p>
|
|
|
|
<ul>
|
|
<li>The primary output file contains one record for each message selected for
|
|
inclusion in the job log. A record in the primary output file contains the
|
|
essential information of the message: message ID, message type, message
|
|
severity, time sent, sender and receiver information, and the message data.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Output to a secondary output file can also be produced. Secondary output is
|
|
optional and is controlled by providing an output file name for the secondary
|
|
file. Secondary output consists of the first and second level text for a
|
|
message. The first and second level text has all message data inserted and is
|
|
an image of the print line. Since there can be more than one print line for
|
|
first and second level text, there can be more than one secondary record for a
|
|
message. Thus, for a single message, the primary file contains one record and
|
|
the secondary file contains one or more records. For example, if the print
|
|
image for first level text is 2 print lines and the second level is 4 print
|
|
lines, there are 6 records produced for the message in the secondary file. With
|
|
the 1 primary record, there would be a total of 7 records produced for that
|
|
message.</li>
|
|
</ul>
|
|
|
|
<p>Detailed information about the formats of the primary output file and
|
|
secondary output file is provided in the <a href="../rbam6/clpro.htm">CL Programming</a> topic.</p>
|
|
|
|
<p>This API does not influence the DSPJOBLOG CL command when OUTPUT(*OUTFILE)
|
|
is specified on the command. If OUTPUT(*OUTFILE) is specified on the command,
|
|
the primary job log information is written to the file specified on the
|
|
command, and no message filtering is performed. If OUTPUT(*APIDFN) is specified
|
|
on the command, the files specified by the call to the API are used for output,
|
|
and message filtering is performed by the call to this API. The error message
|
|
queue is not used so any errors are returned to the issuer of the DSPJOBLOG
|
|
command.</p>
|
|
|
|
<p>If the DSPJOBLOG command is used with the files prepared by this API, note
|
|
the following:</p>
|
|
|
|
<ul>
|
|
<li>The files specified on the API are prepared only once, when the API is
|
|
called. Preparing the files includes clearing the members of any existing data
|
|
if requested on the API. The files prepared by this API can be used on several
|
|
calls of the DSPJOBLOG command. However, the members are not cleared between
|
|
calls.</li>
|
|
|
|
<li>Each time the DSPJOBLOG command is called, the output is added to whatever
|
|
is already in the members. Additionally, at end of job, the final records for
|
|
the job log are added to the members.</li>
|
|
|
|
<li>If the members need to be cleared between calls of the DSPJOBLOG command or
|
|
before the job ends, call the API again or use the CLRPFM (Clear Physical File
|
|
Member) command.</li>
|
|
</ul>
|
|
|
|
<p>This API does not override the LOG job attribute for the job or the LOG
|
|
attribute on the SIGNOFF CL command. The LOG job attribute controls whether any
|
|
job log is to be produced and controls whether second level text is to be
|
|
logged.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Authorities and Locks</h3>
|
|
|
|
<p>Authorization to the specified output file(s) is checked when this API is
|
|
used. If the specified output file(s) does not exist, this API creates them.
|
|
Additionally, if the output file member(s) does not exist, this API adds a new
|
|
member by the specified name to the output file(s). The authorization checking
|
|
is performed using the user profile the API was called under. If an output file
|
|
needs to be created, the user profile the API was called under becomes the
|
|
owner of the output file. Public authority to files created by this API is
|
|
controlled by the library containing those files. Public authority for objects
|
|
created into a library is controlled by the CRTAUT parameter on the CRTLIB or
|
|
CHGLIB command.</p>
|
|
|
|
<dl>
|
|
<dt><strong>Output file library authority:</strong></dt>
|
|
|
|
<dd>
|
|
<ul>
|
|
<li>*EXECUTE required in all cases.</li>
|
|
|
|
<li>*ADD required when the output file or member does not exist.</li>
|
|
</ul>
|
|
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>Output file authority:</strong></dt>
|
|
|
|
<dd>
|
|
<ul>
|
|
<li>*OBJOPR, *OBJMGT, *ADD required in all cases.</li>
|
|
|
|
<li>*DLT required to clear the member of existing records.</li>
|
|
</ul>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Required Parameter Group</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Output file names structure</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(65)
|
|
|
|
<p>Provides information about the primary and secondary files and members.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Output file names structure format</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(8)
|
|
|
|
<p>The format of the output file names structure parameter. This must be set to
|
|
CTLJ0100. See <a href="#HDROFNS">CTLJ0100 Output File Names Structure</a> for
|
|
details about this format.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Message filter array</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(*)
|
|
|
|
<p>An array of zero or more elements. Each element in the array defines a test
|
|
applied against each message before it is written to the output file. The tests
|
|
are performed in the order they appear in the array. A message is rejected and
|
|
not written to the output file if any one test defined in the array is true for
|
|
the message. A message is selected and written to the output file if all tests
|
|
defined in the array are false for the message.</p>
|
|
|
|
<p>Each array element specifies a message severity, message type, and message
|
|
ID. If a message has a message severity less than or equal to the specified
|
|
severity, has the specified type, and has a message ID equal to the specified
|
|
ID, the test is true and the message is not written to the output file.
|
|
Processing stops on the rejected message and the next message is processed.</p>
|
|
|
|
<p>If a message meets one or two of the criteria but not all three, the test is
|
|
false and the test defined by the next array element is applied. If all array
|
|
elements have been applied to the message and none have been found true, the
|
|
message is written to the output file.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Number of message filter elements</strong></dt>
|
|
|
|
<dd>INPUT; BINARY(4)
|
|
|
|
<p>The number of elements in the Message filter array parameter. The value must
|
|
be greater than or equal to 0 but less than or equal to 255. If no message
|
|
filtering is to be done during job log production, this parameter must be set
|
|
to 0.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Qualified error message queue name</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(20)
|
|
|
|
<p>The qualified name of a message queue to which a message should be sent to
|
|
record any errors detected during the production of the job log to an output
|
|
file. The first 10 characters of this parameter contain the message queue name
|
|
and the second 10 characters contain the library name. A library name must be
|
|
specified. The special values *CURLIB and *LIBL cannot be used. QTEMP cannot be
|
|
specified as the library name. The message queue name specified cannot be QHST
|
|
or QSYSMSG.</p>
|
|
|
|
<p>The following special value can be used for the message queue name of this
|
|
parameter:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*NONE</em></td>
|
|
<td align="left" valign="top">No messages are sent. If errors occur during job
|
|
log production to an output file, there is no record of what the error was or
|
|
the action taken in response to the error.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*SYSOPR</em></td>
|
|
<td align="left" valign="top">Send the messages to the system operator's
|
|
message queue, QSYSOPR.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>If a qualified message queue name is provided and that message queue does
|
|
not exist or is unusable at job log production time, any messages are sent to
|
|
*SYSOPR.</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="HDROFNS">CTLJ0100 Output File Names Structure</a></h3>
|
|
|
|
<p>The following table shows the layout of the output file names structure for
|
|
format CTLJ0100.</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%">BIN(4)</td>
|
|
<td align="left" valign="top" width="60%">Output file names structure
|
|
length</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">CHAR(20)</td>
|
|
<td align="left" valign="top">Qualified primary file name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">24</td>
|
|
<td align="center" valign="top">18</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Primary file member name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">34</td>
|
|
<td align="center" valign="top">22</td>
|
|
<td align="left" valign="top">CHAR(20)</td>
|
|
<td align="left" valign="top">Qualified secondary file name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">54</td>
|
|
<td align="center" valign="top">36</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Secondary file member name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">64</td>
|
|
<td align="center" valign="top">40</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Member replace option</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRAREL">Message Filter Array Elements</a></h3>
|
|
|
|
<p>The following table shows the structure of an array element in the message
|
|
filter array parameter. This structure is repeated for each element in the
|
|
array.</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%">Reserved</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Message severity</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="center" valign="top">8</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Message Type</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">18</td>
|
|
<td align="center" valign="top">12</td>
|
|
<td align="left" valign="top">CHAR(7)</td>
|
|
<td align="left" valign="top">Message ID</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">25</td>
|
|
<td align="center" valign="top">19</td>
|
|
<td align="left" valign="top">CHAR(3)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRXXXXXX">Field Descriptions</a></h3>
|
|
|
|
<p><strong>Member replace option.</strong> Specifies if an existing member of
|
|
either the primary or secondary file is to be cleared. If the member is to be
|
|
cleared, it is cleared when this API is called. If a member contains existing
|
|
records and is not cleared, at job log production time, the new records are
|
|
added to the member and the existing records are left unchanged. Use one of the
|
|
following special values:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">Do not clear the member.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">Clear the member of existing records.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Message ID.</strong> The message ID to test each message against.
|
|
The following special values can be used in place of a message ID:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*ANY</em></td>
|
|
<td align="left" valign="top">Any message ID is considered equal. Message type
|
|
and message severity determine if the message is selected or rejected. If
|
|
message type is specified as *ANY, message severity as 99, and message ID as
|
|
*ANY, all messages are rejected. There is no job log output to the output
|
|
file(s).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*IMMED</em></td>
|
|
<td align="left" valign="top">Identifies immediate messages with no message
|
|
ID.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>A generic message ID can be used in place of a specific message ID. A
|
|
generic message ID is an ID in which the last 2 or 4 characters are 0. For
|
|
example, CPF2400 and CPF0000 are generic IDs. A generic ID represents a range
|
|
of IDs rather than a single ID. A generic ID of the form XXXnn00 represents all
|
|
IDs from XXXnn00 through XXXnnFF. A generic ID of the form XXX0000 represents
|
|
all IDs from XXX0000 through XXXFFFF.</p>
|
|
|
|
<p>When a generic ID is specified, any message ID within the range of the
|
|
generic ID is considered to match the generic ID. The message severity to test
|
|
each message against. If severity is not important in rejecting a message use
|
|
99 as the value for this field. When 99 is used, each message's severity is
|
|
less than or equal and, as a result, message type and message ID will determine
|
|
if a message is selected or rejected.</p>
|
|
|
|
<p><strong>Message type.</strong> The message type to test each message for.
|
|
Use one of the following special values:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*ANY</em></td>
|
|
<td align="left" valign="top">Any message type. Use this when message type is
|
|
not important in rejecting a message. Any message type is considered equal to
|
|
this and, as a result, message severity and message ID determines if the
|
|
message is selected or rejected.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*CMD</em></td>
|
|
<td align="left" valign="top">Commands that are logged from the running of a CL
|
|
program.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*COMP</em></td>
|
|
<td align="left" valign="top">Completion message type.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*COPY</em></td>
|
|
<td align="left" valign="top">Sender's copy message type. If a sender's copy
|
|
message is not written to the output file, its reply message is also not
|
|
written.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*DIAG</em></td>
|
|
<td align="left" valign="top">Diagnostic message type.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*ESCAPE</em></td>
|
|
<td align="left" valign="top">Escape message type. The *ESCAPE message type
|
|
includes the function check message.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*EXCP</em></td>
|
|
<td align="left" valign="top">Exception message type. Includes both *ESCAPE and
|
|
*NOTIFY message types.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*INFO</em></td>
|
|
<td align="left" valign="top">Information message type.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*INQ</em></td>
|
|
<td align="left" valign="top">Inquiry message type. If an inquiry message is
|
|
not written to the output file, its reply message is also not written.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*NOTIFY</em></td>
|
|
<td align="left" valign="top">Notify message type. If a notify message is not
|
|
written to the output file, its reply message is also not written.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*RQS</em></td>
|
|
<td align="left" valign="top">Request message type.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>*RPY</em></td>
|
|
<td align="left" valign="top">Reply message type. If a reply message is not
|
|
written to the output file, its inquiry, notify, or sender's copy message is
|
|
also not written.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Output file names structure length.</strong> The length of this
|
|
structure. This must be set to a value of 65.</p>
|
|
|
|
<p><strong>Primary file member name.</strong> The name of the member within the
|
|
primary file used for the primary job log information.</p>
|
|
|
|
<p>If a member of the specified name does not exist, a member by that name is
|
|
added to the primary file by this API.</p>
|
|
|
|
<p>If a member by the specified name does exist, this API will clear the member
|
|
if the Member replace option field of this structure specifies replace.
|
|
Otherwise, the member is not cleared. At job log production time, new records
|
|
are added to the member and any existing records are left unchanged.</p>
|
|
|
|
<p>The following special value can be used in this field:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*FIRST</em></td>
|
|
<td align="left" valign="top">The first member in the file receives the output.
|
|
If a member does not exist, one is created with a name the same as the file
|
|
name.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Qualified primary file name.</strong> The qualified name of the
|
|
primary output file. This field consists of two parts. The first 10 positions
|
|
contain the file name and the second 10 positions contain the library name. A
|
|
specific library name can be provided or the special values *CURLIB and *LIBL
|
|
can be used. QTEMP cannot be used as a library name.</p>
|
|
|
|
<p>If an output file by the specified name does not exist when this API is
|
|
called, one is created by that name in the specified library. If the library
|
|
was specified as *LIBL, the file is created in the current library. If *LIBL or
|
|
*CURLIB was specified and there is no current library, the file is created in
|
|
QGPL. The file is created with the attributes MAXRCDS and MAXMBRS set to
|
|
*NOMAX.</p>
|
|
|
|
<p>The following special value can be used in this field:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*PRINT</em></td>
|
|
<td align="left" valign="top">Resets the job so the job log is written to a
|
|
spooled file rather than an output file. When this special value is used the
|
|
remaining parameters on this API are ignored.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The API does not allow the primary file specification to be overridden by
|
|
the use of the Override Database File (OVRDBF) command. The primary file also
|
|
cannot be overridden at job log production time. The file object determined to
|
|
be the primary file used by this API is the one used at job log production
|
|
time. If the file does not exist at job log production time, the job log is
|
|
redirected to a spooled file.</p>
|
|
|
|
<p>The primary file must be a local physical file; it cannot be a DDM file.</p>
|
|
|
|
<p><strong>Qualified secondary file name.</strong> The name of the file into
|
|
which the secondary job log information is written. The parameter consists of
|
|
two parts. The first 10 positions to contain the file name and the second 10
|
|
positions contain the library name. A library name can be provided or the
|
|
special values *CURLIB and *LIBL can be used. QTEMP cannot be used for the
|
|
library name.</p>
|
|
|
|
<p>If an output file by the specified name does not exist when the API is
|
|
called, one is created by that name in the specified library. If the library
|
|
was specified as *LIBL, the file is created in the current library. If *LIBL or
|
|
*CURLIB was specified and there is no current library, the file is created in
|
|
QGPL. The file attributes MAXRCDS and MAXMBRS are set to *NOMAX.</p>
|
|
|
|
<p>The following special value can be used in this field:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*NONE</em></td>
|
|
<td align="left" valign="top">No secondary file is provided. This special value
|
|
prevents the generation of the secondary job log information. When this special
|
|
value is used, the secondary library and member names are ignored.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>The API does not allow the secondary file specification to be overridden by
|
|
the use of the OVRDBF command. The secondary file also cannot be overridden at
|
|
job log production time. The file object determined to be the secondary file by
|
|
this API is used at job log production time. If the file does not exist at job
|
|
log production time, the job log automatically redirects to a spooled file.</p>
|
|
|
|
<p>The secondary file must be a local physical file; it cannot be a DDM
|
|
file.</p>
|
|
|
|
<p><strong>Reserved.</strong> This field must be set to binary zeros.</p>
|
|
|
|
<p><strong>Secondary file member name.</strong> The name of the member within
|
|
the secondary file used for the secondary job log information.</p>
|
|
|
|
<p>If a member of the specified name does not exist, a member by that name is
|
|
added to the secondary file.</p>
|
|
|
|
<p>If a member by the specified name does exist, the member is cleared if the
|
|
Member replace option field of this structure specifies replace. Otherwise, the
|
|
member is not cleared. At job log production time, new records are added to the
|
|
member and any existing records are left unchanged.</p>
|
|
|
|
<p>The following special value can be used in this field:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>*FIRST</em></td>
|
|
<td align="left" valign="top">The first member in the file receives the output.
|
|
If a member does not exist, one is created with the same name as the file
|
|
name.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3>CCSID Considerations</h3>
|
|
|
|
<p>CCSID conversion is allowed on any field in the primary file with the
|
|
exception of the field QMHMDT, which contains the message data or immediate
|
|
message text. The QMHMDT field is defined with a CCSID of 65535 so conversion
|
|
does not occur on this field when the record is written. CCSID processing is
|
|
done on the message data when the message is sent. The CCSID that the QMHMDT
|
|
field data is in is stored in the record with the message data. The CCSID is
|
|
placed in field QMHCID.</p>
|
|
|
|
<p>CCSID conversion is allowed for any field in the secondary file except for
|
|
the field QMHLIN which contains a line of message text. This field is defined
|
|
with CCSID 65535. The message text has completed CCSID processing before the
|
|
record is written to the file. The CCSID the message text is in is stored in
|
|
field QMHSID.</p>
|
|
|
|
<p>The model files QAMHJLPR and QAMHJLSC specify no CCSID definitions other
|
|
than the two fields mentioned previously. CCSID processing for the remaining
|
|
fields is allowed to default.</p>
|
|
|
|
<p>Detailed information about the fields mentioned in this discussion is
|
|
provided in the <a href="../rbam6/clpro.htm">CL Programming</a> topic.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Error Considerations</h3>
|
|
|
|
<p>During job log production to an output file, different types of errors can
|
|
be encountered. Some errors allow the job log to be written to the output file
|
|
but the information in a record can be incomplete. Other errors can prevent the
|
|
job log from being written to the output file. For example, when the output
|
|
file has been deleted between the time this API has been run and job log
|
|
production starts. Other errors, such as when a member becomes full, allow a
|
|
certain number of records to be written but not all. Whenever an error is
|
|
encountered, an informational message is written to the user or workstation
|
|
queue specified by the API parameter. If the API parameter specifies *NONE,
|
|
these messages are not written.</p>
|
|
|
|
<p>If the error is such that the data can still be written to the output file,
|
|
even though it can be incomplete, processing continues and at the end of job
|
|
log production there are output file(s) and member(s) which contains the
|
|
information that could be written. For example, if the message data for a
|
|
message needs to be truncated to 3000 characters, production of the job log to
|
|
the output file continues but a message is sent to record the fact that the
|
|
message data was truncated.</p>
|
|
|
|
<p>If the error is such that no data can be written, the job log automatically
|
|
redirects to a spooled file. This occurs if the objects, determined by the API
|
|
to be the output files, are deleted, damaged, or otherwise unusable at the time
|
|
job log production started. If any such error is encountered on the primary or
|
|
secondary output file, this redirection to a spooled file occurs. A message is
|
|
sent to the specified message queue to record that the job log has been
|
|
redirected to a spooled file.</p>
|
|
|
|
<p>If only certain records are written to the output file, the remaining
|
|
messages are redirected to a spooled file. A message is sent to notify of
|
|
this.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Job Message Queue Full Considerations</h3>
|
|
|
|
<p>If the print-wrap option is used to control the action to take when a job
|
|
message queue becomes full, consider the following when using this API to
|
|
direct the output to an output file.</p>
|
|
|
|
<p>Each time the job message queue becomes full, records are written to the
|
|
output file for those messages that are being removed from the job message
|
|
queue. All new records are added to the member. The Member replace option
|
|
specified on this API has an effect only when this API is preparing the output
|
|
file for use. It has no effect when the records are written to the output file.
|
|
For the print-wrap option, the member contains the complete set of messages for
|
|
the job rather than a partial set.</p>
|
|
|
|
<p>For long running jobs, it is possible that the job message queue can become
|
|
full and the output file member also becomes full. If the member becomes full,
|
|
output is automatically redirected to a spooled file until the API is run
|
|
another time to specify a new member to use.</p>
|
|
|
|
<p>Changing the action from print-wrap to wrap will stop the production of
|
|
records to the file(s). When the job ends or if the action is changed back to
|
|
print-wrap, records are again written to the file(s).</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="usage_notes">Usage Notes</a></h3>
|
|
|
|
<p>This API can be called from the initial thread of a multithreaded job to
|
|
control the job log output for all threads. It should not be called from a
|
|
secondary thread.</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 align="left" valign="top">CPF24D0 E</td>
|
|
<td align="left" valign="top">QTEMP is not a valid library to use
|
|
for the file &1.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF24D1 E</td>
|
|
<td align="left" valign="top">Member replace option &1 is not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF24D2 E</td>
|
|
<td align="left" valign="top">Number of elements &1 in message filter array
|
|
is not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF24D3 E</td>
|
|
<td align="left" valign="top">Message queue &1 not valid for use with the
|
|
QMHCTLJL API.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF24D4 E</td>
|
|
<td align="left" valign="top">Message type &1 specified in filter element
|
|
&2 is not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF24D5 E</td>
|
|
<td align="left" valign="top">Message severity &1 specified in filter
|
|
element &2 is not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF24D6 E</td>
|
|
<td align="left" valign="top">Reserved field in filter element &1 does not
|
|
contain a null value.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF24D7 E</td>
|
|
<td align="left" valign="top">File &1 in library &2 cannot be used for
|
|
job log production.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF24D8 E</td>
|
|
<td align="left" valign="top">DDM file &1 in library &2 cannot be used
|
|
for job log production.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF24D9 E</td>
|
|
<td align="left" valign="top">Error message queue library name &1 is not
|
|
valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF24DA E</td>
|
|
<td align="left" valign="top">Failure while preparing for job log production to
|
|
a physical file.</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">CPF3C1D E</td>
|
|
<td align="left" valign="top">Length specified in parameter &1 not
|
|
valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPF3C21 E</td>
|
|
<td align="left" valign="top">Format name &1 is not valid.</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">CPF9822 E</td>
|
|
<td align="left" valign="top">Not authorized to file &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>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3><a name="Header_23">Job Log Production Messages</a></h3>
|
|
|
|
<table width="100%" cellpadding="5">
|
|
<!-- cols="15 85" -->
|
|
<tr>
|
|
<th align="left" valign="top">Message ID</th>
|
|
<th align="left" valign="top">Message Text</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPD241A E</td>
|
|
<td align="left" valign="top">Output file &1 member &3
|
|
moved or renamed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPD241B E</td>
|
|
<td align="left" valign="top">Error occurred on file &1 member &3 in
|
|
&2.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPD241C E</td>
|
|
<td align="left" valign="top">Job log file &1 member &3 in &2 has
|
|
been deleted.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPD241D E</td>
|
|
<td align="left" valign="top">Job log file &1 member &3 in &2 is
|
|
not available.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPD241E E</td>
|
|
<td align="left" valign="top">No records written to job log file &1 member
|
|
&3 in &2.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPD241F E</td>
|
|
<td align="left" valign="top">Not all records written to job log file &1
|
|
member &3 in &2.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPD242B E</td>
|
|
<td align="left" valign="top">Message data truncated for message key
|
|
&7.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<hr>
|
|
API introduced: V3R1
|
|
|
|
<hr>
|
|
|
|
<table align="center" cellpadding="2" cellspacing="2">
|
|
<tr align="center">
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
|
"mh1.htm">Message Handling APIs</a> | <a href="aplist.htm">APIs by
|
|
category</a></td>
|
|
</tr>
|
|
</table>
|
|
</body>
|
|
</html>
|
|
|