545 lines
19 KiB
HTML
545 lines
19 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>User-Defined Communications</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 -->
|
|
<!-- Print SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
|
|
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
|
|
<!-- File Edited November 2001 -->
|
|
<!-- Graphics included: RBAFX604, 605, 606 -->
|
|
<!-- 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>User-Defined Communications</h2>
|
|
|
|
<p>User-defined communications support is a set of application program
|
|
interfaces (APIs) that are part of the Operating System/400<sup>(R)</sup>
|
|
(i5/OS<SUP>(R)</SUP>) licensed program. These callable routines allow customers to write their
|
|
own communications protocol stacks above the iSeries<SUP>(TM)</SUP> data link and physical layer
|
|
support. The term <strong>user-defined communications</strong> is used here to
|
|
describe this communications protocol support. The term <strong>application
|
|
program</strong> refers to a user-supplied communications application
|
|
program.</p>
|
|
|
|
<p>This article defines the user-defined communications support and describes
|
|
how to write protocols using the APIs. In addition, it provides two C language
|
|
program examples that illustrate the use of the APIs while performing a simple
|
|
file transfer between two systems attached to an X.25 packet switched
|
|
network.</p>
|
|
|
|
<hr>
|
|
<h3><a name="HDROVIEWCH">Overview</a></h3>
|
|
|
|
<p>The user-defined communications APIs allow your application programs to send
|
|
and receive data, and do specialized functions such as setting timers.</p>
|
|
|
|
<p>Your application programs need to work with the following:</p>
|
|
|
|
<ul>
|
|
<li>User-defined communications support<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Input/output buffers and descriptors<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>A queue</li>
|
|
</ul>
|
|
|
|
<a href="#FIGOVIEWFG">Figure 1-1</a> shows an overview of the user-defined
|
|
communications support.
|
|
|
|
<p><strong><a name="FIGOVIEWFG">Figure 1-1. User-Defined Communications
|
|
Support</a></strong></p>
|
|
|
|
<p><img src="RBAFX604.gif" alt="User-Defined Communications Support"></p>
|
|
|
|
<br>
|
|
<h3><a name="Header_3">User-Defined Communications Callable Routines</a></h3>
|
|
|
|
<p>The APIs provided by the i5/OS licensed program are callable routines that
|
|
allow an application program to start, perform, and end communications, and
|
|
perform specialized functions such as setting timers. These routines are listed
|
|
below and are discussed in detail in <a href="comm4.htm">User-Defined
|
|
Communications Support APIs</a>.</p>
|
|
|
|
<ul>
|
|
<li>Disable Link (QOLDLINK) ends communications<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Enable Link (QOLELINK) starts communications<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Query Line Description (QOLQLIND)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Receive Data (QOLRECV)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Send Data (QOLSEND)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Set Filter (QOLSETF) for inbound routing information<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Set Timer (QOLTIMER) sets or cancels a timer</li>
|
|
</ul>
|
|
|
|
<br>
|
|
<h3>Input/Output Buffers and Descriptors</h3>
|
|
|
|
<p>The input/output buffers and descriptors are user space objects (*USRSPC)
|
|
that contain and describe the data an application program is sending or
|
|
receiving. There are separate buffers and descriptors for input and output.</p>
|
|
|
|
<p>When an application program is ready to send data, it fills the output
|
|
buffer with data and provides a description of that data in the output buffer
|
|
descriptor. Similarly, when an application program receives data, the
|
|
user-defined communications support fills the input buffer with data and
|
|
provides a description of that data in the input buffer descriptor.</p>
|
|
|
|
<p>The i5/OS licensed program also provides callable APIs to allow an
|
|
application program to manipulate the data in the user spaces. Some of these
|
|
APIs are listed below.</p>
|
|
|
|
<ul>
|
|
<li>Change User Space (QUSCHGUS)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Retrieve Pointer to User Space (QUSPTRUS)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Retrieve User Space (QUSRTVUS)</li>
|
|
</ul>
|
|
|
|
<p>See <a href="obj5.htm">User Space APIs</a> for more information.</p>
|
|
|
|
<br>
|
|
<h3>Queues</h3>
|
|
|
|
<p>A queue is used by the user-defined communications support to inform an
|
|
application program of some action to perform or of an activity that is
|
|
complete.</p>
|
|
|
|
<p>The i5/OS licensed program provides APIs that allow your application
|
|
programs to manipulate the data and user queues. Some of these callable APIs
|
|
are listed below.</p>
|
|
|
|
<ul>
|
|
<li>Clear Data Queue (QCLRDTAQ)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Create User Queue (QUSCRTUQ)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Delete User Queue (QUSDLTUQ)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Receive Data Queue (QRCVDTAQ)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Send Data Queue (QSNDDTAQ)</li>
|
|
</ul>
|
|
|
|
<p>See the <a href="../rbam6/clpro.htm">CL Programming</a> topic for more
|
|
information on data queues.</p>
|
|
|
|
<br>
|
|
<h2><a name="HDROVCNCPT">Terminology</a></h2>
|
|
|
|
<p>Listed below are terms that are important in understanding the information
|
|
contained in this part.</p>
|
|
|
|
<p><strong>Communications handle.</strong> The name an application program
|
|
assigns and uses to refer to a link.</p>
|
|
|
|
<p><strong>Connection.</strong> The logical communication path from one
|
|
computer system to another. For example, a switched virtual circuit (SVC)
|
|
connection on an X.25 network.</p>
|
|
|
|
<p><strong>Connectionless service.</strong> A method of operation where data
|
|
can be sent to and received from the remote computer system without
|
|
establishing a connection to it. User-defined communications support provides
|
|
connectionless service over token-ring, Ethernet, fiber distributed data
|
|
interface (FDDI), wireless and X.25 networks only. For a local area network
|
|
(LAN) environment, connectionless service is also known as unacknowledged
|
|
service.</p>
|
|
|
|
<p><strong>Connection-oriented service.</strong> A method of operation where a
|
|
connection to the remote computer system must first be established before data
|
|
can be sent to it or received from it. User-defined communications support
|
|
provides connection-oriented service over X.25 networks only.</p>
|
|
|
|
<p><strong>Connection identifier.</strong> A local identifier (ID) that a
|
|
computer system uses to distinguish one connection from another. When using the
|
|
user-defined communications support on the server, a connection ID is made up
|
|
of a user connection end point ID and a provider connection end point ID.</p>
|
|
|
|
<p><strong>Disable.</strong> The process of deactivating a link so that input
|
|
and output operations are no longer possible on a communications line.</p>
|
|
|
|
<p><strong>Enable.</strong> The process of setting up and activating a link for
|
|
input and output operations on a communications line.</p>
|
|
|
|
<p><strong>Filter.</strong> The technique used to route inbound data to a link
|
|
that is enabled by an application program.</p>
|
|
|
|
<p><strong>Link.</strong> The logical path between an application program and a
|
|
communications line. A link is made up of the following communications
|
|
objects:</p>
|
|
|
|
<ul>
|
|
<li>Network interface description running X.25 over ISDN<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>X.25, token-ring, fiber distributed data interface (FDDI), Ethernet, or
|
|
wireless line description<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Network controller description<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Network device description of type *USRDFN</li>
|
|
</ul>
|
|
|
|
<p><strong>Provider connection end point ID (PCEP ID).</strong> The portion of
|
|
the connection ID that the user-defined communications support uses to identify
|
|
the connection. For example, data sent by the application program will be on
|
|
the PCEP ID portion of the connection ID.</p>
|
|
|
|
<p><strong>User connection end point ID (UCEP ID).</strong> The portion of the
|
|
connection ID that the application program uses to identify the connection. For
|
|
example, data received by the application program is on the UCEP ID portion of
|
|
the connection ID.</p>
|
|
|
|
<br>
|
|
<h2>Relationship to Communications Standards</h2>
|
|
|
|
<p><a href="#FIGAPPCIS">Figure 1-2</a> shows the structure of advanced
|
|
program-to-program communications (APPC) on the sergver and its relationship to
|
|
the International Standards Organization (ISO) protocol model. Note that only
|
|
the application layer above the APPC protocol code is available for definition.
|
|
The APPC functional equivalents of the ISO presentation, session, networking,
|
|
transport, data link, and physical layers are performed by the i5/OS operating
|
|
system or Licensed Internal Code, and you cannot replace or change them.
|
|
Contrast this with <a href="#FIGUDISO">Figure 1-3</a> which shows how much more
|
|
of the protocol is defined by the user-defined communications application than
|
|
by the APPC application.</p>
|
|
|
|
<p><strong><a name="FIGAPPCIS">Figure 1-2. iSeries APPC versus ISO
|
|
Model</a></strong></p>
|
|
|
|
<p><img src="RBAFX605.gif" alt="iSeries APPC versus ISO Model"></p>
|
|
|
|
<p><a href="#FIGUDISO">Figure 1-3</a> shows the structure for user-defined
|
|
communications and its relationship to the International Standards Organization
|
|
(ISO) protocol model. Note that the available iSeries data links and physical
|
|
layers limit user-defined communications to run over LAN (token-ring, Ethernet,
|
|
wireless, or FDDI), or X.25 links, but the portion of the protocol above the
|
|
data link layer is completely open to a user-defined communications
|
|
application. In addition, these same X.25 and LAN links may be shared between
|
|
the application program and other iSeries communications protocols that support
|
|
X.25 and LAN lines. Examples include Systems Network Architecture (SNA),
|
|
asynchronous communications, Transmission Control Protocol/Internet Protocol
|
|
(TCP/IP), and Open Systems Interconnection (OSI).</p>
|
|
|
|
<p><strong><a name="FIGUDISO">Figure 1-3. iSeries User-Defined versus ISO
|
|
Model</a></strong></p>
|
|
|
|
<p><img src="RBAFX606.gif" alt="iSeries User-defined versus ISO Model"></p>
|
|
|
|
<p>You can write protocols that run over local area networks or X.25 networks
|
|
completely in high-level languages such as C, COBOL, or RPG. You can also write
|
|
protocols currently running on other systems to run on the iSeries. For
|
|
example, you can write both non-SNA LAN or X.25 packet layer protocols on the
|
|
iSeries.</p>
|
|
|
|
<p>Configuration instructions also need to be supplied with the application
|
|
program. User-defined communications support simply opens a pathway to the
|
|
system data links. It is up to you as a protocol developer to supply any
|
|
configuration instructions that are in addition to the data link or physical
|
|
layer definition. Data link and physical layer definitions are defined when you
|
|
use the following commands:</p>
|
|
|
|
<ul>
|
|
<li>Create Line Description (DDI) (CRTLINDDI)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Create Line Description (Ethernet) (CRTLINETH)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Create Line Description (Token Ring) (CRTLINTRN)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Create Line Description (Wireless) (CRTLINWLS)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Create Line Description (X.25) (CRTLINX25)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Create Network Interface Description (ISDN) (CRTNWIISDN)</li>
|
|
</ul>
|
|
|
|
<p><a href="#TBLOBJTAB">Figure 1-4</a> outlines the difference between standard
|
|
iSeries communications configuration, such as the iSeries APPC protocol, and
|
|
user-defined communications configuration.</p>
|
|
|
|
<p><strong><a name="TBLOBJTAB">Figure 1-4. Comparison between User-Defined
|
|
Communications and APPC Communications</a></strong></p>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<th valign="top">Object</th>
|
|
<th valign="top">APPC Communications</th>
|
|
<th valign="top">User-Defined Communications</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" width="20%">Network<br>
|
|
Interface<br>
|
|
Description</td>
|
|
<td align="left" valign="top" width="40%">ISDN basic rate interface (BRI).
|
|
Describes the physical attachment to an ISDN BRI. Only used for ISDN. X.25 or
|
|
IDLC protocols supported.</td>
|
|
<td align="left" valign="top" width="40%">Same as APPC. Only X.25
|
|
supported.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Line Description</td>
|
|
<td align="left" valign="top">SDLC, LAN, IDLC, X.25 lines supported. Contains
|
|
local port information for iSeries communication IOP (hardware address, maximum
|
|
frame size, exchange identifier (XID), local recovery information, ...).</td>
|
|
<td align="left" valign="top">LAN, X.25 lines supported. Same as APPC except
|
|
some of the information does not apply to user-defined communications.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Controller Description</td>
|
|
<td align="left" valign="top">APPC, host controllers supported. Describes
|
|
remote system, and parameters must match the remote hardware (hardware address,
|
|
XID, ...).</td>
|
|
<td align="left" valign="top">Network controller supported. Pathway into
|
|
network. Only one specific parameter--X.25 time-out value.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Device Description</td>
|
|
<td align="left" valign="top">APPC device supported. Describes remote logical
|
|
unit (LU), and parameters must match partner LU (remote location name, local
|
|
location name, ...).</td>
|
|
<td align="left" valign="top">Network device supported. Only describes the
|
|
communications method or type(for example, TCP/IP, OSI, or user-defined
|
|
communications).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Mode Description and Class-of-Service (COS)</td>
|
|
<td align="left" valign="top">Required.</td>
|
|
<td align="left" valign="top">Not available.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>Although an APPC network requires one APPC controller description to
|
|
describe each remote system in the network, user-defined communications only
|
|
requires one network controller for communications with an entire network of
|
|
remote systems. Thus, LAN and X.25 lines can be shared between user-defined
|
|
communications support and any other protocols that support those same line
|
|
types. For example, APPC may run over a token-ring line and use the X'04'
|
|
Service Access Point (SAP). TCP/IP might run at the same time using the X'AA'
|
|
SAP. You might write an application program to use the X'22' SAP, and run at
|
|
the same time as the first two. All three protocols can be active at the same
|
|
time across the same physical media.</p>
|
|
|
|
<p><strong>Note:</strong> System-specific configuration information must be
|
|
part of the application program and is not supplied by IBM<SUP>(R)</SUP>.</p>
|
|
|
|
<br>
|
|
<h2><a name="Header_8">Local Area Network (LAN) Considerations</a></h2>
|
|
|
|
<p>User-defined communications supports these LAN types:</p>
|
|
|
|
<ul>
|
|
<li>Token ring (IEEE 802.5)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Ethernet (IEEE 802.3)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Ethernet Version 2<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Wireless<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>FDDI</li>
|
|
</ul>
|
|
|
|
<p>For token ring (802.5), Ethernet (802.3), and FDDI, user-defined
|
|
communications uses the IEEE 802.2 logical link control (LLC) layer, which
|
|
provides type 1 connectionless service. Connectionless service is also known as
|
|
unacknowledged service. The LLC layer provides for type 2 connection service as
|
|
well. For Ethernet Version 2, no 802.2 layer is available.</p>
|
|
|
|
<p>The wireless LAN type supports the characteristics of both Ethernet (802.3)
|
|
and Ethernet Version 2.</p>
|
|
|
|
<p>Your application program has access to type 1 unnumbered information (UI)
|
|
frames. This connectionless service is commonly referred to as <em>
|
|
datagram</em> support where protocol data units are exchanged between end
|
|
points without establishing a data link connection first.</p>
|
|
|
|
<p>The type 1 operations, test and exchange identifier (XID) frames, are not
|
|
supported in user-defined communications. Any XID or test frames that the
|
|
physical layer of the iSeries receives are processed by the input/output
|
|
processor (IOP) and never reach your application program.</p>
|
|
|
|
<p>LAN frames are routed by filtering incoming data using the inbound routing
|
|
data defined by your application program. The filters are hierarchical and are
|
|
set up by your application program before communications is started.</p>
|
|
|
|
<p>The following list shows the possible settings for LAN inbound routing data
|
|
(filters) from least selective to most selective.</p>
|
|
|
|
<ul>
|
|
<li>Destination Service Access Point (DSAP)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>DSAP, Source Service Access Point (SSAP), and optional Ethernet Version 2
|
|
frame type<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>DSAP, SSAP, optional Ethernet Version 2 frame type, and adapter
|
|
address</li>
|
|
</ul>
|
|
|
|
<p>Because user-defined communications does not allow applications to define
|
|
the data link and physical layers, the entire token-ring or Ethernet frame is
|
|
not available to your applications. The following fields are the parts of the
|
|
LAN frame that are available to the user-defined communications support:</p>
|
|
|
|
<ul>
|
|
<li>DSAP<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>SSAP<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Destination address (DA)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Routing information (RI)<br>
|
|
This field is available only when using token ring.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Priority control<br>
|
|
This field is available only when using token ring.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Access control<br>
|
|
This field is available only when using token ring.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Data</li>
|
|
</ul>
|
|
|
|
<p>For more information on local area networks, see the <a href=
|
|
"../books/sc415404.pdf" target="_blank">LAN, Frame-Relay and ATM
|
|
Support</a><img src="wbpdf.gif" alt="Link to PDF"> book.</p>
|
|
|
|
<br>
|
|
<h2><a name="Header_9">X.25 Considerations</a></h2>
|
|
|
|
<p>X.25 user-defined communications support includes access to both permanent
|
|
virtual circuits (PVCs) and switched virtual circuits (SVCs).</p>
|
|
|
|
<p>Over X.25 networks, including those using ISDN, your application program can
|
|
initiate and accept X.25 calls, send and receive data, reset, and clear
|
|
connections.</p>
|
|
|
|
<p>X.25 packets are routed by filtering the incoming call request using the
|
|
inbound routing data that is defined by your application program. The filters
|
|
are hierarchical and are set up by the application program before
|
|
communications is started.</p>
|
|
|
|
<p>The following list shows the possible settings for X.25 inbound routing data
|
|
(filters) from least selective to most selective.</p>
|
|
|
|
<ul>
|
|
<li>Protocol identifier (PID)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>PID, and calling data terminal equipment (DTE) address</li>
|
|
</ul>
|
|
|
|
<p>When X.25 networks are using ISDN, notification of incoming calls may be
|
|
received on the D-channel. You can decide whether these calls are accepted.</p>
|
|
|
|
<p>For more information on X.25 networks, see the <a href=
|
|
"../books/sc415405.pdf" target="_blank">X.25 Network Support</a><img src=
|
|
"wbpdf.gif" alt="Link to PDF"> book.</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>
|
|
|