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