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

746 lines
21 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>Send Message (QEZSNDMG) 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. -->
<!-- NETMG2 SCRIPT A converted by B2H R4.1 (346) (CMS) by HOLTJM at -->
<!-- RCHVMW2 on 29 Jan 1999 at 10:01:37 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!--File Edited Oct 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>Send Message (QEZSNDMG) API</h2>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;Optional Parameter Group 1:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">1</td>
<td align="left" valign="top" width="50%">Message type</td>
<td align="left" valign="top" width="15%">Input</td>
<td align="left" valign="top" width="25%">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Delivery mode</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Message text</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">Length of message text</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">List of user profile or display station
names</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Array of Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Number of user profile or display station
names</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Message sent indicator</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">Function requested</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">9</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;Optional Parameter Group 2:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">10</td>
<td align="left" valign="top" width="50%">Show Send a Message display</td>
<td align="left" valign="top" width="15%">Input</td>
<td align="left" valign="top" width="25%">Char(1)</td>
</tr>
<tr>
<td align="center" valign="top">11</td>
<td align="left" valign="top">Qualified 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">12</td>
<td align="left" valign="top">Name type indicator</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(4)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Optional Parameter Group 3:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">13</td>
<td align="left" valign="top" width="50%">Coded character set identifier</td>
<td align="left" valign="top" width="15%">Input</td>
<td align="left" valign="top" width="25%">Binary(4)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<br>
<p>The Send Message (QEZSNDMG) API sends a message to one or more users or
display stations and optionally shows the Operational Assistant <a href=
"#FIGSNDMSG">Send a Message</a> display before sending the message. Parameters
can be specified, providing the ability to display initial values (defaults) to
the user. Parameters determine:</p>
<ul>
<li>The type of message that is sent (informational or inquiry)</li>
<li>The delivery mode of the message (break or normal)</li>
<li>The message text</li>
<li>The users or the display stations who will receive the message</li>
<li>The message queue to receive the reply to an inquiry message</li>
<li>Whether or not the Send a Message display is shown</li>
<li>Whether the list of names contains user profile names or display station
names</li>
</ul>
<p>This API combines the functions of the Send Message (SNDMSG) and Send Break
Message (SNDBRKMSG) commands. In addition, it provides the ability to:</p>
<ul>
<li>Send inquiry messages to more than one user</li>
<li>Send break messages to user profiles</li>
<li>Send break and inquiry messages to all active users</li>
<li>Send nonbreak and inquiry messages to display stations</li>
</ul>
<p>This API can be called with or without parameters. If parameters are
specified, at least nine parameters are required. If this API is called in a
batch job, parameter 10, Show Send a Message display, must be specified with a
value of N. This will cause the message to be sent without using the Send a
Message display.</p>
<p>Refer to <a href="netmg.htm">Network Management APIs</a> for information on
alert messages. Refer to <a href="mh1.htm">Message Handling APIs</a> for
information on the message handling APIs.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Special Authority (*ALL or *ALLACT value on parameter 5)</em></dt>
<dd>*JOBCTL</dd>
<dt><em>SNDBRKMSG Command (*BREAK delivery mode on parameter 2)</em></dt>
<dd>*USE</dd>
<dt><em>Message Queue Authority</em></dt>
<dd>*OBJOPR and *ADD</dd>
<dt><em>Message Queue Library Authority</em></dt>
<dd>*EXECUTE</dd>
</dl>
<br>
<h3><a name="FIGSNDMSG">Send a Message Display</a></h3>
<p><img src="rbafx662.gif" alt="Send a Message Display"></p>
<br>
<h3>Optional Parameter Group 1</h3>
<dl>
<dt><strong>Message type</strong></dt>
<dd>INPUT; CHAR(10)
<p>The type of message to send. The value you specify determines the default
for the <em>Message needs reply</em> prompt on the Send a Message display (N
for *INFO and Y for *INQ). You must specify one of these values:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*INFO</em></td>
<td align="left" valign="top">Informational. The message does not need a
reply.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*INQ</em></td>
<td align="left" valign="top">Inquiry. The message needs a reply. If the
message queue and library name parameter was specified, the reply is placed on
that message queue; otherwise, the reply is placed on the message queue
specified in the user profile of the sender.</td>
</tr>
<tr>
<td align="left" valign="top"></td>
<td align="left" valign="top">The user profile name of the person sending the
reply is added to the beginning of the message text, allowing the person
receiving the reply to determine which user it is from.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Delivery mode</strong></dt>
<dd>INPUT; CHAR(10)
<p>The delivery mode of the message. The value you specify determines the
default for the <em>Interrupt user</em> prompt on the Send a Message display (Y
for *BREAK and N for *NORMAL). If the user is not authorized to send a break
message, *NORMAL is used regardless of the value you specify. You must specify
one of these values:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*BREAK</em></td>
<td align="left" valign="top">Break message. If the user is signed on, the
message goes to the work station message queues that the user is signed on to
and temporarily interrupts the work that the user is doing. If the user is not
signed on, the message goes to the user profile message queue and the sender is
notified. If display station names are specified, the message goes to the
message queues for the specified display stations.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*NORMAL</em></td>
<td align="left" valign="top">The message goes to the user profile or display
station message queue. If the message queue is in notify mode for that user,
the message waiting light is turned on. If the message queue is in break mode,
the message temporarily interrupts the work that the receiver is doing. If the
message queue is in hold mode, the receiver is not notified.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Message text</strong></dt>
<dd>INPUT; CHAR(*)
<p>The complete text of the message. The text you specify is displayed as the
default on the Send a Message display. This must not be blank if used in a
batch job or if the Show Send a Message display parameter is N.</p>
</dd>
<dt><strong>Length of message text</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the message text, in bytes. Valid values are 0 through 494.
This must be greater than 0 if the API is used in a batch job or if the Send a
Message display is not to be shown.</p>
</dd>
<dt><strong>List of user profile or display station names</strong></dt>
<dd>INPUT; ARRAY OF CHAR(10)
<p>A list of 0 through 299 user profile or display station names to which the
message is being sent. The list you specify is shown as the default on the Send
a Message display.</p>
<p>The name type indicator parameter indicates whether the names in the list
are user profile names or display station names; the default is user profile
names. At least one name must be specified if the API is used in a batch job or
if the Send a Message display is not to be used.</p>
<p>The message is sent to the user profile or display station message queue. To
specify other user message queues, use one of the following special values:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*ALL</em></td>
<td align="left" valign="top">The message queues of all users. When you use
this value, it must be the only item in the list. This value cannot be used if
*DSP is specified for the name type indicator parameter.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*ALLACT</em></td>
<td align="left" valign="top">The message queues of all active users or display
stations. This value can be used in combination with specific user profile
names or display station names and with *SYSOPR.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*SYSOPR</em></td>
<td align="left" valign="top">The system operator's message queue, QSYSOPR.
This value can be used in combination with specific user profile names and with
*ALLACT. It cannot be used if *DSP is specified for the name type indicator
parameter.</td>
</tr>
</table>
<p>If the list specifies display station names, the library list will be used
to find the work station message queues.</p>
<p><strong>Note:</strong> *JOBCTL special authority is required to use the *ALL
or *ALLACT value in this parameter.</p>
</dd>
<dt><strong>Number of user profile</strong></dt>
<dt>or display station names</dt>
<dd>INPUT; BINARY(4)
<p>The number of user profile or display station names specified. Valid values
are 0 through 299. When you use the special value *ALL for the list of user
profile or display station names parameter, specify 1. This must be greater
than 0 if the API is used in a batch job or if the Send a Message display is
not to be used.</p>
</dd>
<dt><strong>Message sent indicator</strong></dt>
<dd>OUTPUT; BINARY(4)
<p>Whether the user pressed F10 (Send message) to send one or more messages
from the Send a Message display. One of the following values is returned:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">No messages were sent.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">One or more messages were sent. If the Show Send
a Message display parameter is N and the program completes without error, this
will always be 1.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">One or more messages were sent, but one or more
of the names specified were not valid. If the Show Send a Message display
parameter is Y or not specified, the user names will be displayed and validated
before the message is sent; therefore, this value will not be used.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Function requested</strong></dt>
<dd>OUTPUT; BINARY(4)
<p>The function that the user requested when exiting the Send a Message
display. One of the following values is returned:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>-4</em></td>
<td align="left" valign="top">User pressed the Exit key (F3).</td>
</tr>
<tr>
<td align="left" valign="top"><em>-8</em></td>
<td align="left" valign="top">User pressed the Cancel key (F12).</td>
</tr>
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Send a Message display was not used.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Error code</strong></dt>
<dd>I/O; CHAR(*)
<p>The structure in which to return error information. For the format of the
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
</dd>
</dl>
<br>
<h3>Optional Parameter Group 2</h3>
<dl>
<dt><strong>Show Send a Message display</strong></dt>
<dd>INPUT; CHAR(1)
<p>Whether or not to show the Send a Message display before sending the
message. If this parameter is used, one of the following values must be
specified;</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>Y</em></td>
<td align="left" valign="top">Use the Send a Message display. This is the
default.</td>
</tr>
<tr>
<td align="left" valign="top"><em>N</em></td>
<td align="left" valign="top">Do not use the Send a Message display. This value
must be specified if the program is running in a batch job.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Qualified message queue name</strong></dt>
<dd>INPUT; CHAR(20)
<p>The name of the message queue that is to receive the reply for inquiry-type
messages. The first 10 characters contain the message queue name, and the
second 10 characters contain the library name. If this parameter is blank or
not specified, the reply will be sent to the message queue specified in the
user profile of the sender. This parameter is ignored if the message type
parameter is not *INQ. If this parameter is used, you can use these special
values for the library name:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*LIBL</em></td>
<td align="left" valign="top">The library list</td>
</tr>
<tr>
<td align="left" valign="top"><em>*CURLIB</em></td>
<td align="left" valign="top">The job's current library</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Name type indicator</strong></dt>
<dd>INPUT; CHAR(4)
<p>The type of names in the list. If this parameter is used, one of the
following values must be specified:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>*USR</em></td>
<td align="left" valign="top">The list of names contains only user profile
names. *USR is the default.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*DSP</em></td>
<td align="left" valign="top">The list of names contains only display station
names. This value may not be specified if the Show Send a Message display
parameter is Y.</td>
</tr>
</table>
</dd>
</dl>
<br>
<h3>Optional Parameter Group 3</h3>
<dl>
<dt><strong>Coded character set identifier</strong></dt>
<dd>INPUT; BINARY(4)
<p>The coded character set identifier (CCSID) that the immediate message text
is in. The following values are allowed:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">The immediate message text is assumed in the
CCSID of the job running this API. This is the default value if this parameter
is not specified.</td>
</tr>
<tr>
<td align="left" valign="top"><em>65535</em></td>
<td align="left" valign="top">The immediate message text will not be
converted.</td>
</tr>
<tr>
<td align="left" valign="top"><em>CCSID</em></td>
<td align="left" valign="top">Specify a valid CCSID that your immediate message
is in. Valid values are between 1 and 65535. This API will validate the CCSID.
<p>For a list of valid CCSIDs, see the <a href="../nls/rbagsglobalmain.htm">
Globalization</a> topic.</p>
</td>
</tr>
</table>
</dd>
</dl>
<br>
<h3>Error Messages</h3>
<table 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" width="15%">CPF1EA0 E</td>
<td align="left" valign="top" width="85%">Not authorized to send message to
*ALL or *ALLACT.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1EBA E</td>
<td align="left" valign="top">Parameters passed on CALL do not match those
required.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1EBB E</td>
<td align="left" valign="top">Value &amp;1 not valid for list of display
station names.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1EBC E</td>
<td align="left" valign="top">At least one user or display station must be
specified.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1EBD E</td>
<td align="left" valign="top">Message text cannot be blank.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1EBE E</td>
<td align="left" valign="top">Display station names cannot be used with the
Send a Message display.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1EBF E</td>
<td align="left" valign="top">Value for Use Send a Message display not
valid</td>
</tr>
<tr>
<td align="left" valign="top">CPF1EB2 E</td>
<td align="left" valign="top">Delivery mode must be *BREAK or *NORMAL.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1EB3 E</td>
<td align="left" valign="top">Value for length of message text must be 0
through 494.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1EB4 E</td>
<td align="left" valign="top">Number of user profile names not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1EB5 E</td>
<td align="left" valign="top">Value for number of user profile names must be 0
through 299.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1EB6 E</td>
<td align="left" valign="top">Program &amp;1 cannot be run as a batch job.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1EB7 E</td>
<td align="left" valign="top">*ALL not allowed with other user profile
names.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1EB8 E</td>
<td align="left" valign="top">Value &amp;1 for name type indicator not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1EB9 E</td>
<td align="left" valign="top">Value &amp;1 not valid for list of user profile
names.</td>
</tr>
<tr>
<td align="left" valign="top">CPF1E99 E</td>
<td align="left" valign="top">Unexpected error occurred.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24B3 E</td>
<td align="left" valign="top">Message type &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24B4 E</td>
<td align="left" valign="top">Severe error while addressing parameter
list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2403 E</td>
<td align="left" valign="top">Message queue &amp;1 in &amp;2 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF2408 E</td>
<td align="left" valign="top">Not authorized to message queue &amp;1.</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">CPF3CF1 E</td>
<td align="left" valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9871 E</td>
<td align="left" valign="top">Error occurred while processing.</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>
<hr>
API introduced: V2R1
<hr>
<center>
<table cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"oa1.htm">Operational Assistant APIs</a> | <a href="aplist.htm">APIs by
category</a></td>
</tr>
</table>
</center>
</body>
</html>