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

555 lines
17 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 Data Queue (QSNDDTAQ) 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. -->
<!-- QSNDDTAQ SCRIPT A converted by B2H R4.1 (346) (CMS) by PMHALL at -->
<!-- RCHVMW2 on 7 Oct 1998 at 10:05:11 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- Edited by Kersten Jan 02 -->
<!-- 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 Data Queue (QSNDDTAQ) 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%">Data queue name</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(10)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Library name</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">Length of data</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Packed(5,0)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Data</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
</table>
<br>
&nbsp;&nbsp;Optional Parameter Group 1:<br>
<!-- iddvc RMBR -->
<br>
<table width="100%">
<tr>
<td align="center" valign="top" width="10%">5</td>
<td align="left" valign="top" width="50%">Length of key data</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Packed(3,0)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Key data</td>
<td align="left" valign="top">Input</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%">7</td>
<td align="left" valign="top" width="50%">Asynchronous request</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(10)</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%">8</td>
<td align="left" valign="top" width="50%">Data is from a journal entry</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(10)</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><br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Send Data Queue (QSNDDTAQ) API sends data to the specified data queue.
When an entry is sent to a standard data queue, the storage allocated for each
entry will be the value specified for the maximum entry length on the Create
Data Queue (CRTDTAQ) command.</p>
<p>Distributed data management (DDM) data queues are supported using this API.
This means that you can use this API to send data to a data queue that exists
on a remote iSeries.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Data Queue Authority</em></dt>
<dd>*OBJOPR and *ADD<br><br></dd>
<dt><em>Data Queue Library Authority</em></dt>
<dd>*EXECUTE<br><br></dd>
<dt><em>When using optional parameter group 3 and the journal entry was
deposited for a data queue with the sender ID attribute set to *YES, authority
to the current profile in the sender ID of the journal entry</em></dt>
<dd>*USE<br><br></dd>
<dt><em>Data Queue Lock</em></dt>
<dd>*EXCLRD</dd>
</dl>
<p>Internally, when a job uses API QSNDDTAQ (Send Data Queue), QRCVDTAQ
(Receive Data Queue), QMHQRDQD (Retrieve Data Queue Description), or QMHRDQM
(Retrieve Data Queue Message), a cache is created to allow faster access to the
data queue. An entry in the cache means a user is authorized to the data queue.
An entry is added to the cache when a user calling one of the APIs has the
required authority to the data queue. An entry is also added to the cache when
QSNDDTAQ is called to handle a journal entry for a data queue created with the
sender ID attribute set to *YES, and the user requesting the the send function
has the required authority to the current profile name in the sender ID
information of the journal entry. The data in the cache is used until the job
ends, so if you need to immediately change a user's authority to one of these
objects, you may need to end that user's jobs.</p>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Data queue name</strong></dt>
<dd>INPUT; CHAR(10)
<p>The name of the data queue to send the data to.</p>
</dd>
<dt><strong>Library name</strong></dt>
<dd>INPUT; CHAR(10)
<p>The name of the library where the data queue resides.</p>
<p>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>
<p><strong>Note:</strong> To improve data queue performance, the data queue
APIs remember addressing information for the last data queues used. This occurs
when a specific (not *LIBL or *CURLIB) value is provided for the library name,
and the data queue is located
in the system auxiliary storage pool (ASP number 1) or a basic user ASP (ASP
numbers 2-32). The addressing information for data queues located in
independent ASPs is not saved.</p>
<p>Because the addressing information is saved, users of this API should be
aware of the following scenarios.</p>
<p><strong>Scenario 1</strong></p>
<p>If, a job references a library-specific data queue, the data queue is moved
using the Move Object (MOVOBJ) command or renamed using the Rename Object
(RNMOBJ) command, and a new data queue is created with the same name and
library as the data queue that was renamed or moved, then, the job continues to
reference the original data queue, not the newly created data queue.</p>
<p><strong>Scenario 2</strong></p>
<p>If, a job references a library-specific distributed data management (DDM)
data queue, the DDM data queue is moved using the Move Object (MOVOBJ) command
or renamed using the Rename Object (RNMOBJ) command, and a new data queue is
created with the same name and library as the DDM data queue that was renamed
or moved, then, the job continues to reference the original DDM data queue, not
the newly created data queue.</p>
<p><strong>Scenario 3</strong></p>
<p>If, a job references a DDM data queue, which starts a DDM target job (DDM
conversation) on a remote system that references a library-specific data queue,
the data queue on the remote system is moved using the Move Object (MOVOBJ)
command or renamed using the Rename Object (RNMOBJ) command, and on the remote
system, a new data queue is created with the same name and library as the data
queue that was renamed or moved, then, the DDM target job continues to
reference the original data queue on the remote system, not the newly created
data queue, only when the same DDM target job is used for the subsequent data
queue operation. If a new DDM target job is used for the subsequent data queue
operation, then the newly created data queue will be used on the remote
system.</p>
<p><strong>Note:</strong> For more information on creating DDM data queues and
on DDM target jobs, see <a href="../ddm/rbae5kickoff.htm">Distributed Data
Management</a> in the iSeries Information Center.</p>
</dd>
<dt><strong>Length of data</strong></dt>
<dd>INPUT; PACKED(5,0)
<p>The number of characters to be sent to the data queue.</p>
<p><strong>Note:</strong> An error occurs if the value specified is greater
than the length specified by the maximum lenght (MAXLEN) parameter on the
Create Data Queue (CRTDTAQ) command, unless optional parameter group 3 is
specified. With optional parameter group 3, the length of the data provided in
the journal entry should be specified, and it could be longer than the maximum
entry length. This will be handled appropriately by the API.</p>
</dd>
<dt><strong>Data</strong></dt>
<dd>INPUT; CHAR(*)
<p>The data to be sent to the data queue.</p>
<p><strong>Note:</strong> If the length of this field is larger than the length
of data parameter, only the number of characters (beginning from the left) as
defined by the length of data parameter are sent to the data queue. If the
length of this variable is smaller than the length of data parameter,
unexpected results can occur.</p>
</dd>
</dl>
<br>
<h3>Optional Parameter Group 1</h3>
<dl>
<dt><strong>Length of key data</strong></dt>
<dd>INPUT; PACKED(3,0)
<p>The number of characters in the key data parameter.</p>
<p><strong>Note:</strong> The maximum value is the value that is specified on
the KEYLEN parameter on the Create Data Queue (CRTDTAQ) command.</p>
</dd>
<dt><strong>Key data</strong></dt>
<dd>INPUT; CHAR(*)
<p>The data sent to the data queue. This value must be at least as long as the
value specified in the length of key data parameter; otherwise, unexpected
results can occur.</p>
</dd>
</dl>
<br>
<h3>Optional Parameter Group 2</h3>
<dl>
<dt><strong>Asynchronous request</strong></dt>
<dd>INPUT; CHAR(10)
<p>Whether the send data queue request to a DDM data queue should be processed
asynchronously. This parameter only applies to DDM data queues. Valid values
are *YES and *NO. An error will occur if *YES is specified for a non-DDM data
queue. If the value *YES is specified for the asynchronous request parameter
for a DDM data queue and an error occurs on the operation, the error will not
be detected until the next time the data queue is accessed.</p>
<p><strong>Note:</strong> If this parameter is specified, the key length and
key data parameters must also be specified even if they are not applicable. In
that event, the key length should be zero and blanks should be specified for
the key data.</p>
</dd>
</dl>
<br>
<h3>Optional Parameter Group 3</h3>
<dl>
<dt><strong>Data is from a journal entry</strong></dt>
<dd>INPUT; CHAR(10)
<p>Indicate whether the data, in parameter four, came from a journal entry.
This parameter only applies to a non-DDM data queue. Valid values are *YES and
*NO.</p>
<p>When using this paramter the data queue needs to have the same attributes as
the journaled data queue. To ensure the attributes of the data queue are the
same as the journaled data queue, save the journaled data queue and restore it
to the system where this API will be called with optional parameter group 3
specified. Refer to <a href="../rzaki/rzakikickoff.htm">Journal management</a>
for information on journaling.</p>
<p><strong>Note:</strong> When using this parameter, the length of data in
parameter three should be obtained from the journal entry. The length could be
longer than the maximum entry length of the data queue and this will be handled
appropriately by the API, an error will not be issued.</p>
<p><strong>Note:</strong> If this parameter is specified, the key length, key
data, and asynchronous request parameters must also be specified even if they
are not applicable. In that event, the key length should be zero, key data
should be blanks and *NO should be specified for the asynchronous request.</p>
</dd>
</dl>
<br>
<h3><a name="usage_notes">Usage Notes</a></h3>
<p>This API can be used in a multithreaded job to send entries to a non-DDM
data queue. It cannot be used in a job that allows multiple threads to send
entries to a DDM data queue.</p>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top" nowrap>Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td align="left" valign="top">CPF2207 E</td>
<td align="left" valign="top">Not authorized to use object &amp;1 in library
&amp;3 type *&amp;2.</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">CPF2498 E</td>
<td align="left" valign="top">Invalid length. MAXLEN for data queue &amp;1 in
&amp;2 is &amp;3.</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">CPF6565 E</td>
<td align="left" valign="top">User profile storage limit exceeded.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9501 E</td>
<td align="left" valign="top">Data queue &amp;1 in &amp;2 requires a key
value.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9502 E</td>
<td align="left" valign="top">Key length must be zero for data queue &amp;1 in
&amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9503 E</td>
<td align="left" valign="top">Cannot lock data queue &amp;1 in &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9506 E</td>
<td align="left" valign="top">Key length must be &amp;3 for data queue &amp;1
in &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9507 E</td>
<td align="left" valign="top">Invalid key length specified.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9509 E</td>
<td align="left" valign="top">Space access error.</td>
</tr>
<tr>
<td align="left" valign="top">CPF950A E</td>
<td align="left" valign="top">Storage limit exceeded for data queue &amp;1 in
&amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9510 E</td>
<td align="left" valign="top">Operation on DDM data queue &amp;1 in &amp;2
failed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9512 E</td>
<td align="left" valign="top">Invalid asynchronous request.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9513 E</td>
<td align="left" valign="top">Asynchronous request must be *NO for data queue
&amp;1 in &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9520 E</td>
<td align="left" valign="top">Value for data is from a journal entry is not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9521 E</td>
<td align="left" valign="top">Entry not sent. Data queue attributes do not
match.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9522 E</td>
<td align="left" valign="top">Entry not sent. Data from a journal entry is not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9523 E</td>
<td align="left" valign="top">Data queue function not successful.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9801 E</td>
<td align="left" valign="top">Object &amp;2 in library &amp;3 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9802 E</td>
<td align="left" valign="top">Not authorized to object &amp;2 in &amp;3.</td>
</tr>
<tr><!-- CPF9803 is sent as a diagnostic when PEX is being used and -->
<!-- another job has the dtaq allocated. This only indicates that -->
<!-- the queue depth is not correct; the message will still be -->
<!-- sent. -->
<td align="left" valign="top">CPF9803 D</td>
<td align="left" valign="top">Cannot allocate object &amp;2 in library &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9807 E</td>
<td align="left" valign="top">One or more libraries in library list
deleted.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9808 E</td>
<td align="left" valign="top">Cannot allocate one or more libraries on library
list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9810 E</td>
<td align="left" valign="top">Library &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9820 E</td>
<td align="left" valign="top">Not authorized to use library &amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9830 E</td>
<td align="left" valign="top">Cannot assign library &amp;1.</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: V1R1
<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=
"obj1.htm">Object APIs</a> | <a href="aplist.htm">APIs by
category</a></td>
</tr>
</table>
</body>
</html>