friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
0332907f0f
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/comm3.htm

518 lines
16 KiB
HTML
Raw Normal View History

Add readme and dist folders
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>Configuration and Queue Entries</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 -->
<!-- COMM3 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2DCIJB at -->
<!-- RCHVMW2 on 1 Jun 1999 at 17:33:38 -->
<!--File Edited November 2001 -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<!--Java sync-link -->
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
</script>
<h2>Configuration and Queue Entries</h2>
<ul>
<li>Configure user-defined communications support<br>
<br>
</li>
<li>Set up the entries that user-defined communications support can send to the
queue</li>
</ul>
<br>
<h3><a name="HDRCNFIGCH">Configuring User-Defined Communications
Support</a></h3>
<p>This section describes what needs to be configured before your application
program can use the user-defined communications APIs. You can either use the
system-supplied menus or the Control Language (CL) commands to do this
configuration. For more information on using queue APIs, see the <a href=
"obj1.htm">Object APIs</a> in the Information Center.</p>
<br>
<h3><a name="Header_3">Links</a></h3>
<p>Links allow your application program to use a token-ring, Ethernet, FDDI,
wireless, or X.25 communications line. A link is made up of the following
communications objects:</p>
<ul>
<li>Token-ring, Ethernet, FDDI, wireless, or X.25 line description<br>
<br>
</li>
<li>Network controller description<br>
<br>
</li>
<li>Network device description of type *USRDFN<br>
<br>
</li>
<li>Network interface description for ISDN (X.25 only)</li>
</ul>
<p>You need to configure the line description; user-defined communications
support automatically configures a network controller and a network device
description of type *USRDFN when the link is enabled. If you are using X.25
over ISDN, the network interface description must also be configured. The
network interface, line, controller, and device descriptions are automatically
varied on, if necessary.</p>
<p>Use the following commands to create or change line descriptions:</p>
<ul>
<li>CRTLINDDI -- Create Line Description (DDI)<br>
<br>
</li>
<li>CHGLINDDI -- Change Line Description (DDI)<br>
<br>
</li>
<li>CRTLINETH -- Create Line Description (Ethernet)<br>
<br>
</li>
<li>CHGLINETH -- Change Line Description (Ethernet)<br>
<br>
</li>
<li>CRTLINTRN -- Create Line Description (Token-Ring)<br>
<br>
</li>
<li>CHGLINTRN -- Change Line Description (Token-Ring)<br>
<br>
</li>
<li>CRTLINWLS -- Create Line Description (Wireless)<br>
<br>
</li>
<li>CHGLINWLS -- Change Line Description (Wireless)<br>
<br>
</li>
<li>CRTLINX25 -- Create Line Description (X.25)<br>
<br>
</li>
<li>CHGLINX25 -- Change Line Description (X.25)</li>
</ul>
<p>Use the following commands to create or change controller descriptions:</p>
<ul>
<li>CRTCTLNET -- Create Controller Description (Network)<br>
<br>
</li>
<li>CHGCTLNET -- Change Controller Description (Network)</li>
</ul>
<p>Use the following commands to create or change device descriptions:</p>
<ul>
<li>CRTDEVNET -- Create Device Description (Network)<br>
<br>
</li>
<li>CHGDEVNET -- Change Device Description (Network)</li>
</ul>
<p>Use the following commands to create or change network interface
descriptions:</p>
<ul>
<li>CRTNWIISDN -- Create Network Interface Description (ISDN)<br>
<br>
</li>
<li>CHGNWIISDN -- Change Network Interface Description (ISDN)</li>
</ul>
<p>See the <a href="../booksc4154010.pdf">Communications
Configuration</a><img src="wbpdf.gif" alt="Link to PDF"> book
on the V5R1 Supplemental Manuals Web site for more
information on configuring communications.</p>
<br>
<h3>Queue</h3>
<p>User-defined communications support uses a queue to inform your application
program of some action to take or of an activity that is complete. You must
create the queue before the link is enabled.</p>
<p>The size of each queue entry must be large enough to accommodate the
user-defined communications support entries. See the following <a href=
"#HDRDATAQCH">Queue Entries</a> for more information on the entries that
user-defined communications support can send to the queue.</p>
<p>Use the Create Data Queue (CRTDTAQ) command to create your data queues. Use
the QUSCRTUQ and QUSDLTUQ APIs to create and delete your user queues.</p>
<hr>
<h2><a name="HDRDATAQCH">Queue Entries</a></h2>
<p>This section describes the entries user-defined communications support can
send to the queue.</p>
<br>
<h3>General Format</h3>
<p>The length of each entry is always at least 80 bytes. When using a keyed
queue, however, each entry can be as large as 336 bytes, depending on the size
of the key value supplied to the user-defined communications support.</p>
<p><a href="#FIGDTAQGFG">Table 1</a> shows the general format of each
user-defined communications support entry.</p>
<p><strong><a name="FIGDTAQGFG">Table 1. Queue Entry General
Format</a></strong></p>
<table border width="80%">
<tr>
<th valign="top">Entry type Char(10)</th>
<th valign="top">Entry ID Char(2)</th>
<th valign="top">Entry data Char(68)</th>
<th valign="top">Key CHAR(256)</th>
</tr>
<tr>
<td align="center" valign="top" width="25%">Bytes 1-10</td>
<td align="center" valign="top" width="25%">11-12</td>
<td align="center" valign="top" width="25%">13-80</td>
<td align="center" valign="top" width="25%">81-336</td>
</tr>
</table>
<p><strong>Entry type</strong></p>
<p>This indicates the type of entry on the queue and will be *USRDFN for all
user-defined communications support entries.</p>
<p><strong>Entry ID</strong></p>
<p>This uniquely identifies each entry within an entry type. User-defined
communications support has five entries defined:</p>
<ul>
<li>Enable-complete entry (entry ID = '00')<br>
<br>
</li>
<li>Disable-complete entry (entry ID = '01')<br>
<br>
</li>
<li>Permanent-link-failure entry (entry ID = '02')<br>
<br>
</li>
<li>Incoming-data entry (entry ID = '03')<br>
<br>
</li>
<li>Timer-expired entry (entry ID = '04')</li>
</ul>
<p><strong>Note:</strong> The entry type of *USRDFN and all associated entry
IDs, either defined or undefined, are reserved for user-defined communications
support. Therefore, your application program should not define entries using
this entry type.</p>
<p><strong>Entry data</strong></p>
<p>This data is useful to your application program and varies according to the
entry ID.</p>
<p><strong>Key</strong></p>
<p>When using a keyed queue, this is the key value supplied to the user-defined
communications support.</p>
<br>
<h3><a name="HDRECPLTEN">Enable-Complete Entry</a></h3>
<p>The enable-complete entry is sent to the queue when the enable link
operation is complete. This entry is only sent after the Enable Link (QOLELINK)
API returns to your application program with a successful return and reason
code.</p>
<p><strong>Note:</strong> The QOLELINK API only initiates the enabling of the
link. Your application program must wait for the enable-complete entry before
attempting to perform input or output on the link.</p>
<p><a href="#FIGDTAQEFG">Table 2</a> shows the format of the enable-complete
entry.</p>
<p><strong><a name="FIGDTAQEFG">Table 2. Enable-Complete
Entry</a></strong></p>
<table border width="80%">
<tr>
<th valign="top">*USRDFN</th>
<th valign="top">'00'</th>
<th valign="top">Communications handle</th>
<th valign="top">Status</th>
<th valign="top">Reserved</th>
<th valign="top">Key</th>
</tr>
<tr>
<td align="center" valign="top" width="17%">Bytes 1-10</td>
<td align="center" valign="top" width="17%">11-12</td>
<td align="center" valign="top" width="17%">13-22</td>
<td align="center" valign="top" width="17%">23</td>
<td align="center" valign="top" width="16%">24-80</td>
<td align="center" valign="top" width="16%">81-336</td>
</tr>
</table>
<p><strong>Communications handle</strong></p>
<p>The name of the link that is being enabled. Your application program
supplies this name when the QOLELINK API is called.</p>
<p><strong>Status</strong></p>
<p>This indicates the outcome of the enable link operation. A character value
of zero indicates the enable link operation was successful and I/O is now
possible on this link. A character value of one indicates the enable link
operation was not successful (the job log contains messages indicating the
reason). The user-defined communications support disables the link when the
enable link operation does not complete successfully and the disable-complete
entry is not sent to the queue.</p>
<p><strong>Key</strong></p>
<p>The key value associated with the enable-complete entry when using a keyed
queue. Your application program supplies this key value when the QOLELINK API
is called. When using a non-keyed queue (indicated by supplying a key length of
zero to the QOLELINK API) this field is not present.</p>
<br>
<h3><a name="HDRDCPLTEN">Disable-Complete Entry</a></h3>
<p>The disable-complete entry is sent to the queue when a link is successfully
disabled. This entry is always the last entry sent by the user-defined
communications support on this link and, therefore, provides a way for your
application program to remove any enable-complete, incoming-data, or
permanent-link-failure entries previously sent to the queue.</p>
<blockquote>
<p><strong>Note:</strong> User-defined communications support does not
associate timers with links. Therefore, it is possible for a timer-expired
entry to be sent to the queue after the link is disabled. Your user-defined
communications application program is responsible for handling this.</p>
</blockquote>
<p><a href="#FIGDTAQDFG">Table 3</a> shows the format of the disable-complete
entry.</p>
<p><strong><a name="FIGDTAQDFG">Table 3. Disable-Complete
Entry</a></strong></p>
<table border width="80%">
<tr>
<th valign="top">*USRDFN</th>
<th valign="top">'01'</th>
<th valign="top">Communications handle</th>
<th valign="top">Reserved</th>
<th valign="top">Key</th>
</tr>
<tr>
<td align="center" valign="top" width="20%">Bytes 1-10</td>
<td align="center" valign="top" width="20%">11-12</td>
<td align="center" valign="top" width="20%">13-22</td>
<td align="center" valign="top" width="20%">23-80</td>
<td align="center" valign="top" width="20%">81-336</td>
</tr>
</table>
<p><strong>Communications handle</strong></p>
<p>The name of the link that has been disabled. Your application program
supplies this name when the QOLELINK API is called to enable the link.</p>
<p><strong>Key</strong></p>
<p>The key value associated with the disable-complete entry, when using a keyed
queue. Your application program supplies this key value when the QOLELINK API
is called to enable the link. When using a non-keyed queue (indicated by
supplying a key length of zero to the QOLELINK API) this field is not
present.</p>
<br>
<h3><a name="HDRPLFLREN">Permanent-Link-Failure Entry</a></h3>
<p>The permanent-link-failure entry is sent to the queue when error recovery is
canceled on a link. You must disable and then enable the link to recover.</p>
<p><a href="#FIGDTAQPFG">Table 4</a> shows the format of the
permanent-link-failure entry.</p>
<p><strong><a name="FIGDTAQPFG">Table 4. Permanent-Link-Failure
Entry</a></strong></p>
<table border width="80%">
<tr>
<th valign="top">*USRDFN</th>
<th valign="top">'02'</th>
<th valign="top">Communications handle</th>
<th valign="top">Reserved</th>
<th valign="top">Key</th>
</tr>
<tr>
<td align="center" valign="top" width="20%">Bytes 1-10</td>
<td align="center" valign="top" width="20%">11-12</td>
<td align="center" valign="top" width="20%">13-22</td>
<td align="center" valign="top" width="20%">23-80</td>
<td align="center" valign="top" width="20%">81-336</td>
</tr>
</table>
<p><strong>Communications handle</strong></p>
<p>The name of the link on which the failure has occurred. Your application
program supplies this name when the QOLELINK API is called to enable the
link.</p>
<p><strong>Key</strong></p>
<p>The key value associated with the permanent-link-failure entry, when using a
keyed queue. Your application program supplies this key value when the QOLELINK
API is called to enable the link. When using a non-keyed queue (indicated by
supplying a key length of zero to the QOLELINK API) this field is not
present.</p>
<br>
<h3><a name="HDRIDATAEN">Incoming-Data Entry</a></h3>
<p>The incoming-data entry is sent to the queue when the user-defined
communications support has data for your application program to receive. Your
application program should call the Receive Data (QOLRECV) API to pick up the
data when this entry is received.</p>
<p><strong>Note:</strong> Another incoming-data entry is not sent to the queue
until your application program picks up all the data from the user-defined
communications support. The data available parameter on the call to the QOLRECV
API indicates that the receipt of data is not complete.</p>
<p><a href="#FIGDTAQIFG">Table 5</a> shows the format of the incoming-data
entry.</p>
<p><strong><a name="FIGDTAQIFG">Table 5. Incoming-Data Entry</a></strong></p>
<table border width="80%">
<tr>
<th valign="top">*USRDFN</th>
<th valign="top">'03'</th>
<th valign="top">Communications handle</th>
<th valign="top">Reserved</th>
<th valign="top">Key</th>
</tr>
<tr>
<td align="center" valign="top" width="20%">Bytes 1-10</td>
<td align="center" valign="top" width="20%">11-12</td>
<td align="center" valign="top" width="20%">13-22</td>
<td align="center" valign="top" width="20%">23-80</td>
<td align="center" valign="top" width="20%">81-336</td>
</tr>
</table>
<p><strong>Communications handle</strong></p>
<p>The name of the link on which the data has come in. Your application program
supplies this name when the QOLELINK API is called to enable the link.</p>
<p><strong>Key</strong></p>
<p>The key value associated with the incoming-data entry, when using a keyed
queue. Your application program supplies this key value when the QOLELINK API
is called to enable the link. When using a non-keyed queue (indicated by
supplying a key length of zero to the QOLELINK API) this field is not
present.</p>
<br>
<h3><a name="HDRTMREXEN">Timer-Expired Entry</a></h3>
<p>The timer-expired entry is sent to the queue when a timer, previously set by
your application program, ends.</p>
<p><a href="#FIGDTAQTFG">Table 6</a> shows the format of the timer-expired
entry.</p>
<p><strong><a name="FIGDTAQTFG">Table 6. Timer-Expired Entry</a></strong></p>
<table border width="80%">
<tr>
<th valign="top">*USRDFN</th>
<th valign="top">'04'</th>
<th valign="top">Timer handle</th>
<th valign="top">User data</th>
<th valign="top">Key</th>
</tr>
<tr>
<td align="center" valign="top" width="20%">Bytes 1-10</td>
<td align="center" valign="top" width="20%">11-12</td>
<td align="center" valign="top" width="20%">13-20</td>
<td align="center" valign="top" width="20%">21-80</td>
<td align="center" valign="top" width="20%">81-336</td>
</tr>
</table>
<p><strong><a name="Header_25">Timer handle</a></strong></p>
<p>The name of the expired (ended) timer. Your application program returns this
name when the Set or Cancel Timer (QOLTIMER) API is called to set the
timer.</p>
<p><strong>User data</strong></p>
<p>The data associated with the expired timer. Your application program
supplies this data when the QOLTIMER API is called to set the timer.</p>
<p><strong>Key</strong></p>
<p>The key value associated with the timer-expired entry, when using a keyed
queue. Your application program supplies this key value when the QOLTIMER API
is called to set the timer. When using a non-keyed queue (indicated by
supplying a key length of zero to the QOLTIMER API) this field is not
present.</p>
<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>
Reference in New Issue Copy Permalink