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

560 lines
15 KiB
HTML
Raw Normal View History

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>Send Writer Message (QSPSNDWM) 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. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- Print SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!--File Edited by Kersten Oct 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 language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<h2>Send Writer Message (QSPSNDWM) API</h2>
<div class="box" style="width: 80%;">
<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%">Receiver variable</td>
<td align="left" valign="top" width="20%">Output</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Length of receiver variable</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Format name</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Message identifier</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(7)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Qualified message file 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">Message data</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="left" valign="top">Length of message data</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="left" valign="top">Message type</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">9</td>
<td align="left" valign="top">Message wait timeout</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">10</td>
<td align="left" valign="top">Message key</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(4)</td>
</tr>
<tr>
<td align="center" valign="top">11</td>
<td align="left" valign="top">Writer handle</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(16)</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="left" valign="top">Coded character set identifier</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">13</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: No<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Send Writer Message (QSPSNDWM) API is used by a driver exit program to
send either an informational or inquiry message to the writer's message
queue.</p>
<p>When an inquiry message is issued, the writer goes into message wait status
and waits the specified number of seconds. When the message is answered, or the
timeout value has been reached, the API clears the message wait status and
returns to its caller. The answer to the inquiry message is returned through
the receiver variable parameter.</p>
<p>When an informational message is issued, the API sets the status of the
writer to message wait and returns to the caller. The API's caller must then
call the API to clear the message wait status.</p>
<br>
<h3>Authorities and Locks</h3>
<p>None.</p>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The receiver variable that receives the information requested. You can
specify the size of the area to be smaller than the format requested as long as
you specify the length parameter correctly. As a result, the API returns only
the data that the area can hold.</p>
</dd>
<dt><strong>Length of receiver variable</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the receiver variable provided. The length of receiver
variable parameter may be specified up to the size of the receiver variable
specified in the user program. If the length of receiver variable parameter
specified is larger than the allocated size of the receiver variable specified
in the user program, the results are not predictable. The minimum length is 8
bytes.</p>
</dd>
<dt><strong>Format name</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the writer message data returned.</p>
<table cellpadding="5">
<!-- cols="25 75" -->
<tr>
<td valign="top"><em><a href="#HDRSNDM100">SNDM0100</a></em></td>
<td valign="top">Contains the information about the message and its reply.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Message identifier</strong></dt>
<dd>INPUT; CHAR(7)
<p>The message identifier of the message to issue.</p>
</dd>
<dt><strong>Qualified message file name</strong></dt>
<dd>INPUT; CHAR(20)
<p>The name of the message file in which the message resides. The first 10
characters contain the message file name and the second 10 characters contain
the name of the library in which the message file is located. If this field is
blank, the system message file (QCPFMSG) is used.</p>
<p>The following special values are supported for the library name:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>*LIBL</em></td>
<td valign="top">The library list of the writer job is used to locate the
message file.</td>
</tr>
<tr>
<td valign="top"><em>*CURLIB</em></td>
<td valign="top">The current library for the writer job is used to locate the
message file.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Message data</strong></dt>
<dd>INPUT; CHAR(*)
<p>The data to insert in the predefined message's substitution variables</p>
</dd>
<dt><strong>Length of message data</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the message data in bytes. Value values are 1 through 512
bytes.</p>
</dd>
<dt><strong>Message type</strong></dt>
<dd>INPUT; CHAR(10)
<p>The type of the message.</p>
<p>The Values are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>*INFO</em></td>
<td valign="top">The message to be sent is an informational message.</td>
</tr>
<tr>
<td valign="top"><em>*INQ</em></td>
<td valign="top">The message to be sent is an inquiry message.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Message wait timeout</strong></dt>
<dd>INPUT; BINARY(4)
<p>The number of seconds to wait for a reply to an inquiry message. Any number
greater than 0 is valid. This parameter is only used for inquiry messages. It
is ignored for informational messages. The following special value is supported
for this parameter.</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>-1</em></td>
<td valign="top">The maximum wait time is be used.</td>
</tr>
</table>
<p><strong>Note:</strong> This parameter is only used for inquiry messages. It
is ignored for informational messages.</p>
</dd>
<dt><strong>Message key</strong></dt>
<dd>INPUT; CHAR(4)
<p>The key of the message whose wait status is cleared. This field is blank
when a message is being sent.</p>
</dd>
<dt><strong>Writer handle</strong></dt>
<dd>INPUT; CHAR(16)
<p>The handle to the writer job. This handle is provided to the driver program
on a writer call to the driver exit program during initialization.</p>
</dd>
<dt><strong>Coded character set identifier</strong></dt>
<dd>INPUT; BINARY(4)
<p>The coded character set identifier used to convert the message data supplied
as replacement text for message fields that correspond to *CCHAR type fields.
The data supplied that does not correspond to a *CCHAR field is 65535 and is
not converted. For more information about *CCHAR type fields, see the Add
Message Description (ADDMSGD) command.</p>
<p>The following values are allowed:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td valign="top"><em>0</em></td>
<td valign="top">The message data 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 valign="top"><em>65535</em></td>
<td valign="top">The message data is not be converted.</td>
</tr>
<tr>
<td valign="top"><em>CCSID</em></td>
<td valign="top">Specify a valid CCSID that your replacement data or impromptu
message is in. Valid values are between 1 and 65535. This API validates the
CCSID.
<p>For a list of valid CCSIDs, see the <a href=
"../nls/rbagsglobalmain.htm">Globalization</a> topic in the iSeries Information
Center.</p>
</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><a name="HDRSNDM100">SNDM0100 Format</a></h3>
<p>The following table shows the information returned for the SNDM0100 format.
For more details about the fields in the following table see, <a href=
"#QSPSNDWM_field">Field Descriptions</a>.</p>
<table border width="80%">
<tr>
<th align="center" valign="bottom" colspan="2">Offset</th>
<th align="left" valign="bottom" rowspan="2">Type</th>
<th align="left" valign="bottom" rowspan="2">Field</th>
</tr>
<tr>
<th align="center" valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">0</td>
<td align="center" valign="top" width="10%">0</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Bytes returned</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">Bytes available</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">CHAR(4)</td>
<td align="left" valign="top">Message key</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">CHAR(16)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">28</td>
<td align="center" valign="top">1C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Offset to message reply text</td>
</tr>
<tr>
<td align="center" valign="top">32</td>
<td align="center" valign="top">20</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of message reply text returned</td>
</tr>
<tr>
<td align="center" valign="top">36</td>
<td align="center" valign="top">24</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of message reply text available</td>
</tr>
<tr>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="left" valign="top">CHAR(*)</td>
<td align="left" valign="top">Message reply text</td>
</tr>
</table>
<br>
<h3><a name="QSPSNDWM_field">Field Descriptions</a></h3>
<p><strong>Bytes available.</strong> The number of bytes of data available to
be returned. All available data is returned if enough space is provided.</p>
<p><strong>Bytes returned.</strong> The number of bytes of data returned.</p>
<p><strong>Length of message reply text available.</strong> The length of the
message reply text that is available. This length is zero (0) for informational
messages or when the message wait timeout value was reached.</p>
<p><strong>Length of message reply text returned.</strong> The length of the
message reply text that is returned in the message reply text. This length is
zero (0) for informational messages or when the message wait timeout value was
reached.</p>
<p><strong>Message key.</strong> The key of the message issued. This can be
used with message handler APIs to perform various functions.</p>
<p><strong>Message reply text.</strong> The text of the reply received from the
inquiry message.</p>
<p><strong>Offset to message reply text.</strong> The offset to the message
reply text, in bytes.</p>
<p><strong>Reserved.</strong> The field is reserved.</p>
<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 width="15%" valign="top">CPF24A8 E</td>
<td width="85%" valign="top">Value for wait time not valid.</td>
</tr>
<tr>
<td valign="top">CPF24B3 E</td>
<td valign="top">Message type &amp;1 not valid.</td>
</tr>
<tr>
<td valign="top">CPF24B4 E</td>
<td valign="top">Severe error while addressing parameter list.</td>
</tr>
<tr>
<td valign="top">CPF247E E</td>
<td valign="top">CCSID &amp;1 is not valid.</td>
</tr>
<tr>
<td valign="top">CPF3CF1 E</td>
<td valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td valign="top">CPF3C19 E</td>
<td valign="top">Error occurred with receiver variable specified.</td>
</tr>
<tr>
<td valign="top">CPF3C1D E</td>
<td valign="top">Length specified in parameter &amp;1 not valid.</td>
</tr>
<tr>
<td valign="top">CPF3C21 E</td>
<td valign="top">Format name &amp;1 is not valid.</td>
</tr>
<tr>
<td valign="top">CPF3C4B E</td>
<td valign="top">Value not valid for field &amp;1.</td>
</tr>
<tr>
<td valign="top">CPF3C90 E</td>
<td valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td valign="top">CPF33CC E</td>
<td valign="top">No writer found for specified handle &amp;1.</td>
</tr>
<tr>
<td valign="top">CPF9872 E</td>
<td valign="top">Program or service program &amp;1 in library &amp;2 ended.
Reason code &amp;3.</td>
</tr>
</table>
<hr>
API introduced: V3R7
<hr>
<table cellpadding="2" cellspacing="2" align="center">
<tr align="center">
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
"print1.htm">Print APIs</a> | <a href="aplist.htm">APIs by
category</a></td>
</tr>
</table>
</body>
</html>