236 lines
9.8 KiB
HTML
236 lines
9.8 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>Message Handling Terms and Concepts</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 ========================================== -->
|
||
|
|
<!-- MH1TEMP SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
|
||
|
|
<!-- RCHVMW2 on 26 Jan 1999 at 10:37:34 -->
|
||
|
|
<!-- File edited Sept 2001 -->
|
||
|
|
<!--End Header Records -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<a name="Top_Of_Page"></a>
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<h2>Message Handling Terms and Concepts</h2>
|
||
|
|
|
||
|
|
<p>This article describes the basic elements of iSeries messages and message
|
||
|
|
handling, including:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Immediate and predefined messages</li>
|
||
|
|
|
||
|
|
<li>Message types, or the purposes assigned to messages when they are sent</li>
|
||
|
|
|
||
|
|
<li>Message destinations, such as work station displays and call message
|
||
|
|
queues</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>For details about these topics, see the
|
||
|
|
<a href="../rbam6/clpro.htm">CL Programming</a> topic.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Immediate and Predefined Messages</h3>
|
||
|
|
|
||
|
|
<p>The i5/OS program uses two basic kinds of messages, immediate and
|
||
|
|
predefined. <strong>Immediate messages</strong>, also known as <strong>
|
||
|
|
impromptu messages</strong>, are created by the sender when they are sent. They
|
||
|
|
consist completely of text that the sender supplies. They do not have
|
||
|
|
identifying codes like CPF2469, and they are not stored in message files on the
|
||
|
|
system.</p>
|
||
|
|
|
||
|
|
<p>In contrast, <strong>predefined messages</strong> are created and exist
|
||
|
|
outside the programs that use them. Each predefined message has its own
|
||
|
|
<strong>message description</strong>, which is stored in a message file (object
|
||
|
|
type *MSGF) on the system. The message description includes the message text
|
||
|
|
and other items, such as message help, the default reply for the message, and
|
||
|
|
its severity level.</p>
|
||
|
|
|
||
|
|
<p>Each message description has its own message identifier. The <strong>message
|
||
|
|
identifier</strong> is a 7-character code, such as CPF2469, that refers to the
|
||
|
|
message description as a whole. It is displayed with the text of the message
|
||
|
|
and lets programs refer to the message easily. The term message identifier is
|
||
|
|
usually abbreviated to MSGID in items such as CL commands.</p>
|
||
|
|
|
||
|
|
<p>Predefined messages have two types of text, message text and message help.
|
||
|
|
The <strong>message text</strong> is the version of the predefined message that
|
||
|
|
is first displayed at a work station or logged in a job log. The message text
|
||
|
|
is also known as <strong>first-level text</strong>. It briefly describes a
|
||
|
|
condition. <strong>Message help</strong>, also known as <strong>second-level
|
||
|
|
text</strong>, is available to the user on request. It usually describes the
|
||
|
|
cause of the condition and details any corrective action the user should
|
||
|
|
take.</p>
|
||
|
|
|
||
|
|
<p>The message text and message help for predefined messages can consist of
|
||
|
|
only constant text, only substitution variables, or both constant text and
|
||
|
|
substitution variables. are variables for items such as file names in the
|
||
|
|
message text or message help. They allow the message to better describe the
|
||
|
|
recipient's individual circumstances. Substitution variables are also known as
|
||
|
|
<strong>replacement data</strong>. <strong>Substitution variables</strong> The
|
||
|
|
specific values you assign to these variables are called <strong>message
|
||
|
|
data</strong>.</p>
|
||
|
|
|
||
|
|
<p>When either an immediate or predefined message is sent, the command or API
|
||
|
|
used to send it usually assigns it a message key. The <strong>message
|
||
|
|
key</strong>, also called the <strong>message reference key</strong>, is a
|
||
|
|
unique string of characters that identifies a particular instance of a message
|
||
|
|
in a queue. (In contrast, a message identifier identifies a message as it is
|
||
|
|
stored in a message file, not as it is sent.) You can use the message key to
|
||
|
|
refer to a specific instance of a message in order to move, receive, reply to,
|
||
|
|
resend, or remove it.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3><a name="HDRMSGTYPE">Message Types</a></h3>
|
||
|
|
|
||
|
|
<p>The i5/OS program divides messages into types according to their use. These
|
||
|
|
<strong>message types</strong> are categories based on the message's purpose.
|
||
|
|
The sender of the message determines its type when sending the message. The
|
||
|
|
message handling APIs use these message types in defining and working with
|
||
|
|
messages:</p>
|
||
|
|
|
||
|
|
<p><strong>Completion (*COMP).</strong> Reports the successful
|
||
|
|
completion of a task.</p>
|
||
|
|
|
||
|
|
<p><strong>Diagnostic (*DIAG).</strong> Describes errors in
|
||
|
|
processes or input data. When an error occurs, a program usually sends an
|
||
|
|
escape message, which causes the task to end abnormally. One or more diagnostic
|
||
|
|
messages can be sent before the escape message to describe the error.</p>
|
||
|
|
|
||
|
|
<p><strong>Escape (*ESCAPE).</strong> Indicates a condition causing
|
||
|
|
a program to end abnormally, without completing its work.</p>
|
||
|
|
|
||
|
|
<p><strong>Exception (*EXCP).</strong> Indicates a condition
|
||
|
|
causing a program to end abnormally, without completing its work. An exception
|
||
|
|
message can be either an escape or a notify message. The exception message type
|
||
|
|
and the special value *EXCP are used only with the Receive Program Message
|
||
|
|
(QMHRCVPM) API.</p>
|
||
|
|
|
||
|
|
<p><strong>Informational (*INFO).</strong> Conveys information <em>
|
||
|
|
without</em> asking for a reply.</p>
|
||
|
|
|
||
|
|
<p><strong>Inquiry (*INQ).</strong> Conveys information <em>
|
||
|
|
and</em> asks for a reply.</p>
|
||
|
|
|
||
|
|
<p><strong>Notify (*NOTIFY).</strong> Describes a condition in the
|
||
|
|
sending program requiring corrective action or a reply.</p>
|
||
|
|
|
||
|
|
<p><strong>Reply (*RPY).</strong> Responds to an inquiry or notify
|
||
|
|
message.</p>
|
||
|
|
|
||
|
|
<p><strong>Request (*RQS).</strong> Requests a function from the
|
||
|
|
receiving program.</p>
|
||
|
|
|
||
|
|
<p><strong>Sender's copy (*COPY).</strong> Is a copy of an inquiry
|
||
|
|
or notify message. This copy is kept by the sender of the inquiry or notify
|
||
|
|
message.</p>
|
||
|
|
|
||
|
|
<p><strong>Scope (*SCOPE).</strong> Specifies a program to run when
|
||
|
|
the program this message is sent to completes. If the message is sent to *EXT
|
||
|
|
the program is to run when the job completes.</p>
|
||
|
|
|
||
|
|
<p><strong>Status (*STATUS).</strong> Describes the status of work
|
||
|
|
being done by a program.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Message Destinations</h3>
|
||
|
|
|
||
|
|
<p>All iSeries messages are sent to message queues. The system provides the
|
||
|
|
following message queues:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>A work station message queue for each work station on the system.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>A user profile message queue for each enrolled user.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>A job message queue for each job running on the system. The job message
|
||
|
|
queue consists of two or more message queues:<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<ol type="1">
|
||
|
|
<li>An <strong>external message queue (*EXT)</strong> to send messages between
|
||
|
|
an interactive job and the work station user.
|
||
|
|
|
||
|
|
<p>Any thread in a multithreaded job can send messages to the external message
|
||
|
|
queue. Each thread can receive or remove only those messages sent to the
|
||
|
|
external message queue from that thread.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>A set of <strong>call message queues</strong> corresponding to the calls in
|
||
|
|
the job. Each call within a job has a call message queue. If a call stack entry
|
||
|
|
appears in the call stack twice, it has two separate call message queues.
|
||
|
|
|
||
|
|
<p>A call message queue is also known as a program message queue. However, in
|
||
|
|
the ILE model, you can call procedures as well as programs. Both ILE procedure
|
||
|
|
message queues and OPM program message queues are referred to as call message
|
||
|
|
queues. A multithreaded job has a separate set of call message queues for each
|
||
|
|
thread that is running in the job. Each thread can access only the messages for
|
||
|
|
the call message queues within its own thread; messages cannot be sent to,
|
||
|
|
received from, or removed from call message queues in other threads.</p>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong> An ILE procedure has an associated call
|
||
|
|
message queue only if the related compiler does not place the procedure inline.
|
||
|
|
A inline procedure does not have a call message queue, and because of this,
|
||
|
|
cannot be referenced on any message handler API. For example, you cannot send a
|
||
|
|
message to an inline procedure by specifying the name of that inline
|
||
|
|
procedure.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>All message queues other than external and call message queues are
|
||
|
|
considered <strong>nonprogram message queues.</strong></li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The system operator's message queue, QSYSOPR.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The history log, QHST.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p><a name="term.htm#SPTHMPGMM"><strong>Note:</strong></a> A message sent to a
|
||
|
|
message queue remains on the queue until you use a command or API to remove it
|
||
|
|
from the queue or move it to another queue. <strong>Removing a message</strong>
|
||
|
|
from a message queue deletes that one instance of the message from the system.
|
||
|
|
After removal, you can no longer receive or otherwise work with that instance
|
||
|
|
of the message. However, other instances of the message might still be
|
||
|
|
available in the same or different message queues. The message description of a
|
||
|
|
predefined message still exists in a message file.</p>
|
||
|
|
|
||
|
|
<p>This exit program could be called from an exit point within a multithreaded
|
||
|
|
job and should be written to be threadsafe.</p>
|
||
|
|
|
||
|
|
<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>
|
||
|
|
|