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

2342 lines
93 KiB
HTML
Raw Permalink Blame History

<!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>Programming Design Considerations for Communications APIs</title>
<!-- Begin Header Records ========================================= -->
<!-- Print SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- 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 -->
<!-- File Edited November 2001 -->
<!-- Graphics included: RBAFX607 through 625 -->
<!-- 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>Programming Design Considerations for Communications APIs</h2>
<p>This document outlines concepts related to user-defined communications and
how they might relate to the design of a user-defined communications
application. Topics covered are:</p>
<ul>
<li>Jobs</li>
<li>Application program feedback</li>
<li>Programming languages</li>
<li>Connection identifiers</li>
<li>Token-ring, Ethernet, and wireless networks</li>
<li>X.25 networks</li>
<li>Queues</li>
<li>User spaces</li>
</ul>
<h3>Jobs</h3>
<p>A fundamental concept in user-defined communications is the job. The concept
of the job is important because the user-defined communications support
performs services for the job requesting the communications support through one
of the user-defined communications APIs. Information used by the user-defined
communications support is kept along with other information about the job. You
can display this information by using the Work with Job (WRKJOB) command and
selecting the Work with communications status option. The user-defined
communications information for the job, such as the communications handle name,
last operation, and input and output counts are shown.</p>
<p>A user-defined communications application program (hereafter referred to as
an application or application program), always runs within a job. This job may
be run interactively or in batch and always represents a separate application
to the user-defined communications support. This means that the same protocol
can be actively running in more than one job on the system. Also, more than one
job can have links that share the same line as other jobs running application
programs.</p>
<p>Each link that is enabled by an application program logically consists of
the line, network controller, and network device description objects (plus the
network interface description object for ISDN links). Many applications can
share the same line and controller description, provided the applications are
running in different jobs, but each application uses a different device
description. Up to 256 device descriptions can be attached to a controller
description. This means that there can be a maximum of 256 jobs running
application programs that share the same line at one time. When an application
program has finished using a link and disabling it, the network device
description used by the application becomes available to another
application.</p>
<p>For end-to-end communication to begin, the application programs on each
system must be started. There is no function equivalent to the intersystem
communications function (ICF) program start request. Your application program
is responsible for providing this support, if needed. To provide this support,
your application can have a batch job servicing remote requests to start the
user-defined communications application program. This job can be created to run
in any subsystem.</p>
<p>For more information on jobs and subsystems, see the <a href="../rzaks/rzaks1.htm">Work Management</a> topic.</p>
<p>You can design your application programs so that the entire protocol resides
within one job or separate jobs where each job represents a portion of the
protocol.</p>
<p>There is a one-to-one correspondence between a job and the user-defined
communications support for that job. The user-defined communications support
for one job does not communicate with the user-defined communications support
for another job. If two applications wish to communicate between themselves, a
method such as a shared queue can be used. Also, the queue can be shared
between the two (or more) jobs and the user-defined communications support for
those jobs.</p>
<p><a href="#FIGAPIOVER">Figure 1-1</a> shows how user-defined communications
relate to the i5/OS<SUP>(R)</SUP> job structure and the data queue or user queue that
provides the ability to communicate between your application and the
user-defined communications support.</p>
<p>In this figure, one interactive job is running over an X.25 line (X25USA) to
a system in Rochester, Minnesota, using the user-defined communications
support. The link was enabled with communications handle name ROCHESTER.</p>
<p>The user space application programming interfaces (APIs) that the
application program is using are shown, along with the programming interfaces
for data and user queues and the user-defined communications support APIs.</p>
<p><strong><a name="FIGAPIOVER">Figure 1-1. Overview of API
Relationships</a></strong></p>
<p><img src="RBAFX607.gif" alt="Overview of API Relationships"></p>
<p><a href="#FIGJOBREL">Figure 1-2</a> shows two jobs, A and B. Each job is
using the user-defined communications support to communicate with the networks
attached to the iSeries<SUP>(TM)</SUP> server by the line description. The figure shows the
relationship between the different APIs and the job which is running the
application program.</p>
<p>The lines between the jobs indicate that callable APIs that are used to
communicate between the application program and the system services shown.</p>
<p><strong><a name="FIGJOBREL">Figure 1-2. Application Programming Interface to
Job Structure</a></strong></p>
<p><img src="RBAFX608.gif" alt="Application Programming Interface to Job Structure"></p>
<p>The following list pertains to <a href="#FIGJOBREL">Figure 1-2</a>.</p>
<ul>
<li>The applications use the data queue APIs, user space APIs, and user-defined
communications APIs.<br>
<br>
</li>
<li>An application can have more than one link enabled, and can use a separate
queue for each link, or the same queue for some or all the links that it has
enabled.<br>
<br>
</li>
<li>The two jobs can communicate with each other using a common queue. This
queue can be the same queue that is used for user-defined communications
support or a different one.<br>
<br>
</li>
<li>Both jobs (or any other job on the system) that has the proper authority to
the user spaces, can access the user spaces.<br>
<br>
</li>
<li>The user-defined communications support uses the data in the output user
spaces that are created when the link is created. The application making the
call to the Send Data (qolsend) API can fill the output buffer and descriptor,
or another application can do this.<br>
<br>
</li>
<li>The user-defined communications support sends data to the application
through the input buffer and input descriptor that is created when the link on
which the data is arriving was created. Either the application making the call
to the Receive Data (QOLRECV) API retrieves the data from the input buffer and
descriptor, or another application with access to the user spaces does
this.<br>
<br>
</li>
<li>The application supplies any communications handle (link name) to the link
as long as this name is unique among all the other links that the job has
enabled.<br>
<br>
</li>
<li>An application can enable as many links as there are line descriptions that
are supported (X.25, token-ring, Ethernet, wireless, and FDDI) and that are
able to be varied on.<br>
<br>
</li>
<li>An application is able to run over X.25 and LAN links concurrently.</li>
</ul>
<br>
<h3>Application Program Feedback</h3>
<p>The user-defined communications support uses return and reason codes to
indicate the success or failure of an operation, and provide suggested recovery
information. In severe error conditions an escape message is signaled to the
application program. If a severe error occurs, user-defined communications is
no longer available to the application.</p>
<p>When the qolsend and QOLRECV APIs return to the application and you are
running to an X.25 network, the diagnostic field is filled in. The reason code
indicates whether or not the application program should look at the data
returned in the diagnostic field. The diagnostic field contains additional
information on the error or condition that is reported.</p>
<br>
<h3><a name="HDRTWOSTEP">Synchronous and Asynchronous Operations</a></h3>
<p>Most operations that an application program requests on the call to the
qolsend API are synchronous operations. Synchronous operations involve one
step, which is to call the qolsend API, passing the appropriate information.
Synchronous operations complete when the qolsend API returns to the application
program. The success or failure of the operation is reported in the return and
reason codes by the qolsend API.</p>
<p>Asynchronous operations do not complete when the qolsend API returns to the
application. There are two steps for every asynchronous operation:</p>
<ol>
<li>Call the qolsend API to initiate or request the operation.<br>
<br>
</li>
<li>Call the QOLRECV API to receive the results of the completed
operation.</li>
</ol>
<p>When the qolsend API returns to the application program, the request for the
operation is successfully submitted. After the requested operation is complete,
the user-defined communications support sends an incoming data entry (if
necessary) to the queue to instruct the application program to call the QOLRECV
API to receive the data. When this call to the QOLRECV API returns, the return
and reason codes in the parameter list contain the success or failure of the
operation. If the operation was unsuccessful due to an application template
error in the user space used for output, the request data given to qolsend
using the output buffer and descriptor is copied into the input buffer and
descriptor. The offset to the template error detected is returned in the
parameter list of the QOLRECV API. Asynchronous operations are only used for
open connection requests, close connection requests, and resets.</p>
<p>For either type of operation, the application program is allowed to use the
output user spaces again as soon as the call to the qolsend API returns.</p>
<br>
<h3><a name="HDRLANGUAG">Programming Languages</a></h3>
<p>Any program written in an i5/OS-supported language can call
user-defined communications support. One consideration for choosing one
language over another, is that the programming language must have the ability
to set a byte field to any hexadecimal value. This does not restrict
programming in the different languages, but it does make some languages more
appealing than others.</p>
<br>
<h3>Starting and Ending Communications</h3>
<p>Relatively little configuration is required by user-defined communications
support to begin communications to the network. For information on
configuration, see <a href="comm3.htm">Configuration and Queue Entries</a>.</p>
<p>To start communications with a network, your user-defined communications
application program enables the link to the network by calling the Enable Link
(QOLELINK) API. Once the link is enabled, the application program can call any
of the user-defined communications support APIs, and request any of the
operations supported for the link. When the application program completes
communications with the network, it disables the link by calling the Disable
Link (QOLDLINK) API.</p>
<p><strong>Note:</strong> Enabling the link does not result in any
communications activity on the network. Disabling a link may cause
communications activity for X.25 links if connections are active when the link
is disabled.</p>
<br>
<h3><a name="HDRUCEPCON">Using Connection Identifiers</a></h3>
<p>Connection identifiers are used for connection-oriented support over X.25
networks. The connectionless connection identifiers (UCEP=1, PCEP=1) are used
for local area networks. The following examples (<a href="#FIGMPGA">Figure
1-3</a> through <a href="#FIGCMPGA">Figure 1-14</a>) illustrate how to use
connection identifiers (UCEP and PCEP). They show how the two step operations,
open connection request, and close connection request relate to the UCEP and
PCEP identifiers. Note the outstanding two-step operations. This is important
so that the application can correctly interpret the PCEP and reuse UCEPs.</p>
<p>The connections in each figure refer to SVC connections, and the examples
use the Receive Data Queue (QRCVDTAQ) API. The same principles apply when using
PVC connections and user queues.</p>
<p><strong><a name="FIGMPGA">Figure 1-3. Example 1: Normal Connection
Establishment</a></strong></p>
<p><img src="RBAFX609.gif" alt="Normal Connection Establishment"></p>
<ol>
<li>The application wants to open a connection, so it calls the qolsend API
passing it the UCEP it wants to use for the connection. The application keeps
track of the UCEP, PCEP pair. At this point, the UCEP=7, and the PCEP is
undefined.<br>
<br>
</li>
<li>The user-defined communications support receives the request, stores the
UCEP for the connection, and uses the next available PCEP, which is 1, and
returns to the application, acknowledging the receipt of the request.
<p>The user-defined communications support validates the request and issues the
X.25 call request.</p>
</li>
<li>The application records that the PCEP for UCEP=7 is 1. The UCEP=7, PCEP=1
connection is not yet active. Next, the application calls the Receive Entry
From Data Queue (QRCVDTAQ) API, to wait for the incoming data entry. The
application is expecting the open connection response.<br>
<br>
</li>
<li>The X.25 call accept is received for PCEP=1. To inform the application of
the incoming data, an incoming data entry is sent to the data queue.<br>
<br>
</li>
<li>The application's call to the QRCVDTAQ API returns with the incoming data
entry. The application then issues a call to the QOLRECV API.<br>
<br>
</li>
<li>The user-defined communications support fills in the input buffer and
descriptor with data for the open connection response operation, and determines
the UCEP associated with the data by examining the PCEP associated with the
X.25 call accept. Because the call accept was received for PCEP=1, the
UCEP=7.<br>
<br>
</li>
<li>The application's call to the QOLRECV API returns with successful return
and reason codes for the open connection response operation. This operation was
reported for UCEP 7; the UCEP=7, PCEP=1 connection is now active.</li>
</ol>
<p><strong><a name="FIGMPGB">Figure 1-4. Example 2: Connection Request Cleared
by Network/Remote System</a></strong></p>
<p><img src="RBAFX610.gif" alt="Connection Request Cleared by Network/Remote System"></p>
<ol>
<li>The application wishes to open a connection, so it calls the qolsend API,
passing it the UCEP it wants to use for the new connection. The application
keeps track of the UCEP, PCEP pair. At this point, the UCEP=7, and the PCEP is
undefined.<br>
<br>
</li>
<li>The user-defined communications support receives the request, stores the
UCEP for the connection, and uses the next available PCEP, which is 1, and
returns to the application, acknowledging the receipt of the request.
<p>The user-defined communications support validates the request and issues the
X.25 call request.</p>
</li>
<li>The application records that the PCEP for UCEP=7 is 1, and the UCEP=7,
PCEP=1 connection is not yet active. Next, the application calls the QRCVDTAQ
API to wait for the incoming data entry. The application is expecting the
open-connection response.<br>
<br>
</li>
<li>A clear is received for PCEP=1. To inform the application of the incoming
data, an incoming data entry is sent to the data queue.<br>
<br>
</li>
<li>The application's call to the QRCVDTAQ API returns with the incoming data
entry. The application then issues a call to the QOLRECV API.<br>
<br>
</li>
<li>The user-defined communications support fills in the input buffer and
descriptor with data for the open connection response operation, and determines
the UCEP for the data by using the PCEP for which the X.25 call accept was
received. Because the call was cleared for PCEP=1, the UCEP=7. The PCEP=1 is no
longer active, and may be reused by the user-defined communications
support.<br>
<br>
</li>
<li>The application's call to the QOLRECV API returns with unsuccessful return
and reason codes for the open connection response operation. Thus for the
PCEP=1, the UCEP=7. The PCEP=1 is no longer active, and the operation is for
UCEP=7. Because the connection is not open, the user-defined communications
support's PCEP=1 no longer implies UCEP=7, and the application's UCEP=7 may be
reused.</li>
</ol>
<p><strong><a name="FIGMPGC">Figure 1-5. Example 3: Request to Clear Connection
with Outstanding Call (Unsuccessful)</a></strong></p>
<p><img src="RBAFX611.gif" alt="Request to Clear Connection with Outstanding Call (Unsuccessful)"></p>
<ol>
<li>The application wishes to open a connection, so it calls the qolsend API
passing it the UCEP for the new connection. The application keeps track of the
UCEP, PCEP pair. At this point, the UCEP=7, and the PCEP is undefined.<br>
<br>
</li>
<li>The user-defined communications support receives the request, stores the
UCEP for the connection, and uses the next available PCEP, which is 1, and
returns to the application, acknowledging the receipt of the request.
<p>The user-defined communications support validates the request and issues the
X.25 call request.</p>
</li>
<li>The application records that the PCEP for UCEP=7 is 1, and the UCEP=7,
PCEP=1 connection is not yet active. Next, the application calls the QRCVDTAQ
API to wait for the incoming data entry. The application is expecting the open
connection response.<br>
<br>
</li>
<li>QRCVDTAQ returns to the application (the dequeue time-out value has
elapsed), and the application no longer wants the UCEP=7 connection. It calls
the qolsend API passing the PCEP=1 to identify the connection to be closed.
Then the application calls the QRCVDTAQ API.<br>
<br>
</li>
<li>The user-defined communications support receives the close connection
request, and returns to the application, acknowledging the receipt of the
request.
<p>The user-defined communications support validates the request and finds an
error.</p>
</li>
<li>The user space error is found. A copy of the user space, which contained an
error, is passed back to the application. To inform the application of the
unsuccessful close connection request, an incoming data entry is sent to the
data queue.<br>
<br>
</li>
<li>The application's call to the QRCVDTAQ API returns with the incoming data
entry. The application then issues a call to the QOLRECV API.<br>
<br>
</li>
<li>The user-defined communications support fills in the input buffer and
descriptor with data for the unsuccessful close connection request operation,
and determines the UCEP associated with the data by examining the PCEP
associated with the close connection. Because the close connection request was
for PCEP=1, the UCEP=7.<br>
<br>
</li>
<li>The application's call to the QOLRECV API returns with unsuccessful return
and reason codes for the close connection response operation. This operation is
for UCEP=7. The connection UCEP=7, PCEP=1 is still in use by both the
application and the user-defined communications support. The application can
either correct the error and reissue the operation, or wait for the call to be
accepted or rejected.</li>
</ol>
<p><strong><a name="FIGMPGD">Figure 1-6. Unsuccessful Attempt to Clear
Outstanding (Successful) Call</a></strong></p>
<p><img src="RBAFX612.gif" alt="Unsuccessful Attempt to Clear Outstanding (Successful) Call"></p>
<ol>
<li>The application wishes to open a connection, so it calls the qolsend API,
passing the UCEP for the new connection. The application keeps track of the
UCEP, PCEP pair. At this point, the UCEP=7, and the PCEP is undefined.<br>
<br>
</li>
<li>The user-defined communications support receives the request, stores the
UCEP for the connection, and uses the next available PCEP, which is 1, and
returns to the application, acknowledging the receipt of the request.
<p>The user-defined communications support validates the request and issues the
X.25 call request.</p>
</li>
<li>The application records that the PCEP for UCEP=7 is 1, and the UCEP=7,
PCEP=1 connection is not yet active. Next, the application calls the QRCVDTAQ
API to wait for the incoming data entry. The application is expecting the open
connection response.<br>
<br>
</li>
<li>QRCVDTAQ returns to the application (the dequeue time-out value has
elapsed), and the application no longer wants the UCEP=7 connection. It calls
the qolsend API passing the PCEP=1 to identify the connection to be closed.
Then the application calls the QRCVDTAQ API.<br>
<br>
</li>
<li>The X.25 call accept is received for PCEP=1. To inform the application of
the incoming data, an incoming data entry is sent to the data queue.<br>
<br>
</li>
<li>The user-defined communications support receives the close connection
request, and returns to the application, acknowledging the receipt of the
request.<br>
<br>
</li>
<li>The application's call to the QRCVDTAQ API returns with the incoming data
entry. The application then issues a call to the QOLRECV API.<br>
<br>
</li>
<li>The user-defined communications support fills in the input buffer and
descriptor with data for the open connection response, and determines the UCEP
associated with the data by examining the PCEP for the X.25 call accept.
Because the call accept was received for PCEP=1, the UCEP=7.<br>
<br>
</li>
<li>The application's call to the QOLRECV API returns with successful return
and reason codes for the open connection request operation. This operation is
reported for UCEP=7; the UCEP=7, PCEP=1 connection is now active with an
outstanding close connection request. The application calls the QRCVDTAQ
API.<br>
<br>
</li>
<li>While processing the close connection request, the user-defined
communications support detects an error in the user space. The user space that
is in error is copied into the input buffer and descriptor, so the application
is aware of the data in error. To inform the application of the unsuccessful
close connection request, an incoming data entry is sent to the data queue.<br>
<br>
</li>
<li>The application's call to the QRCVDTAQ API returns with the incoming data
entry. The application then issues a call to the QOLRECV API.<br>
<br>
</li>
<li>The user-defined communications support fills the input buffer and
descriptor with data for the unsuccessful close connection request operation.
By using the PCEP that was requested for the close connection, the support
determines the UCEP with which the data is associated. Because the close
connection request was for PCEP=1, the UCEP is 7. The PCEP=1 is still
active.<br>
<br>
</li>
<li>The application's call to the QOLRECV API returns with unsuccessful return
and reason codes for the close connection response operation. This operation is
for UCEP 7. The connection UCEP=7, PCEP=1 is still in use by both the
application and the user-defined communications support. The application can
either correct the error and reissue the operation, or wait for the call to be
accepted or rejected.</li>
</ol>
<p><strong><a name="FIGMPGE">Figure 1-7. Example 5: Successful Attempt to Clear
Outstanding (Successful) Call</a></strong></p>
<p><img src="RBAFX613.gif" alt="Successful Attempt to Clear Outstanding (Successful) Call"></p>
<ol>
<li>The application wishes to open a connection so it calls the qolsend API,
passing it the UCEP for the new connection. The application keeps track of the
UCEP, PCEP pair. At this point, the UCEP=7, and the PCEP is undefined.<br>
<br>
</li>
<li>The user-defined communications support receives the request, stores the
UCEP for the connection, and uses the next available PCEP, which is 1, and
returns to the application, acknowledging the receipt of the request.
<p>The user-defined communications support validates the request and issues the
X.25 call request.</p>
</li>
<li>The application records that the PCEP for UCEP=7 is 1, and the UCEP=7,
PCEP=1 connection is not yet active. Next, the application calls the QRCVDTAQ
API to wait for the incoming data entry. The application is expecting the open
connection response.<br>
<br>
</li>
<li>QRCVDTAQ returns to the application (the dequeue time-out value has
elapsed), and the application no longer wants the UCEP=7 connection. It calls
the qolsend API passing the PCEP=1 to identify the connection to be closed. The
application calls the QRCVDTAQ API.<br>
<br>
</li>
<li>The X.25 call-accept is received for PCEP=1. To inform the application of
the incoming data, an incoming data entry is sent to the data queue.<br>
<br>
</li>
<li>The user-defined communications support receives the close connection
request, and returns to the application, acknowledging the receipt of the
request. The application calls QRCVDTAQ API.<br>
<br>
</li>
<li>The application's call to the QRCVDTAQ API returns with the incoming data
entry. The application then issues a call to QOLRECV.<br>
<br>
</li>
<li>The user-defined communications support validates the close connection
request, and issues an X.25 clear request.<br>
<br>
</li>
<li>The user-defined communications support fills in the input buffer and
descriptor with data for the open connection response, and determines the UCEP
that the data is for by using the PCEP for the X.25 call accept. Since the call
accept was received for PCEP=1, the UCEP is 7.<br>
<br>
</li>
<li>The application's call to QOLRECV returns with successful return and reason
codes for the open connection request operation. This operation is reported for
UCEP=7; the UCEP=7, PCEP=1 connection is now active with an outstanding close
connection request.<br>
<br>
</li>
<li>The clear confirmation is received for PCEP=1. To inform the application of
the successful close connection request, an incoming data entry is sent to the
data queue.<br>
<br>
</li>
<li>The application's call to the QRCVDTAQ API returns indicating there is data
to receive.<br>
<br>
</li>
<li>The user-defined communications support fills the input buffer and
descriptor with data for the successful close connection request operation, and
determines the UCEP associated with the data by examining the PCEP that was
requested for the close connection. Because the close connection request was
for PCEP=1, the UCEP=7. The PCEP=1 is no longer active.<br>
<br>
</li>
<li>The application's call to the QOLRECV API returns with successful return
and reason codes for the close connection response operation. This operation is
for UCEP 7. The UCEP=7, PCEP=1 connection is no longer active.</li>
</ol>
<p><strong><a name="FIGMPGF">Figure 1-8. Example 6: Successful Attempt to Clear
Outstanding (Unsuccessful) Call</a></strong></p>
<p><img src="RBAFX614.gif" alt="Successful Attempt to Clear Outstanding (Unsuccessful) Call"></p>
<ol>
<li>The application wishes to open a connection, so it calls the qolsend API,
passing it the UCEP for the new connection. The application keeps track of the
UCEP, PCEP pair. At this point, the UCEP=7, and the PCEP is undefined.<br>
<br>
</li>
<li>The user-defined communications support receives the request, stores the
UCEP for the connection, and uses the next available PCEP, which is 1, and
returns to the application, acknowledging the receipt of the request.
<p>The user-defined communications support validates the request and issues the
X.25 call request.</p>
</li>
<li>The application records that the PCEP for UCEP=7 is 1, and the UCEP=7,
PCEP=1 connection is not yet active. Next, the application calls the QRCVDTAQ
API to wait for the incoming data entry. The application is expecting the open
connection response.<br>
<br>
</li>
<li>QRCVDTAQ API returns to the application (the dequeue time-out value has
elapsed), and the application no longer wants the UCEP=7 connection. It calls
the qolsend API passing the PCEP=1 to identify the connection to be closed.
Then the application calls the QRCVDTAQ API.<br>
<br>
</li>
<li>The X.25 clear is received for PCEP=1. To inform the application of the
incoming data, an incoming data entry is sent to the data queue.<br>
<br>
</li>
<li>The user-defined communications support receives the close connection
request, and returns to the application, acknowledging the receipt of the
request.<br>
<br>
</li>
<li>The application's call to the QRCVDTAQ API returns with the incoming data
entry. The application then issues a call to the QOLRECV API.<br>
<br>
</li>
<li>The user-defined communications support fills in the input buffer and
descriptor with data for the open connection response, and determines the UCEP
that the data is for by using the PCEP that the X.25 clear is for. Because the
clear was received for PCEP=1, the UCEP is 7.<br>
<br>
</li>
<li>The application's call to the QOLRECV API returns with unsuccessful return
and reason codes for the open connection request operation. This operation is
reported for UCEP=7. Because the close connection request is outstanding, the
UCEP=7, PCEP=1 connection is not fully closed. The application calls the
QRCVDTAQ API.<br>
<br>
</li>
<li>The close connection request is validated, but no clear is sent because the
connection was cleared previously. The close is considered successful, and an
entry is sent to the data queue.<br>
<br>
</li>
<li>The application's call to the QRCVDTAQ API returns with the incoming data
entry. The application then issues a call to the QOLRECV API.<br>
<br>
</li>
<li>The user-defined communications support fills in the input buffer and
descriptor with data for the successful close connection request operation, and
determines the UCEP that the data is for by using the PCEP that the close
connection was requested for. Since the close connection request was for
PCEP=1, and the UCEP is 7. The PCEP=1 is no longer active.<br>
<br>
</li>
<li>The application's call to the QOLRECV API returns with unsuccessful return
and reason codes for the close connection response operation. This operation is
for UCEP 7. The connection UCEP=7, PCEP=1 is no longer active.</li>
</ol>
<p><strong><a name="FIGMPGG">Figure 1-9. Example 7: Unsuccessful Attempt to
Clear Outstanding (Unsuccessful) Call</a></strong></p>
<p><img src="RBAFX615.gif" alt="Unsuccessful Attempt to Clear Outstanding (Unsuccessful) Call"></p>
<ol>
<li>The application wishes to open a connection, so it calls the qolsend API
passing it the UCEP for the new connection. The application keeps track of the
UCEP, PCEP pair. At this point, the UCEP=7, and the PCEP is undefined.<br>
<br>
</li>
<li>The user-defined communications support receives the request, stores the
UCEP for the connection, and uses the next available PCEP (1); and returns to
the application, acknowledging the receipt of the request.
<p>The user-defined communications support validates the request and issues the
X.25 call request.</p>
</li>
<li>The application records that the PCEP for UCEP=7 is 1, and the UCEP=7,
PCEP=1 connection is not yet active. Next, the application calls the QRCVDTAQ
API to wait for the incoming data entry. The application is expecting the open
connection response.<br>
<br>
</li>
<li>The application no longer wants the UCEP=7 connection. It calls the qolsend
API passing the PCEP=1 to identify the connection to be closed. The application
calls the QRCVDTAQ API.<br>
<br>
</li>
<li>The X.25 Clear is received for PCEP=1. To inform the application of the
incoming data, an incoming data entry is sent to the data queue.<br>
<br>
</li>
<li>The user-defined communications support receives the close connection
request, and returns to the application, acknowledging the receipt of the
request.<br>
<br>
</li>
<li>The application's call to the QRCVDTAQ API returns with the incoming data
entry. The application then issues a call to the QOLRECV API.<br>
<br>
</li>
<li>The user-defined communications support fills in the input buffer and
descriptor with data for the open connection response, and determines the UCEP
that the data is for by using the PCEP that the X.25 clear is for. Because the
clear was received for PCEP=1, the UCEP is 7.<br>
<br>
</li>
<li>The application's call to the QOLRECV API returns with unsuccessful return
and reason codes for the open connection request operation. This operation is
reported for UCEP=7. Because the close connection request is outstanding, the
UCEP=7, PCEP=1 connection is not fully closed. The application calls the
QRCVDTAQ API.<br>
<br>
</li>
<li>The close connection request is validated, and an error is found in the
user space. An entry is sent to the data queue.<br>
<br>
</li>
<li>The application's call to the QRCVDTAQ API returns with the incoming data
entry. The application then issues a call to the QOLRECV API.<br>
<br>
</li>
<li>The user-defined communications support fills in the input buffer and
descriptor with data for the unsuccessful close connection request operation,
and determines the UCEP that the data is for by using the PCEP that the close
connection was requested for. Since the close connection request was for
PCEP=1, the UCEP is 7. Because the connection was cleared prior to the close
connection request, the PCEP=1, UCEP=7 connection is considered no longer
active to the user-defined communications support.<br>
<br>
</li>
<li>The application's call to the QOLRECV API returns with unsuccessful return
and reason codes for the close connection response operation. This operation is
for UCEP 7. The connection UCEP=7, PCEP=1 is no longer active.</li>
</ol>
<br>
<h3>Incoming Connections</h3>
<p>The following figures show how the application program handles UCEPs and
PCEPs for incoming connections.</p>
<p><strong><a name="FIGIMPGA">Figure 1-10. Example 1: Normal Connection
Establishment</a></strong></p>
<p><img src="RBAFX616.gif" alt="Normal Connection Establishment"></p>
<ol>
<li>An incoming call request is received by the communications support, which
determines if there is an application that has a filter satisfying this call
request. The communications support uses the next available PCEP, which is 1,
for this new connection. An entry is sent to the data queue.<br>
<br>
</li>
<li>The application has been waiting for its call to the QRCVDTAQ API to
complete. The call completes indicating there is data to be received. The
application calls the QOLRECV API.<br>
<br>
</li>
<li>The input buffer and descriptor are filled with the incoming call request
for PCEP=1, and the QOLRECV API returns.<br>
<br>
</li>
<li>The application looks at the operation, which indicates an incoming call
indication. The PCEP reported by the communications support is 1. The
application chooses to accept this call, and passes the UCEP to be used for
this new connection. The call is made to the qolsend API with PCEP=1,
UCEP=7.<br>
<br>
</li>
<li>The call accept is received and sent for PCEP=1. The qolsend API returns to
the application.<br>
<br>
</li>
<li>The call accept request was successful for UCEP=7, PCEP=1. This connection
is now active.</li>
</ol>
<p><strong><a name="FIGIMPGB">Figure 1-11. Example 2: Send Call Accept Not
Valid</a></strong></p>
<p><img src="RBAFX617.gif" alt="Send Call Accept Not Valid"></p>
<ol>
<li>An incoming call request is received by the communications support, which
determines if there is an application that has a filter satisfying this call
request. The communications support uses the next available PCEP=1 for this new
connection. An entry is sent to the data queue.<br>
<br>
</li>
<li>The application has been waiting for its call to the QRCVDTAQ API to
complete. It does, indicating there is data to be received. The application
calls the QOLRECV API.<br>
<br>
</li>
<li>The input buffer and descriptor are filled with the incoming call request
for PCEP=1, and the QOLRECV API returns.<br>
<br>
</li>
<li>The application looks at the operation which indicates an incoming call
indication. The PCEP reported by the communications support is 1. The
application chooses to accept this call, and passes the UCEP to be used for
this new connection. The call is made to the qolsend API with PCEP=1,
UCEP=7.<br>
<br>
</li>
<li>The call accept is received and an error is found in the user space. The
qolsend API returns to the application, reporting the error and offset. The
incoming call is still outstanding for PCEP=1.
<p>The application checks the return and reason codes and finds that an error
has occurred. The call accept was not sent and the incoming call is still
waiting for a response.</p>
</li>
</ol>
<p><strong><a name="FIGRMPGA">Figure 1-12. Example 3: Send Clear for Incoming
Call</a></strong></p>
<p><img src="RBAFX618.gif" alt="Send Clear for Incoming Call"></p>
<ol>
<li>An incoming call request is received by the communications support, which
determines if there is an application that has a filter satisfying this call
request. The communications support uses the next available PCEP, which is 1,
for this new connection. An entry is sent to the data queue.<br>
<br>
</li>
<li>The application has been waiting for its call to the QRCVDTAQ API to
complete. It does, indicating there is data to be received. The application
calls the QOLRECV API.<br>
<br>
</li>
<li>The input buffer and descriptor are filled for the incoming call request
for PCEP=1, and the QOLRECV API returns.<br>
<br>
</li>
<li>The application looks at the operation which indicates an incoming call
indication. The PCEP reported by the communications support is 1. The
application does not wish to accept the call, so the user space is filled in
for a close connection request and the application calls the qolsend API. The
application calls the QRCVDTAQ API.<br>
<br>
</li>
<li>The close connection request is received and the qolsend API returns to the
application, acknowledging the request.
<p>The close connection request is validated and a clear is sent.</p>
</li>
<li>The clear confirmation is received for PCEP=1 which has no UCEP. An
incoming data entry is sent to the data queue. The application calls the
QRCVDTAQ API.<br>
<br>
</li>
<li>The application's call to the QRCVDTAQ API returns with the incoming data
entry. The application calls the QOLRECV API to receive the data.<br>
<br>
</li>
<li>The input buffer and descriptor are filled in with the clear confirmation
data. Since the connection was never established (and the application never
assigned a UCEP to this connection), the QOLRECV API returns to the application
passing a UCEP=0.<br>
<br>
</li>
<li>The close connection request was successful. PCEP=1 is no longer
active.</li>
</ol>
<p><strong><a name="FIGRMPGB">Figure 1-13. Example 4: Send Clear for Incoming
Call</a></strong></p>
<p><img src="RBAFX619.gif" alt="Send Clear for Incoming Call"></p>
<ol>
<li>An incoming call request is received by the communications support, which
determines there is an application that has a filter satisfying this call
request. The communications support uses the next available PCEP=1 for this new
connection. An entry is sent to the data queue.<br>
<br>
</li>
<li>The application has been waiting for its call to the QRCVDTAQ API to
complete. It completes indicating there is data to be received. The application
calls the QOLRECV API.<br>
<br>
</li>
<li>The input buffer and descriptor are filled for the incoming call request
for PCEP=1, and the QOLRECV API returns.<br>
<br>
</li>
<li>The application looks at the operation which indicates an incoming call
indication. The PCEP reported by the communications support is 1. The
application does not wish to accept the call, so the user space is filled in
for a close connection request and the qolsend API. The application calls the
QRCVDTAQ API.<br>
<br>
</li>
<li>The close connection request is received and the qolsend API returns to the
application, acknowledging the request.<br>
<br>
</li>
<li>The close connection request is validated and an error is found. An entry
is sent to the data queue.<br>
<br>
</li>
<li>The application's call to the QRCVDTAQ API return, with the incoming data
entry. The application calls the QOLRECV API to receive the data.<br>
<br>
</li>
<li>The input buffer and descriptor are filled in with the unsuccessful close
request, and the QOLRECV API returns to the application.<br>
<br>
</li>
<li>The close connection request was not successful. PCEP=1 is still
active.</li>
</ol>
<br>
<h3>Closing Connections</h3>
<p>The following figures show how the application program closes a connection.
The figures apply to both incoming and outgoing connections.</p>
<p>The next two figures illustrate that a close connection request never
completely guarantees the connection will be closed.</p>
<p><strong><a name="FIGCMPGA">Figure 1-14. Example 1: Close Connection Request
Is Not Valid</a></strong></p>
<p><img src="RBAFX620.gif" alt="Close Connection Request Is Not Valid"></p>
<ol>
<li>A connection is established with the PCEP=1, UCEP=7.<br>
<br>
</li>
<li>The application calls the qolsend API to close the connection. The
application calls the QRCVDTAQ API.<br>
<br>
</li>
<li>The user-defined communications support receives the close connection
request and returns to the application, acknowledging the receipt of the
request.<br>
<br>
</li>
<li>The value in the user space is not correct. An entry is sent to the data
queue.<br>
<br>
</li>
<li>The application's call to the QRCVDTAQ API returns with the incoming data
entry. The application calls the QOLRECV API to receive the data.<br>
<br>
</li>
<li>The user-defined communications support fills the input user space with
data for the close connection request and determines the UCEP that the data is
for by examining the PCEP that was requested for the close connection.<br>
<br>
</li>
<li>The application's call to the QOLRECV API returns with unsuccessful return
and reason codes for the close connection response. This operation is for UCEP
7. The connection UCEP=7, PCEP=1 is still active.</li>
</ol>
<p><strong><a name="FIGCMPGB">Figure 1-15. Example 2: Close Connection Request
Is Valid</a></strong></p>
<p><img src="RBAFX621.gif" alt="Close Connection Request Is Valid"></p>
<ol>
<li>A connection is established with the PCEP=1, UCEP=7.<br>
<br>
</li>
<li>The application calls the qolsend API to close the connection. The
application calls the QRCVDTAQ API.<br>
<br>
</li>
<li>The user-defined communications support receives the close connection
request and returns to the application, acknowledging the receipt of the
request.<br>
<br>
</li>
<li>The close connection request is received and the qolsend API returns to the
application, acknowledging the request. The close connection request is
validated and a clear is sent.<br>
<br>
</li>
<li>The clear confirmation is received for PCEP=1, UCEP=7. An incoming data
entry is sent to the data queue.<br>
<br>
</li>
<li>The application's call to the QRCVDTAQ API returns with the incoming data
entry. The application calls the QOLRECV API to receive the data.<br>
<br>
</li>
<li>The user-defined communications support fills the input user space with
data for the close connection confirmation and determines the UCEP that the
data is for by examining the PCEP that was requested for the close
connection.<br>
<br>
</li>
<li>The application's call to the QOLRECV API returns with successful return
and reason codes for the close connection response. This operation is for UCEP
7. The connection UCEP=7, PCEP=1 is no longer active.</li>
</ol>
<hr>
<h2>Programming Considerations for LAN Applications</h2>
<p>User-defined communications over LANs use connectionless (unacknowledged)
service. Unacknowledged Information (UI) frames are the only frames an
application program can generate.</p>
<p>For a description of the frame formats for Ethernet Version 2, IEEE 802.3,
IEEE 802.5, wireless, and FDDI, refer to the <a href="../bookssc415404.pdf"
target="_blank">LAN, Frame-Relay and ATM Support</a><img src="wbpdf.gif" alt=
"Link to PDF"> book. To determine how the format and the user buffer are
specified, see <a href="comm4.htm">User-Defined Communications Support
APIs</a>.</p>
<br>
<h3>Operations</h3>
<p>User-defined communications support defines many different operations. Not
all operations are valid on all data links. The operations which are valid for
LAN links are:</p>
<ul>
<li>X'0000' and X'0001'. These operations together represent the send- and
receive-data operations for any of the LAN frames types.</li>
</ul>
<br>
<h3>Configuration</h3>
<p>The service access point (SAP) that the application program uses to send and
receive data must be configured in the line description. The 04, 06, and AA
SAPs are created if *SYSGEN is specified on the CRTLINTRN, CRTLINETH,
CRTLINWLS, or CRTLINDDI command. The 04 SAP is used by SNA, and the 06 and AA
SAPs are used by TCP/IP. An application can choose to use any SAP (including
SAPs defined by SNA or IEEE). The line description must be manually configured
to include any other SAPs the application uses. The SAPTYPE for each SAP used
must be configured as *NONSNA to be used by user-defined communications.</p>
<p>Although it is possible to use any SAP configurable on the iSeries server, it
is not recommended to use SNA SAPs for user-defined communications, because
this may restrict the use of SNA on your iSeries server. In the same manner,
using the same SAP as other well-known protocols, such as TCP/IP, may restrict
the use of these protocols or the application program on the iSeries server.</p>
<p><strong>Note:</strong> It is not possible to run an SNA application and a
user-defined communications application program over the same SAP concurrently.
It is possible to run a TCP/IP application and a user-defined communications
application over the same SAP concurrently, provided the inbound routing
information is unique among all the non-SNA applications sharing the network
controller.</p>
<br>
<h3>Inbound Routing Information</h3>
<p>For an application program to receive data from a LAN, it must inform the
communications support of how to filter the inbound data and route it to the
application. This is accomplished by a program call to the Set Filter (QOLSETF)
API. The fields in the incoming frame that are used to route the data are DSAP,
SSAP, MAC address, and type.</p>
<p>The inbound routing information acts as a filter to allow the user-defined
application to distinguish its data from the rest of the data on the LAN. The
more selective the inbound routing information is, the less chance there is
that the application will be processing unnecessary input requests. Also, more
selective inbound routing information allows multiple jobs running user-defined
communications applications to share the same SAP.</p>
<p>For example, if an application is using 92 SSAP and 92 DSAP but only talking
to one remote system, it may want to set a more selective filter which would
include DSAP, SSAP, and the MAC address of the remote system. Conversely, if an
application accepts data on the 04 SAP from all systems sending data on any
SAP, then the application would set a filter for DSAP only, indicating that it
will accept all data arriving on the 04 SAP.</p>
<br>
<h3>End-to-End Connectivity</h3>
<p>Because user-defined communications on a LAN is connectionless, it is up to
your application protocol to define a method to reach the remote systems it
communicates with. There are several ways to do this. One way is to have each
system configured in a database file on the iSeries server. Each system could
have a local name that the application program uses to correlate with the MAC
address and routing information. LANs provide a technique to broadcast, which
can be used to retrieve this information as well. An example of this is the
Address Resolution Protocol (ARP) used by TCP/IP, which returns the MAC address
and routing information so that a system without that information can
communicate with a new remote system.</p>
<br>
<h3>Sending and Receiving Data</h3>
<p><strong>Maximum Frame Size</strong></p>
<p>The user-defined communications support creates a data unit size which is
always large enough to contain the maximum frame size supported by any of the
SAPs configured for non-SNA use, (SAPTYPE(*NONSNA)). The data unit size is
returned in the parameter list on the call to the QOLELINK API. For Ethernet
(802.3), token-ring, FDDI, and wireless LANs, the maximum frame size that the
application can specify is the maximum frame size allowed by the SAP that the
frame is sent on. There is no minimum frame size for the Ethernet 802.3,
token-ring, FDDI, or wireless LANs.</p>
<p>Ethernet Version 2 does not define SAPs for the higher-layer protocols.
Therefore, the maximum frame size is not determined by the maximum frame size
for the SAP that the frame is sent on. The maximum frame size for Ethernet
Version 2 is 1502 bytes. The first 2 bytes are for the type field, and the last
1500 bytes are for user data. The minimum amount of data that can be sent is 48
bytes. The first 2 bytes are for the type field, and the next 46 bytes are for
user data. If the line is configured to handle both Ethernet 802.3 and Ethernet
Version 2 data, the larger of the configured value or 1502 bytes is chosen and
reported to the application on the data unit size parameter returned from the
QOLELINK API.</p>
<p>If your application program attempts to send data frames that are larger or
smaller than those that are supported, the output request completes with
nonzero return and reason codes, and an error code is returned to the
application in the diagnostic information field.</p>
<p>Application programs access information that is contained in the line
description through the Query Line Description (QOLQLIND) API. It is best to
call the QOLQLIND API after the link has been successfully enabled because the
information that the QOLQLIND API passes to the application is accurate for as
long as the link is enabled. The application uses the information on the frame
size for the SAP to send the correct amount of data over the SAP.</p>
<br>
<h3>Maximum Amount of Outstanding Data</h3>
<p>Most often, the data arrives at a slightly faster rate than the application
program can receive it. The communications support keeps data intended for an
application so that the application can receive it. However, there is a limit
to the amount of data that can be kept for the application to use later. The
limit helps to avoid one system from overrunning another system's resources.
When this limit is reached, all new incoming data frames for that application
are discarded until the application picks up one third of the data that was
stored for the application. Because the data consists of unacknowledged
information frames, the higher-layer protocol within the application detects
the loss of data, resends the data, or performs other recovery actions.</p>
<p>Each time the data limit is exceeded, the communications support creates an
error log entry and puts a message in the QSYSOPR message queue, indicating
that the unacknowledged service has temporarily stopped receiving incoming
frames.</p>
<br>
<h3><a name="HDRBRIDGE">Ethernet to Token-Ring Conversion and Routing</a></h3>
<p>The IBM<SUP>(R)</SUP> 8209 Ethernet to token-ring bridge provides additional connectivity
options for the iSeries server. See the <cite>IBM 8209 LAN Bridge Customer
Information</cite> book, SA21-9994, for more details.</p>
<br>
<h3><a name="HDRLANPERF">Performance Considerations</a></h3>
<p>The application program enables connectionless traffic to enter the iSeries server
system from the LAN. In the call to the QOLSETF API, the DSAP field indicates
the SAP which will be activated on the iSeries server. By activating traffic
over a SAP, data is taken from the LAN and brought into the iSeries server.
Similarly, deactivating traffic over an SAP causes traffic intended for that
SAP to be left at the IOP level rather than to be processed on the iSeries server
system.</p>
<p>To minimize host processing, the SAP or SAPs that the application uses
should be deactivated as soon as the application no longer wants to receive
traffic for the SAP. If the link is disabled and no other applications are
using the SAP(s), they are deactivated automatically by the user-defined
communications support.</p>
<p>Protocols that use broadcast frames as a discovery technique could flood the
network with messages and affect performance on all the systems attached to the
network.</p>
<hr>
<h2><a name="HDRX25SPEC">Programming Considerations for X.25
Applications</a></h2>
<p>The user-defined communications support interface to an X.25 network is at
the packet level, which is a connection-oriented level. Your application
program is responsible for ensuring reliable end-to-end connectivity. <strong>
End-to-end connectivity</strong> means that the application program can
initiate, receive, and accept X.25 calls and handle network errors reported to
the application, as well as send and receive data.</p>
<p>Your application program has access to packets that flow over switched
virtual circuits (SVCs) and permanent virtual circuits (PVCs). The application
can have SVC and PVC connections active concurrently. You can configure up to
64 virtual circuits on an X.25 line description, depending on the
communications I/O processor used. The <a href="../bookssc415405.pdf"
target="_blank">X.25 Network Support</a><img src="wbpdf.gif" alt="Link to PDF">
book provides more information about configuration limitations.</p>
<p>The Display Connection Status (DSPCNNSTS) command shows the virtual circuits
that are in use by a network device, and the state of each connection. This
command also displays the active inbound routing information that the
application program uses to route calls.</p>
<br>
<h3>X.25 Packet Types Supported</h3>
<p>A <strong>packet</strong> is the basic unit of information transmitted
through an X.25 network. The following table lists the X.25 packet types along
with the type of service provided. Services for Switched Virtual Circuit (SVC)
and Permanent Virtual Circuit (PVC) connections are identified as well as
services that are not accessible (N/A) to an application program.</p>
<table border width="80%">
<tr>
<th valign="top">Packet Type</th>
<th valign="top">Application Input or Access</th>
<th valign="top">SVC</th>
<th valign="top">PVC</th>
<th valign="top">N/A</th>
</tr>
<tr>
<td align="left" valign="top" width="15%">Data</td>
<td align="left" valign="top" width="61%">Q,D bits of the general format
identifier (GFI)
<p><strong>Note:</strong> The modulus used is configured in the line
description. The open connection request allows the user-defined communications
support to set the actual window size used.</p>
</td>
<td align="center" valign="top" width="8%">X</td>
<td align="center" valign="top" width="8%">X</td>
<td align="center" valign="top" width="8%">&nbsp;</td>
</tr>
<tr>
<td align="left" valign="top">Interrupt</td>
<td align="left" valign="top">32 bytes of data
<p><strong>Note:</strong> On the iSeries server, the X.25 packet layer provides
the confirmation of the receipt of this packet. The call to the qolsend API
does not return until the interrupt is confirmed by the remote system.</p>
</td>
<td align="center" valign="top">X</td>
<td align="center" valign="top">X</td>
<td align="center" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="left" valign="top">Reset request</td>
<td align="left" valign="top">Cause and diagnostic codes
<p><strong>Note:</strong> The application program provides the confirmation of
this packet.</p>
</td>
<td align="center" valign="top">X</td>
<td align="center" valign="top">X</td>
<td align="center" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="left" valign="top">Reset indication</td>
<td align="left" valign="top">Cause and diagnostic codes
<p><strong>Note:</strong> The application program provides the confirmation of
this packet.</p>
</td>
<td align="center" valign="top">X</td>
<td align="center" valign="top">X</td>
<td align="center" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="left" valign="top">Reset confirmation</td>
<td align="left" valign="top">
<p><strong>Note:</strong> User-defined communications support detects and
reports reset collisions to the application on the reset confirmation.</p>
</td>
<td align="center" valign="top">X</td>
<td align="center" valign="top">X</td>
<td align="center" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="left" valign="top">Incoming Call</td>
<td align="left" valign="top">Remote DTE, local virtual circuit, packet and
window sizes, up to 109 bytes of additional facilities, up to 128 bytes of
bytes of call user data</td>
<td align="center" valign="top">X</td>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="left" valign="top">Call Request</td>
<td align="left" valign="top">Remote DTE, local virtual circuit, packet and
window sizes, up to 109 bytes of additional facilities, up to 128 bytes of
bytes of call user data</td>
<td align="center" valign="top">X</td>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="left" valign="top">Call Accept</td>
<td align="left" valign="top">Packet and window sizes, up to 109 bytes of
additional facilities</td>
<td align="center" valign="top">X</td>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="left" valign="top">Call Connected</td>
<td align="left" valign="top">Negotiated packet and window sizes,
facilities</td>
<td align="center" valign="top">X</td>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="left" valign="top">Clear request</td>
<td align="left" valign="top">Cause and diagnostic codes, facilities, up to 128
bytes of clear user data</td>
<td align="center" valign="top">X</td>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="left" valign="top">Clear indication</td>
<td align="left" valign="top">Cause and diagnostic codes, facilities, up to 128
bytes of clear user data
<p><strong>Note:</strong> The X.25 packet layer support provides the
confirmation on this request.</p>
</td>
<td align="center" valign="top">X</td>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="left" valign="top">Clear confirmation</td>
<td align="left" valign="top">The X.25 packet layer support provides this
support.</td>
<td align="center" valign="top">X</td>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
</tr>
<tr>
<td align="left" valign="top">Receive Ready (RR)</td>
<td align="left" valign="top">The flow of RR and RNR packets is determined by
the automatic flow control field of Format I, specified in the open connection
request.</td>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">X</td>
</tr>
<tr>
<td align="left" valign="top">Receive Not Ready (RNR)</td>
<td align="left" valign="top">The flow of RR and RNR packets is determined by
the automatic flow control field of Format I, specified in the open connection
request.</td>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">X</td>
</tr>
<tr>
<td align="left" valign="top">Reject (REJ)</td>
<td align="left" valign="top">This packet is not necessarily available on all
networks and is not supported by the iSeries server.</td>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">X</td>
</tr>
<tr>
<td align="left" valign="top">Restart Request, Indication, and
Confirmation</td>
<td align="left" valign="top">These packets affect all virtual circuits on the
line.</td>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">X</td>
</tr>
<tr>
<td align="left" valign="top">Diagnostic</td>
<td align="left" valign="top">This packet is not necessarily available on all
networks and is not supported by the iSeries server.</td>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">X</td>
</tr>
<tr>
<td align="left" valign="top">Registration Request and Confirmation</td>
<td align="left" valign="top">This packet is not necessarily available on all
networks and is not supported by the iSeries server.</td>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">&nbsp;</td>
<td align="center" valign="top">X</td>
</tr>
</table>
<br>
<h3>Operations</h3>
<p>User-defined communications support defines many different operations. The
X'B000' operation either initiates an X.25 SVC call request, or a request to
open a PVC. By using this operation, an application program initiates an open
connection request. The X'B100' operation either initiates an X.25 SVC clear
request (or confirms the connection failure), or requests closing a PVC. By
using this operation, an application program initiates a close connection
request. The application can use the X'BF00' operation to cause the SVC or PVC
connection to be reset.</p>
<p>The open connection request, close connection request, and reset request (or
response) operations are two-step operations. See <a href="#HDRTWOSTEP">
Synchronous and Asynchronous Operations</a> for more information on programming
for two-step operations.</p>
<p>The X'B400' operation initiates an X.25 SVC call accept. This operation is
known as a call accept operation. The X'0000' operation initiates an X.25 Data
packet for a SVC or PVC connection. This operation is called a send data
operation. The call accept and send data operations are one-step operations.
See <a href="#HDRTWOSTEP">Synchronous and Asynchronous Operations</a> for more
information on programming for one step operations.</p>
<p>The application program does not request the other available X.25
operations. These X.25 operations are inbound packets for responses from the
asynchronous operations that are reported to the application in the parameter
list of the QOLRECV API. The X'B201' operation indicates an incoming X.25 SVC
call and is known as the call indication operation. The X'B301' operation
indicates that a temporary (reset) or permanent (clear) connection failure has
occurred. It is known as the connection failure indication operation. Finally,
the X'0000' operation indicates incoming data. It is known as the receive data
operation.</p>
<br>
<h3><a name="HDRCONNECT">Connections</a></h3>
<p>User-defined communications support allows X.25 connections over both
switched and permanent virtual circuits. Your application program can have one
or many connections active at once. They can be either SVC, PVC, or both. The
Display Connection Status (DSPCNNSTS) command shows the state of the
connection, logical channel identifier, virtual circuit type, and other
information about the call. The states of the connection include activate
pending, active, deactivate pending.</p>
<p>When the open connection request or call accept operations are not yet
complete, the connection state is activate pending. Once the open connection
request or call accept operations are complete with return and reason codes of
zero, the connection state is active. When the close connection request is not
yet complete, or if the connection is cleared by the network, but a close
connection request has not been issued by the application program, the
connection state is deactivate pending.</p>
<p><strong>Notes:</strong></p>
<ol>
<li>The connection enters the active state when the call accept packet is sent
on the network, which is independent of the application program receiving the
results of the open connection request. Likewise, a connection can become
completely closed (deactivated, and no longer appears on the DSPCNNSTS screen)
independent of the application program receiving the results of the close
connection request. This closing occurs when the application confirms the
connection failure.<br>
<br>
</li>
<li>A correctly encoded close connection request will always be successful. The
only time a close connection request is not successful is when the application
program has coded the close connection request incorrectly. See <a href= "#HDRUCEPCON">Using Connection Identifiers</a> for more information.</li>
</ol>
<br>
<h3><a name="Header_24">Connection Identifiers</a></h3>
<p>To differentiate between connections, user-defined communications support
and an application program both use connection identifiers from the time the
connection is started to the time the connection has successfully ended.</p>
<p>User-defined communications support assigns an identifier for each
connection. This identifier is reported back to your application program as the
provider connection end point (PCEP). In the same manner, your application
program assigns an identifier for each connection and reports it to the
communications support as the user connection end point (UCEP). This exchange
of identifiers allows both the communications support and the application
program to refer to a connection in a consistent manner. The UCEP and PCEP are
exchanged during the open connection request during the following
operations:</p>
<ul>
<li>A PVC is opened.<br>
<br>
</li>
<li>An outgoing call is requested.<br>
<br>
</li>
<li>The call indication is received and the call accept is accepted.</li>
</ul>
<p>User-defined communications support identifies a connection only in terms of
PCEP and UCEP. For example, the user-defined communications support passes
information to an application program and reports the UCEP to which the
information pertains. In the same manner the application program initiates
requests for a connection identified by the PCEP.</p>
<p>User-defined communications support uses PCEPs over again as they become
free. PCEPs become free when the application program receives notification that
the open connection request never completed successfully, or the close
connection request completed successfully. This means that PCEPs are not used
over again until the application calls the QOLRECV API, which returns either
the open connection request or the close connection request. Until the PCEP is
freed, the connection cannot be reused.</p>
<p>User-defined communications support places no restrictions on the value of
the UCEP, and does not verify its uniqueness. Because user-defined
communications passes all incoming data and connection failure indications to
the application program using the UCEP connection identifier, the application
should ensure uniqueness of each UCEP. See <a href="#HDRUCEPCON">Using
Connection Identifiers</a> for information on how to reuse connection
identifiers.</p>
<br>
<h3>Connection Information</h3>
<p>In order to ensure reliable end-to-end connectivity, an application program
must keep track of the control information for each connection it is
responsible for. Some of this control information is shown in the following
list.</p>
<ul>
<li>State of the connection (activating, active, deactivating, reset)<br>
<br>
</li>
<li>PCEP for this connection<br>
<br>
</li>
<li>SVC or PVC connection indicator<br>
<br>
</li>
<li>Negotiated frame sizes; maximum data unit size<br>
<br>
</li>
<li>Connection is no longer active indicator or state<br>
<br>
</li>
<li>Other application specific information</li>
</ul>
<p>The application program can use the UCEP as an index into the program's data
structures, which keep track of this control information.</p>
<br>
<h3>Switched Virtual Circuit (SVC) Connectivity</h3>
<p><strong>Configuration</strong></p>
<p>All the users of an X.25 line description share the SVCs that are configured
for that line description. These users are SNA, asynchronous X.25, OSI, TCP/IP,
and user-defined communications. You should define the line description with
enough SVCs to accommodate all of the users of the X.25 line.</p>
<p>Any SVCs defined in the X.25 line description that are not in use by any
controllers (including the network controller) are available to an application
program. The available SVCs are distributed as they are requested by the users
of the X.25 line description.</p>
<p>See the <a href="../bookssc415405.pdf" target="_blank">X.25 Network
Support</a><img src="wbpdf.gif" alt="Link to PDF"> book for more information on
configuring X.25 line descriptions.</p>
<p>For user-defined communications, the application uses an SVC when it either
initiates a call, or receives an incoming call. The SVC is no longer in use
when the application successfully initiates a clear request to the SVC. Like
PVCs, SVCs allow only one application program to have an active connection
using the virtual circuit at a time.</p>
<br>
<h3>Inbound Routing Information</h3>
<p>Before an application program can receive and accept an incoming call, it
must first describe to the user-defined communications support the X.25 calls
that should be routed to the application. The application does this by issuing
a program call to the QOLSETF API, specifying the inbound routing information
in the filter.</p>
<p>The inbound routing information that an application program specifies is the
first byte of call user data called the protocol ID, or the protocol ID
combined with the calling DTE address. In addition, the application specifies
whether it will accept calls with fast select and reverse charging indicated.
The application program can either accept or reject any calls of which it
receives indications. The advantage of using filters to allow the system to
reject some calls (based on protocol ID, calling DTE address, fast select, and
reverse charging indicated in the incoming call) is that the application is
relieved of some of the calls it would always reject.</p>
<p>Once the connection is active, data flows end-to-end between systems and
does not need any other technique to route it to the appropriate
application.</p>
<br>
<h3>End-to-End Connectivity</h3>
<p>End-to-end connectivity is achieved when one system initiates a call and
another accepts the call. When this happens, a connection is established, and
the state of the connection is active. It remains active until either one of
the application programs initiates a clear request, or the network (or system)
clears the connection due to an error condition.</p>
<br>
<h3>Permanent Virtual Circuit (PVC) Connectivity</h3>
<p><strong>Configuration</strong></p>
<p>SNA and asynchronous X.25 controllers use PVCs on the X.25 line by
configuring the controller description to logically attach to the PVC. This is
not true for users of the network controller description. When a PVC is in use
by an application program, the system will logically attach the network
controller to the PVC. This means that any PVC defined in the X.25 line
description and not attached to any controller (including the network
controller) is available for use by any application that has a link enabled for
the network to which the line is attached.</p>
<p>Because the attaching of PVCs to applications is programmable, one job can
have an open connection over the PVC, end the connection, and then another job
can open a different connection over the same PVC. Like SVCs, PVCs allow only
one application program at a time to have an active connection using the
virtual circuit.</p>
<br>
<h3>Inbound Routing Information</h3>
<p>By definition, the PVC does not require a call to set up a path from one
system to another system. As its name suggests, this path always exists
(permanent). Because there is no incoming call to route, the application has no
need to set a filter for the inbound routing information. Once the application
has opened the PVC, there is no other information needed for the system to
route packets on the PVC to the application.</p>
<br>
<h3>End-to-End Connectivity</h3>
<p>The application is responsible for opening and closing PVC connections. To
open a PVC, the application uses the open connection request operation, just as
it does to initiate an X.25 SVC call. To close the PVC, the application uses
the close connection request just as it does to clear the SVC call.</p>
<p>Both systems that want to communicate end-to-end must first open the virtual
circuit on the local system. When the PVC is opened on the iSeries server it is
considered active and in use by the application. This is true even if the
corresponding remote system doesn't have the virtual circuit active. On the
iSeries server, an open connection request always completes with return and
reason codes of zero as long as the PVC is defined in the line description and
is not in use by another application. There is no way to detect whether true
end-to-end connectivity exists on the PVC.</p>
<p>If the virtual circuit is not active on both systems, and one system
attempts to communicate with the other, the virtual circuit on the system with
the open PVC connection is reset. An application that supports X.25 resets,
sees the reset arrive as a result of the attempt to send data. In order to
continue, the application responds to the reset. An application that does not
support X.25 resets sees a connection failure. The application closes the PVC
and opens the PVC again in order to continue to use the PVC.</p>
<p>Similarly, when a PVC connection is closed from one system, the other system
sees a reset (if reset is supported by that application) or a connection
failure if reset is not supported. If the application sees a reset, it must
respond to the reset before communications can continue on that connection.</p>
<br>
<h3>Sending and Receiving Data Packets</h3>
<p><strong>Data Sizes</strong></p>
<p>Data units larger and smaller than the negotiated transmit packet size can
be sent by an application program. Each data unit will be segmented into the
appropriate packet sizes by the iSeries server. Contiguous data larger than the
negotiated packet size can also be sent. The data is divided into individual
packets and sent out with the more-data indicator on. The application program
should request that the data unit size be a multiple of the transmit and
receive packet sizes configured in the line description. The application
program sets other important values that pertain to each connection. See <a
href="qolsend.htm#HDRX25OPER">X.25 SVC and PVC Output Operations</a> for
information about these values.</p>
<p>The values your application supplies should be carefully determined and
tailored to the needs of the application. Similarly, your application uses the
values returned from the system to ensure that the application does not exceed
negotiated limitations.</p>
<p>The application uses three values to determine how to fill the user-space
output buffer. These values are:</p>
<ul>
<li>Data unit size<br>
<br>
</li>
<li>Maximum data unit assembly size<br>
<br>
</li>
<li>Negotiated transmit packet size</li>
</ul>
<p>The data unit size is the value that an application specifies when the link
is enabled. The maximum data unit assembly size is the total length of
contiguous input data that is assembled by the iSeries server before passing it
to the application. Contiguous data units have the more-data indicator set on
in each descriptor for all the data units in the sequence except the last data
unit, which has the more-data indicator set off. The application specifies the
maximum data unit assembly size on the open connection request. The maximum
data unit assembly size should always be greater than the data unit size to
make full use of the user spaces. The negotiated transmit packet size is
returned when the open connection request completes. The application uses these
values together to determine how to fill in the user space output buffer.</p>
<blockquote>
<p><strong>Note:</strong> If the maximum data unit assembly size is exceeded,
the data is passed up to the application with the more-data indicator on. If
the connection is abnormally reset or cleared, the application may not receive
the rest of the contiguous data, which was in progress during the connection
failure.</p>
<p>If the two applications remain without exceeding the maximum data unit
assembly size supported on the remote system, the system guarantees that the
application receives the complete, contiguous data packet sequence.</p>
</blockquote>
<p>See <a href="#HDRMXX25">Maximum Amount of Outstanding Data</a> for related
information on incoming data limitations.</p>
<p><strong>Interrupts</strong></p>
<p>The interrupt is a special data packet. The X.25 network imposes the
restriction that a DTE cannot have more than one outstanding interrupt on any
virtual call in each direction. An application program issues an interrupt by
calling the qolsend API. The qolsend API does not return to the application
program until the interrupt confirmation has been received. It is important to
understand the interrupt confirmation procedures of the remote DTE and its
implications to the local system and application.</p>
<p><strong><a name="HDRFLOWCON">Flow Control</a></strong></p>
<p>The iSeries server sends the Receive Ready (RR) and Receive Not Ready (RNR)
packets on behalf of the application program. The distribution of these packets
is based on the automatic flow control field in the open connection request
operation. The automatic flow control (RR/RNR) is sent to prevent one system
from overrunning another system with data.</p>
<p>When the automatic flow control value is exceeded for a connection because a
remote system is sending data at a rate too fast for the local system, an RNR
packet is sent on behalf of the application on that local system. Once the
application on the local system receives the data, an RR is sent to allow more
data to be received by the local system's communications support.</p>
<p>The automatic flow control value should be set high enough so that RR/RNR
processing does not affect performance on the virtual circuit, and low enough
that the application can process the data fast enough. If an application is
coded properly, the RR and RNR processing is not noticed by the application,
just as for other system users of X.25.</p>
<p>To avoid situations where the virtual circuit is not operational because an
RNR was sent, or to avoid excessive amounts of RR and RNR processing, the
application program should always attempt to receive all the data from the
communications support. An application that is not coded correctly can cause
another application to wait indefinitely for an RR to open the virtual circuit
for communications. When the applications are coded correctly, the RR and RNR
packet sequences are not noticed by the applications.</p>
<p><strong><a name="HDRMXX25">Maximum Amount of Outstanding
Data</a></strong></p>
<p>The communications support sets aside a limited amount of data for the
applications it is servicing. For X.25, it is 128K for each connection. If the
128K limitation is met, an error log entry is created and the connection is
cleared (SVCs) or reset (PVCs) by the system. Before this limit is reached, the
iSeries server attempts to slow the incoming data traffic by issuing an RNR on
behalf of the application. An RR is sent after the application has received
one-third of the amount of outstanding data.</p>
<p><strong>Reset Support</strong></p>
<p>When an application program initiates a reset, it is also responsible for
discarding any data that the user-defined communications support has received.
The user-defined communications support only discards data if the connection is
closed.</p>
<br>
<h3><a name="HDRX25CALL">X.25 Call Control</a></h3>
<p>The X.25 support routes X.25 calls arriving to the iSeries server primarily
based on the protocol ID field. This field is the first byte of call-user data
in the X.25 call packet. For more information on the X.25 support, see the <a
href="../bookssc415405.pdf" target="_blank">X.25 Network Support</a><img
src="wbpdf.gif" alt="Link to PDF"> book.</p>
<br>
<h3><a name="HDRX25PERF">Performance Considerations</a></h3>
<p>The X'0000' operation is completely synchronous. This means that control is
not returned to the application until all the data passed in the data units are
sent and confirmed by the DCE. Some implications of this are:</p>
<ul>
<li>If the application sends data on a connection that has data flow turned off
(the remote system sent an RNR to the local iSeries server), a subsequent call
to the qolsend API with operation X'0000' will not return until the remote
system sends the RR to turn flow back on for the connection.<br>
<br>
</li>
<li>When transmitting Interrupt packets, control is not returned to the
application until the interrupt is confirmed by the remote DTE. If the remote
DTE is an iSeries server, the interrupt is confirmed by the iSeries server X.25
packet layer support. If the network is congested, the use of Interrupt packets
may cause a decrease in performance for the application.</li>
</ul>
<p>In these situations, it may be appropriate to have one job for each
connection (each virtual circuit).</p>
<hr>
<h2>Queue Considerations</h2>
<p>An application program uses a data queue or user queue for communications
between the application and the communications support. The application should
create the queue prior to the call to the QOLELINK API. For more information on
creating and using a queue, see the <a href="../rbam6/clpro.htm">CL Programming</a> topic. The
link will never be fully enabled if the queue does not exist. For example, in
<a href="#FIGSCEN1">Figure 1-16</a>, communications is no longer available when
the user-defined communications support detects that the data queue has been
deleted. The same is true for user queues.</p>
<p><strong><a name="FIGSCEN1">Figure 1-16. Using the Data
Queue</a></strong></p>
<p><img src="RBAFX622.gif" alt="Using the Data Queue"></p>
<p>In addition to using a queue for communications between the application and
the user-defined communications support, the application can use the queue to
provide communications with other applications.</p>
<p>If multiple processes are using the same queue, the queue can be manipulated
so that each process receives queue entries based on the unique key for each
application. This allows the jobs to put many kinds of entries on the queue.
For example, one key value is used for communications between the application
and the system, and another key value is used for communications between the
user-defined communications applications and other applications. Key values can
also serve as a way to prioritize entries on the queue.</p>
<p>The content of the queue entries that the application defines and uses is
not restricted by the user-defined communications support. User-defined
communications support never attempts to receive any entries from the queue. It
is the responsibility of the application to receive the entries from the queue
and perform the appropriate actions for an entry based on its handle (or timer
handle).</p>
<p>This means that it might be necessary for the application to clear the old
messages from the queue if it has been used. For example, if a link is
disabled, all communications entries for that link (denoted by the
communications handle) prior to the disable complete entry are no longer
valid.</p>
<p><strong>Note:</strong> Timer support does not depend on the user-defined
communications support; therefore, timer entries are still valid.</p>
<p>The following example shows an incoming data entry that the application
receives is no longer valid because the application made a request to disable
the link.</p>
<p><strong><a name="FIGSCEN2">Figure 1-17. Application Disables the
Link</a></strong></p>
<p><img src="RBAFX623.gif" alt="Application Disables the Link"></p>
<hr>
<h2><a name="Header_43">User Space Considerations</a></h2>
<p>Your application uses user space objects (*USRSPC) to hold the input and
output buffers and descriptors. The iSeries server provides APIs you can use to
manipulate the user spaces.</p>
<p>When you use the user-defined communications support, you create the user
spaces, a total of four, as part of an enable link request (the QOLELINK API).
For each link, there is an input buffer, input buffer descriptor, output
buffer, and output buffer descriptor. The buffers and descriptors are used to
pass information to and from your application program. The buffers are used to
contain user data. The descriptors are used to describe the data (length and
other qualifiers). If the enable link request is not successful (return and
reason codes are nonzero), the user spaces are not created.</p>
<p><strong><a name="FIGSCEN3">Figure 1-18. User Spaces</a></strong></p>
<p><img src="RBAFX624.gif" alt="User Spaces"></p>
<p>The buffers are divided into equally sized, contiguous sections called data
units. The output buffer contains data to be sent on the network. The input
buffer contains data received from the network. The size of each data unit, as
well as the number of data units created, is returned from the QOLELINK API
when the link is enabled.</p>
<p>The buffer descriptors are divided into equally sized, contiguous sections
called descriptor elements. Each descriptor element describes the data in the
corresponding data unit of the buffer. For example, descriptor element 1
describes the data in data unit 1 of the buffer. The size of each descriptor
element is 32 bytes.</p>
<p>For complete and specific information about the input/output buffers,
descriptors, data units, and data elements, see the sections in <a href=
"comm4.htm">User-Defined Communications Support APIs</a> describing the
individual APIs.</p>
<p>Your application provides the library and name of the user space object that
is created. The descriptive text for the object always contains the name of the
job that is using these spaces. Finally, when the link is disabled (either
explicitly or implicitly), these user spaces are deleted by the user-defined
communications support. See <a href="qoldlink.htm">Disable Link API</a> for
more information on disabling the link.</p>
<p>The application reads from the input buffer and descriptor, and writes to
the output buffer and descriptor. Similarly, the user-defined communications
support reads from the output buffer anddescriptor and writes to the input
buffer and descriptor. As soon as the call to the qolsend API or the QOLRECV
API is complete, the application can access these user spaces.</p>
<p>If changes or deletions to the user spaces occur while they are in use by
the user-defined communications support, a severe application error is reported
to the application, and communications over the link associated with the user
spaces is no longer possible.</p>
<p><strong><a name="FIGSCEN4">Figure 1-19. Input/Output
Operations</a></strong></p>
<p><img src="RBAFX625.gif" alt="Input/Output Operations"></p>
<p>The user-defined communications support defines logical views for the user
spaces. These views are sometimes called formats. There is a format for
filters, sending and receiving LAN frames, and sending and receiving X.25
packets. See <a href="qolsend.htm">Send Data API</a> and <a href="qolrecv.htm">
Receive Data API</a> for details on these formats.</p>
<p>Your application must set all the data fields required for the format. There
are two types of byte fields in the buffer and descriptors, character (CHAR)
and binary (BIN). Binary implies that the value is used as a numeric value.
Sometimes this might be a 1-byte numeric value; for example, 12 = X'0C'. If you
write the application in a language that is not capable of setting this type of
binary field, the field should be declared as character and set to X'0C'. The
character type contains an EBCDIC value, printable or not printable. In
contrast, all parameter values are either character or 4-byte binary. See <a
href="#HDRLANGUAG">Programming Languages</a> for help in writing your
application so that it can provide the expected input for the user-defined
communications support.</p>
<p>The communications support never changes the output buffer; therefore, your
application is responsible for initializing the buffer and descriptor for the
next operation, if necessary. The data in the output buffer can also be used to
help determine why a particular operation is not successful.</p>
<p>For performance reasons, your application should attempt to fill the output
buffer as completely as possible.</p>
<p>Finally, for security reasons, your application chooses the library the user
space object will reside in. The library can be any system library, including
QTEMP. The advantage (or disadvantage) of using QTEMP for user space objects is
that only the job which has enabled the links has access to the user
spaces.This is because a QTEMP library exists for each job on the system. If
the user space objects are in any other library, any job having authority to
the library that the user spaces are in can access them.</p>
<hr>
<h2><a name="HDRRCODES">Return Codes and Reason Codes</a></h2>
<p>When control returns from a user-defined communications API to your
application program, the status of the operation is located in the reason code
and return code output parameters for each API.</p>
<p>Return codes are 4-byte numbers that determine the recovery action to take.
They are grouped into the following categories:</p>
<ul>
<li>00 -- Operation successful, no recovery needed<br>
<br>
</li>
<li>80 -- Irrecoverable error, need to disable link<br>
<br>
</li>
<li>81 -- Irrecoverable error, do not need to disable link<br>
<br>
</li>
<li>82 -- Recoverable error, enable link failed<br>
<br>
</li>
<li>83 -- Recoverable error, see recovery actions</li>
</ul>
<p>Reason codes are 4-byte numbers that determine what error occurred. They are
grouped into the following categories:</p>
<ul>
<li>0000 -- No error<br>
<br>
</li>
<li>1xxx -- Parameter validation or format error<br>
<br>
</li>
<li>20xx -- Line, controller, or device description error<br>
<br>
</li>
<li>22xx -- Data queue error<br>
<br>
</li>
<li>24xx -- Buffer or buffer descriptor error<br>
<br>
</li>
<li>30xx -- Link state error<br>
<br>
</li>
<li>32xx -- Connection state error<br>
<br>
</li>
<li>34xx -- Timer state error<br>
<br>
</li>
<li>4xxx -- Communication error<br>
<br>
</li>
<li>8xxx -- Application error<br>
<br>
</li>
<li>9999 -- A condition in which an Authorized Program Analysis Report (APAR)
may be submitted</li>
</ul>
<p><strong>Note:</strong> 'x' represents any decimal number. For example, 1xxx
represents the range 1000 - 1999.</p>
<p>For complete and specific information about the reason codes and return
codes, see the sections in <a href="comm4.htm">User-Defined Communications
Support APIs</a> describing the individual APIs.</p>
<hr>
<h2><a name="HDRUDCMSG">Messages</a></h2>
<p>The following messages are used to signal the success or failure of
operations performed by the user-defined communications APIs:</p>
<ul>
<li><strong>Information</strong><br>
<br>
<table 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">CPI91F0 I</td>
<td valign="top">X.25 network error occurred.</td>
</tr>
<tr>
<td align="left" valign="top">CPI91F1 I</td>
<td align="left" valign="top">ISDN network error occurred.</td>
</tr>
</table>
<br>
</li>
<li><strong>Escape</strong><br>
<br>
<table 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">CPF91F0 E</td>
<td valign="top">Internal system error.</td>
</tr>
<tr>
<td align="left" valign="top">CPF91F1 E</td>
<td valign="top">User-defined communications application error.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td valign="top">Program or service program &amp;1 in library &amp;2 ended.
Reason code &amp;3</td>
</tr>
</table>
<br>
</li>
<li><strong>Diagnostic</strong><br>
<br>
<table 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">CPD91F0 D</td>
<td valign="top">Error detected in program &amp;1. Condition code is
&amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPD91F1 D</td>
<td valign="top">Unexpected error detected in program &amp;1. Condition code is
&amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPD91F2 D</td>
<td valign="top">User space &amp;1 or &amp;3 not accessible.</td>
</tr>
<tr>
<td align="left" valign="top">CPD91F3 D</td>
<td valign="top">Data limit exceeded. Some data not sent.</td>
</tr>
<tr>
<td align="left" valign="top">CPD91F4 D</td>
<td valign="top">Error while accessing queue &amp;1 in library &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPD91F5 D</td>
<td valign="top">Error while accessing queue. Time &amp;1 canceled.</td>
</tr>
<tr>
<td align="left" valign="top">CPD91F6 D</td>
<td valign="top">Error occurred on line &amp;1 while in use.</td>
</tr>
<tr>
<td align="left" valign="top">CPD91F7 D</td>
<td valign="top">Recovery canceled for network interface &amp;3 or line
&amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPD91F8 D</td>
<td valign="top">Error while accessing queue &amp;1 in library &amp;2.</td>
</tr>
<tr>
<td align="left" valign="top">CPD91F9 D</td>
<td valign="top">Error while enabling line &amp;1.</td>
</tr>
</table>
</li>
</ul>
<hr>
<table align="center" 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>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink