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

982 lines
34 KiB
HTML
Raw Normal View History

Add readme and dist folders
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>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>
&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%">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>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;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 &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24D1 E</td>
<td align="left" valign="top">Member replace option &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24D2 E</td>
<td align="left" valign="top">Number of elements &amp;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 &amp;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 &amp;1 specified in filter element
&amp;2 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24D5 E</td>
<td align="left" valign="top">Message severity &amp;1 specified in filter
element &amp;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 &amp;1 does not
contain a null value.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24D7 E</td>
<td align="left" valign="top">File &amp;1 in library &amp;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 &amp;1 in library &amp;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 &amp;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 &amp;1 not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C21 E</td>
<td align="left" valign="top">Format name &amp;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 &amp;1 in library
&amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
</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 &amp;1 member &amp;3
moved or renamed.</td>
</tr>
<tr>
<td align="left" valign="top">CPD241B E</td>
<td align="left" valign="top">Error occurred on file &amp;1 member &amp;3 in
&amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPD241C E</td>
<td align="left" valign="top">Job log file &amp;1 member &amp;3 in &amp;2 has
been deleted.</td>
</tr>
<tr>
<td align="left" valign="top">CPD241D E</td>
<td align="left" valign="top">Job log file &amp;1 member &amp;3 in &amp;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 &amp;1 member
&amp;3 in &amp;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 &amp;1
member &amp;3 in &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPD242B E</td>
<td align="left" valign="top">Message data truncated for message key
&amp;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>
Reference in New Issue Copy Permalink