406 lines
14 KiB
HTML
406 lines
14 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 Request (QzdmSendRequest) 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. -->
|
||
|
|
<!-- COMM4 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2DCIJB at -->
|
||
|
|
<!-- RCHVMW2 on 1 Jun 1999 at 17:32:50 -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- YYMMDD USERID Change description -->
|
||
|
|
<!--File Edited December, 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>Send Request (QzdmSendRequest) API</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 70%;">
|
||
|
|
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 of receiver variable</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">Request variable</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Char(*)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">5</td>
|
||
|
|
<td align="left" valign="top">Length of request variable</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">6</td>
|
||
|
|
<td align="left" valign="top">Format name of request variable</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Char(8)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">7</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>
|
||
|
|
Library Name / Service Program: QSOC/QZDMMDTA<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *EXECUTE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: No<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The Send Request (QzdmSendRequest) API is used to send a request or a message over an OptiConnect path. A maximum of 32KB of data may be transferred in a single send request.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Restrictions</h3>
|
||
|
|
|
||
|
|
<p>The following restrictions apply:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The OptiConnect QSOC subsystem must be started on both the local and remote systems prior to calling this API.<br><br></li>
|
||
|
|
|
||
|
|
<li>A stream must be opened to the OptiConnect device driver on the local system by using the Open Stream (QzdmOpenStream) API prior to calling this API.<br><br></li>
|
||
|
|
|
||
|
|
<li>A path must be opened to the remote system by using the Open Path (QzdmOpenPath) API prior to calling this API.<br><br></li>
|
||
|
|
|
||
|
|
<li>A maximum of 16 transactions may be in progress for a stream-identifier and path-identifier pair.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Authorities and Locks</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><em>Service Program Authority</em></dt>
|
||
|
|
<dd>*EXECUTE</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Required Parameter Group</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Receiver variable</strong></dt>
|
||
|
|
<dd>OUTPUT; CHAR(*)
|
||
|
|
|
||
|
|
<p>The receiver variable that is to receive the output control information from the Send Request (QzdmSendRequest) API.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Length of receiver variable</strong></dt>
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The length of the receiver variable, in bytes. The length of the receiver variable must be at least equal to or greater than the length of the output format.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Format name of receiver variable</strong></dt>
|
||
|
|
<dd>INPUT; CHAR(8)
|
||
|
|
|
||
|
|
<p>The format of the information that is returned from the Send Request (QzdmSendRequest) API. The SRRC0100 format is used by this API for the receiver variable. See <a href="#HDRSRRC100">SRRC0100 Format</a> for more information on the SRRC0100 format.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Request variable</strong></dt>
|
||
|
|
<dd>INPUT; CHAR(*)
|
||
|
|
|
||
|
|
<p>The request variable structure that describes the input for the Send Request (QzdmSendRequest) API.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Length of request variable</strong></dt>
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The length of the request variable, in bytes. The length of the request variable must be at least equal to the length of the input format, and less than or equal to the maximum length of 4KB.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Format name of request variable</strong></dt>
|
||
|
|
<dd>INPUT; CHAR(8)
|
||
|
|
|
||
|
|
<p>The format of the information that is provided as input for the Send Request (QzdmSendRequest) API. The SRRQ0100 format is used by this API for the request variable. See <a href="#HDRSRRQ100">SRRQ0100 Format</a> for more information on the SRRQ0100 format.</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="HDRSRRC100">SRRC0100 Format</a></h3>
|
||
|
|
|
||
|
|
<p>The following table defines the information returned for Format SRRC0100.</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(8)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Transaction identifier</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br><br>
|
||
|
|
<h3><a name="HDRSRRQ100">SRRQ0100 Format</a></h3>
|
||
|
|
|
||
|
|
<p>The following table defines the information required for Format SRRQ0100.</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(16)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Stream identifier</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">16</td>
|
||
|
|
<td align="center" valign="top" width="10%">10</td>
|
||
|
|
<td align="left" valign="top" width="20%">CHAR(8)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Path identifier</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">24</td>
|
||
|
|
<td align="center" valign="top" width="10%">18</td>
|
||
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Maximum response data length</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">28</td>
|
||
|
|
<td align="center" valign="top" width="10%">1C</td>
|
||
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Offset to input descriptors</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">32</td>
|
||
|
|
<td align="center" valign="top" width="10%">20</td>
|
||
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Number of input descriptors</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">36</td>
|
||
|
|
<td align="center" valign="top" width="10%">24</td>
|
||
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Offset to output descriptors</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">40</td>
|
||
|
|
<td align="center" valign="top" width="10%">28</td>
|
||
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Number of output descriptors</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">44</td>
|
||
|
|
<td align="center" valign="top" width="10%">2C</td>
|
||
|
|
<td align="left" valign="top" width="20%">CHAR(4)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Reserved</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" rowspan="3" colspan="2">These fields repeat for each input descriptor</td>
|
||
|
|
<td align="left" valign="top" width="20%">PTR(SPP)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Data buffer pointer</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Data buffer length</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="20%">CHAR(12)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Reserved</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" rowspan="3" colspan="2">These fields repeat for each output descriptor</td>
|
||
|
|
<td align="left" valign="top" width="20%">PTR(SPP)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Data buffer pointer</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Data buffer length</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" width="20%">CHAR(12)</td>
|
||
|
|
<td align="left" valign="top" width="60%">Reserved</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br><br>
|
||
|
|
<h3><a name="HDRSREQFLD">Field Descriptions</a></h3>
|
||
|
|
|
||
|
|
<p><strong>Data buffer length.</strong> The length of the data buffer that is used for the input or output data.</p>
|
||
|
|
|
||
|
|
<p><strong>Data buffer pointer.</strong> The pointer to the input data buffer that is used for input or output data.</p>
|
||
|
|
|
||
|
|
<p><strong>Maximum response data length.</strong> The maximum length that is allowed for the response data. This field is provided as output on the Receive Request (QzdmReceiveRequest) API and indicates the maximum response data length allowed for the Send Response (QzdmSendResponse) API. If the response data that is sent from the Send Response (QzdmSendResponse) API is larger than the buffer that is provided with the Send Request (QzdmSendRequest) API, not all of the data is received. It is the responsibility of the user's application program to retry the entire transaction by using a larger data buffer size for the Send Request (QzdmSendRequest) API to receive all of the data with the Receive Response (QzdmReceiveResponse) API.</p>
|
||
|
|
|
||
|
|
<p><strong>Number of output descriptors.</strong> The number of output descriptors that are used. An output descriptor describes where the output data that is to be received from the remote system may be found. The output descriptor consists of a space pointer to a data buffer and the length of the data buffer. A maximum of three output descriptors may be specified. The total length of the output buffers must be equal to the maximum response data length that is specified.</p>
|
||
|
|
|
||
|
|
<p><strong>Number of input descriptors.</strong> The number of input descriptors that are used. An input descriptor describes where the input data that is to be sent to the remote system may be found. The input descriptor consists of a space pointer to a data buffer and the length of the data buffer. A maximum of three input descriptors may be specified.</p>
|
||
|
|
|
||
|
|
<p><strong>Offset to output descriptors.</strong> The offset to the output descriptors.</p>
|
||
|
|
|
||
|
|
<p><strong>Offset to input descriptors.</strong> The offset to the input descriptors.</p>
|
||
|
|
|
||
|
|
<p><strong>Path identifier.</strong> The OptiConnect path that is used for communications. This field is provided as output on the Open Path (QzdmOpenPath) API.</p>
|
||
|
|
|
||
|
|
<p><strong>Reserved.</strong> A reserved space for the purpose of aligning pointer values on a 16-byte boundary. This field must be initialized to binary 0.</p>
|
||
|
|
|
||
|
|
<p><strong>Stream identifier.</strong> The OptiConnect stream that is used for communications. This field is provided as output on the Open Stream (QzdmOpenStream) API.</p>
|
||
|
|
|
||
|
|
<p><strong>Transaction identifier.</strong> The specific transaction associated with this Send Request. This field is provided as output on the Send Request (QzdmSendRequest) API. This field must then be provided as input on the corresponding Receive Response (QzdmReceiveResponse) API.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Error Messages</h3>
|
||
|
|
|
||
|
|
<table width="100%" cellpadding="3">
|
||
|
|
<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">CPF24B4 E</td>
|
||
|
|
<td valign="top">Severe error while addressing parameter list.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3C1D E</td>
|
||
|
|
<td valign="top">Length specified in parameter &1 not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3C21 E</td>
|
||
|
|
<td valign="top">Format name &1 is not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3C90 E</td>
|
||
|
|
<td valign="top">Literal value cannot be changed.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3CF1 E</td>
|
||
|
|
<td valign="top">Error code parameter not valid.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9872 E</td>
|
||
|
|
<td valign="top">Program or service program &1 in library &2 ended. Reason code &3.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPFADF0 E</td>
|
||
|
|
<td valign="top">The OptiConnect QSOC subsystem must be active.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPFADF1 E</td>
|
||
|
|
<td valign="top">OptiConnect communication error.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPFADF3 E</td>
|
||
|
|
<td valign="top">OptiConnect path not valid or closed.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPFADF5 E</td>
|
||
|
|
<td valign="top">OptiConnect API internal error, function code &1, return code &2.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPFADF6 E</td>
|
||
|
|
<td valign="top">Request variable not valid, reason code &1.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
API introduced: V3R7
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#top_Of_Page">Top</a> |
|
||
|
|
<a href="comm.htm">Communications APIs</a> | <a href="aplist.htm">APIs by
|
||
|
|
category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|