376 lines
13 KiB
HTML
376 lines
13 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>Open Path (QzdmOpenPath) 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>Open Path (QzdmOpenPath) API</h2>
|
|
|
|
<div class="box" style="width: 60%;">
|
|
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: *EXCLUDE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: No<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The Open Path (QzdmOpenPath) API is used to open an OptiConnect path. The Open Path (QzdmOpenPath) API returns a path identifier that is then required as input for subsequent OptiConnect APIs that require a path identifier.</p>
|
|
|
|
<br>
|
|
<h3>Restrictions</h3>
|
|
|
|
<p>The following restrictions apply:</p>
|
|
|
|
<ul>
|
|
<li>The OptiConnect QSOC subsystems 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 user profile must exist on the remote system by the same name as the user profile that is running the Open Path (QzdmOpenPath) API on the local system.
|
|
|
|
<p>It is the responsibility of the user to verify that the user profile name on the remote system is the same as the user profile name on the local system. The purpose of this verification is to ensure that the user's authority is the same on both systems.</p>
|
|
</li>
|
|
|
|
<li>If a job description (*JOBD) is specified in the user profile on the remote system, the job description must also reside on the remote system.<br><br></li>
|
|
|
|
<li>A maximum of 256 path identifiers may be opened for a single job.</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 Open Path (QzdmOpenPath) 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 Open Path (QzdmOpenPath) API. The OPRC0100 format is used by this API for the receiver variable. See <a href="#HDROPRC100">OPRC0100 Format</a> for more information on the OPRC0100 format.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Request variable</strong></dt>
|
|
<dd>INPUT; CHAR(*)
|
|
|
|
<p>The request variable structure that describes the input for the Open Path (QzdmOpenPath) 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 Open Path (QzdmOpenPath) API. The OPRQ0100 format is used by this API for the request variable. See <a href="#HDROPRQ100">OPRQ0100 Format</a> for more information on the OPRQ0100 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="HDROPRC100">OPRC0100 Format</a></h3>
|
|
|
|
<p>The following table defines the information returned for Format OPRC0100.</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%">Path identifier</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br><br>
|
|
<h3><a name="HDROPRQ100">OPRQ0100 Format</a></h3>
|
|
|
|
<p>The following table defines the information required for format OPRQ0100.</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%">Remote system name</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%">CHAR(10)</td>
|
|
<td align="left" valign="top" width="60%">Program name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">34</td>
|
|
<td align="center" valign="top" width="10%">22</td>
|
|
<td align="left" valign="top" width="20%">CHAR(10)</td>
|
|
<td align="left" valign="top" width="60%">Program library name</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br><br>
|
|
<h3><a name="HDROPTHFLD">Field Descriptions</a></h3>
|
|
|
|
<p><strong>Path identifier.</strong> The OptiConnect path that is to be used for communications. This field is provided as output with the Open Path (QzdmOpenPath) API. This field must then be provided as input on all subsequent OptiConnect APIs that require a path identifier.</p>
|
|
|
|
<p>The path identifier is associated with the stream identifier that is provided as input, as a stream-identifier and path-identifier pair. For most applications, this stream-identifier and path-identifier pair needs to be used for all subsequent OptiConnect APIs that are used to control communications on the local system.</p>
|
|
|
|
<p><strong>Remote system name.</strong> The name of the remote system to which the OptiConnect path is being opened. This is the current system name as displayed on the Display Network Attributes (DSPNETA) display on the remote system.</p>
|
|
|
|
<p><strong>Program name.</strong> The program name on the remote system that controls communications on the remote system. This program is called by the OptiConnect agent job (QZDMAGNT) on the remote system, and is passed a stream-identifier and path-identifier pair.</p>
|
|
|
|
<p>For most applications, this stream-identifier and path-identifier pair needs to be used for all subsequent OptiConnect APIs that are used to control communications on the remote system.</p>
|
|
|
|
<p><strong>Program library name.</strong> The program library name on the remote system in which the program is contained.</p>
|
|
|
|
<p><strong>Stream identifier.</strong> The OptiConnect stream that is to be used for communications. This field is provided as output on the Open Stream (QzdmOpenStream) API.</p>
|
|
|
|
<p>The stream identifier is associated with the path identifier that is provided as output, as a stream-identifier and path-identifier pair. For most applications, this stream-identifier and path-identifier pair needs to be used for all subsequent OptiConnect APIs that are used to control communications on the local system.</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">CPFADF2 E</td>
|
|
<td valign="top">OptiConnect path open error.</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>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFADF7 E</td>
|
|
<td valign="top">OptiConnect API open path error, function code &1, return code &2.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFADF8 E</td>
|
|
<td valign="top">Program name not found.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFADF9 E</td>
|
|
<td valign="top">Program library name not found.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFADFA E</td>
|
|
<td valign="top">User not authorized to program.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFADFB E</td>
|
|
<td valign="top">Open path rejected.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFADFD E</td>
|
|
<td valign="top">Remote system &1 not found or not valid.</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>
|
|
|