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:
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.
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.
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.
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.
For more information on jobs and subsystems, see the Work Management topic.
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.
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.
Figure 1-1 shows how user-defined communications relate to the i5/OS(R) job structure and the data queue or user queue that provides the ability to communicate between your application and the user-defined communications support.
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.
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.
Figure 1-1. Overview of API Relationships
Figure 1-2 shows two jobs, A and B. Each job is using the user-defined communications support to communicate with the networks attached to the iSeries(TM) server by the line description. The figure shows the relationship between the different APIs and the job which is running the application program.
The lines between the jobs indicate that callable APIs that are used to communicate between the application program and the system services shown.
Figure 1-2. Application Programming Interface to Job Structure
The following list pertains to Figure 1-2.
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.
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.
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.
Asynchronous operations do not complete when the qolsend API returns to the application. There are two steps for every asynchronous operation:
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.
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.
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.
Relatively little configuration is required by user-defined communications support to begin communications to the network. For information on configuration, see Configuration and Queue Entries.
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.
Note: 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.
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 (Figure 1-3 through Figure 1-14) 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.
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.
Figure 1-3. Example 1: Normal Connection Establishment
The user-defined communications support validates the request and issues the X.25 call request.
Figure 1-4. Example 2: Connection Request Cleared by Network/Remote System
The user-defined communications support validates the request and issues the X.25 call request.
Figure 1-5. Example 3: Request to Clear Connection with Outstanding Call (Unsuccessful)
The user-defined communications support validates the request and issues the X.25 call request.
The user-defined communications support validates the request and finds an error.
Figure 1-6. Unsuccessful Attempt to Clear Outstanding (Successful) Call
The user-defined communications support validates the request and issues the X.25 call request.
Figure 1-7. Example 5: Successful Attempt to Clear Outstanding (Successful) Call
The user-defined communications support validates the request and issues the X.25 call request.
Figure 1-8. Example 6: Successful Attempt to Clear Outstanding (Unsuccessful) Call
The user-defined communications support validates the request and issues the X.25 call request.
Figure 1-9. Example 7: Unsuccessful Attempt to Clear Outstanding (Unsuccessful) Call
The user-defined communications support validates the request and issues the X.25 call request.
The following figures show how the application program handles UCEPs and PCEPs for incoming connections.
Figure 1-10. Example 1: Normal Connection Establishment
Figure 1-11. Example 2: Send Call Accept Not Valid
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.
Figure 1-12. Example 3: Send Clear for Incoming Call
The close connection request is validated and a clear is sent.
Figure 1-13. Example 4: Send Clear for Incoming Call
The following figures show how the application program closes a connection. The figures apply to both incoming and outgoing connections.
The next two figures illustrate that a close connection request never completely guarantees the connection will be closed.
Figure 1-14. Example 1: Close Connection Request Is Not Valid
Figure 1-15. Example 2: Close Connection Request Is Valid
User-defined communications over LANs use connectionless (unacknowledged) service. Unacknowledged Information (UI) frames are the only frames an application program can generate.
For a description of the frame formats for Ethernet Version 2, IEEE 802.3,
IEEE 802.5, wireless, and FDDI, refer to the LAN, Frame-Relay and ATM Support
book. To determine how the format and the user buffer are
specified, see User-Defined Communications Support
APIs.
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:
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.
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.
Note: 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.
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.
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.
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.
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.
Maximum Frame Size
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.
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.
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.
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.
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.
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.
The IBM(R) 8209 Ethernet to token-ring bridge provides additional connectivity options for the iSeries server. See the IBM 8209 LAN Bridge Customer Information book, SA21-9994, for more details.
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.
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.
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.
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. End-to-end connectivity 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.
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 X.25 Network Support
book provides more information about configuration limitations.
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.
A packet 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.
| Packet Type | Application Input or Access | SVC | PVC | N/A |
|---|---|---|---|---|
| Data | Q,D bits of the general format
identifier (GFI)
Note: 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. |
X | X | |
| Interrupt | 32 bytes of data
Note: 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. |
X | X | |
| Reset request | Cause and diagnostic codes
Note: The application program provides the confirmation of this packet. |
X | X | |
| Reset indication | Cause and diagnostic codes
Note: The application program provides the confirmation of this packet. |
X | X | |
| Reset confirmation |
Note: User-defined communications support detects and reports reset collisions to the application on the reset confirmation. |
X | X | |
| Incoming Call | 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 | X | ||
| Call Request | 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 | X | ||
| Call Accept | Packet and window sizes, up to 109 bytes of additional facilities | X | ||
| Call Connected | Negotiated packet and window sizes, facilities | X | ||
| Clear request | Cause and diagnostic codes, facilities, up to 128 bytes of clear user data | X | ||
| Clear indication | Cause and diagnostic codes, facilities, up to 128
bytes of clear user data
Note: The X.25 packet layer support provides the confirmation on this request. |
X | ||
| Clear confirmation | The X.25 packet layer support provides this support. | X | ||
| Receive Ready (RR) | The flow of RR and RNR packets is determined by the automatic flow control field of Format I, specified in the open connection request. | X | ||
| Receive Not Ready (RNR) | The flow of RR and RNR packets is determined by the automatic flow control field of Format I, specified in the open connection request. | X | ||
| Reject (REJ) | This packet is not necessarily available on all networks and is not supported by the iSeries server. | X | ||
| Restart Request, Indication, and Confirmation | These packets affect all virtual circuits on the line. | X | ||
| Diagnostic | This packet is not necessarily available on all networks and is not supported by the iSeries server. | X | ||
| Registration Request and Confirmation | This packet is not necessarily available on all networks and is not supported by the iSeries server. | X |
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.
The open connection request, close connection request, and reset request (or response) operations are two-step operations. See Synchronous and Asynchronous Operations for more information on programming for two-step operations.
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 Synchronous and Asynchronous Operations for more information on programming for one step operations.
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.
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.
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.
Notes:
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.
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:
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.
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.
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 Using Connection Identifiers for information on how to reuse connection identifiers.
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.
The application program can use the UCEP as an index into the program's data structures, which keep track of this control information.
Configuration
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.
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.
See the X.25 Network
Support book for more information on
configuring X.25 line descriptions.
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.
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.
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.
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.
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.
Configuration
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.
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.
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.
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.
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.
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.
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.
Data Sizes
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 X.25 SVC and PVC Output Operations for information about these values.
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.
The application uses three values to determine how to fill the user-space output buffer. These values are:
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.
Note: 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.
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.
See Maximum Amount of Outstanding Data for related information on incoming data limitations.
Interrupts
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.
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.
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.
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.
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.
Maximum Amount of Outstanding Data
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.
Reset Support
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.
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 X.25 Network Support book.
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:
In these situations, it may be appropriate to have one job for each connection (each virtual circuit).
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 CL Programming topic. The link will never be fully enabled if the queue does not exist. For example, in Figure 1-16, 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.
Figure 1-16. Using the Data Queue
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.
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.
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).
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.
Note: Timer support does not depend on the user-defined communications support; therefore, timer entries are still valid.
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.
Figure 1-17. Application Disables the Link
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.
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.
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.
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.
For complete and specific information about the input/output buffers, descriptors, data units, and data elements, see the sections in User-Defined Communications Support APIs describing the individual APIs.
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 Disable Link API for more information on disabling the link.
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.
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.
Figure 1-19. Input/Output Operations
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 Send Data API and Receive Data API for details on these formats.
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 Programming Languages for help in writing your application so that it can provide the expected input for the user-defined communications support.
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.
For performance reasons, your application should attempt to fill the output buffer as completely as possible.
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.
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.
Return codes are 4-byte numbers that determine the recovery action to take. They are grouped into the following categories:
Reason codes are 4-byte numbers that determine what error occurred. They are grouped into the following categories:
Note: 'x' represents any decimal number. For example, 1xxx represents the range 1000 - 1999.
For complete and specific information about the reason codes and return codes, see the sections in User-Defined Communications Support APIs describing the individual APIs.
The following messages are used to signal the success or failure of operations performed by the user-defined communications APIs:
| Message ID | Error Message Text |
|---|---|
| CPI91F0 I | X.25 network error occurred. |
| CPI91F1 I | ISDN network error occurred. |
| Message ID | Error Message Text |
|---|---|
| CPF91F0 E | Internal system error. |
| CPF91F1 E | User-defined communications application error. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3 |
| Message ID | Error Message Text |
|---|---|
| CPD91F0 D | Error detected in program &1. Condition code is &2. |
| CPD91F1 D | Unexpected error detected in program &1. Condition code is &2. |
| CPD91F2 D | User space &1 or &3 not accessible. |
| CPD91F3 D | Data limit exceeded. Some data not sent. |
| CPD91F4 D | Error while accessing queue &1 in library &2. |
| CPD91F5 D | Error while accessing queue. Time &1 canceled. |
| CPD91F6 D | Error occurred on line &1 while in use. |
| CPD91F7 D | Recovery canceled for network interface &3 or line &1. |
| CPD91F8 D | Error while accessing queue &1 in library &2. |
| CPD91F9 D | Error while enabling line &1. |
| Top | Communications APIs | APIs by category |