518 lines
16 KiB
HTML
518 lines
16 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>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>
|