Fundamental Concepts of the IBM Conventional LU Application

This chapter describes the IBM® conventional logical unit application (LUA) access method and describes its relationship to Systems Network Architecture (SNA).

Note:
Included in the chapters of Part 2 of this book is information on the LUA API provided by the following systems: When there are differences between the support provided by these systems, it is noted.

Understanding LUA and SNA

The IBM LUA access method provides an application programming interface (API) for secondary dependent logical units (LUs). LUA consists of system software and interfaces that supply input/output (I/O) service routines to support communications using LU types 0, 1, 2, and 3 SNA protocols. The RUI and SLI interface of LUA is supported.

The Communications Server is designed to be binary compatible with Microsoft® NT SNA Server and similar to the implementation of Communications Server/2.

The services that LUA provides to application programs include only those that support data communications; LUA does not provide any device emulation facilities. However, LUA does provide a unique subset of presentation services layer functions.

Communications Server must be installed and configured before an LUA application program can run on the workstation. Refer to Quick Beginnings for information about installing and configuring Communications Server.

Connection Capabilities

The main objective of any communications system is to connect with other systems. The goal of SNA is to supply common protocols that give universal connectivity. LUA communication and connectivity requirements include the System/370™ (S/370™) connections.

LUA Application Programs

In this book, the term LUA application program means an application program, or a portion of an application program, that uses LUA communications functions. Application programs use these functions to communicate with application programs on other systems that support LU types 0, 1, 2, or 3.

As a local LUA application program runs, it exchanges data with a remote host application program. The local and remote application programs are called partner application programs.

LUA Verbs

A verb is a formatted request that is processed by LUA. An application program issues a verb to request that LUA take some action. LUA verbs are coded as control blocks. Each verb control block has a precisely defined format. To use the LUA facilities, an application program supplies verb control blocks to the LUA API.

An LUA verb always returns immediately to its caller. If the return code is IN_PROGRESS, the application needs to wait for completion of the verb, using the posting method specified in the verb request. See RUI LUA Entry Points for a description of LUA verb postings.

Verb control block layouts are available in the INCLUDE directory. You can use the verb control block layouts and sample programs to help you write LUA application programs.

LUs, Local LUs, and Partner LUs

A logical unit (LU) manages the exchange of data between application programs. Every LUA application program gains access to an SNA network through an LU, which acts as an intermediary between the LUA application program and the SNA network.

In LUA, there is a one-to-many relationship between LUA application program processes and LUs. One LUA application program process can own multiple LUs simultaneously, but a given LU can be owned by only one LUA application program process simultaneously. Before a second application program process can use an LU, the first application program must release the LU.

An LUA application program issues LUA verbs to its local LU. These verbs cause commands and data to flow across the network to the partner LU.

Note:
You need to define your local LU only once for each machine, as described in Quick Beginnings.

System Services Control Point (SSCP)

The system services control point (SSCP) component in a host system is responsible for starting host applications, for associating host applications with dependent LUs, and for creating and terminating the connections between LUs.

SNA Layers

SNA is a hierarchical structure that consists of seven well-defined layers. Each layer in the architecture performs a specific function. Understanding the layered structure of SNA helps in understanding the various functions that LUA supplies. The following descriptions of the five highest-level SNA layers show the relationship between LUA and SNA.

Data Link Control Layer

The data link control (DLC) layer consists of the elements that provide an interface to the hardware. The DLC elements supply support for various DLC protocols, such as Synchronous Data Link Control (SDLC) and the IBM Token-Ring Network. The DLC layer supplies a common link appearance to the elements in the path control (PC) layer. The DLC layer is common to all Personal Communications LU implementations, including LUA.

Path Control Layer

The path control (PC) layer of SNA in a peripheral node supplies basic functions, such as routing to and from multiple half-sessions within its node. SNA permits the PC layer to route to and from only one data link at a time. The PC layer is common to all Personal Communications LU implementations, including LUA.

Transmission Control Layer

The transmission control (TC) layer of SNA supplies the connection-point-manager function and the session-control function for each locally supported half-session. The connection-point-manager function controls sequence-number checking, pacing, and other support functions that relate to half-session data flows. The session-control function supplies session-specific support for starting, pacing, enciphering, deciphering, and other support functions that relate to session-related data flows. LUA contains an implementation of the TC layer for LU types 0, 1, 2, and 3 within Personal Communications.

Data Flow Control Layer

The data flow control (DFC) layer of SNA controls the flow of function management data (FMD) requests and FMD responses between FMD pairs that are in sessions and between sessions. The data flow control layer supplies various functions, such as request/response formatting, data-chaining protocol, request/response correlation, send- and receive-mode protocols, bracket protocol, error-recovery protocol, stop-bracket-initiation protocol, and queued-response protocol. LUA contains an implementation of the data flow control layer for LU types 0, 1, 2, and 3 within Personal Communications.

Presentation Services Layer

The presentation services (PS) layer of SNA contains the function that presents the communications data interface to the user. The presentation services layer is defined in the architecture for all LU types except LU 0. LUA contains a unique subset of the presentation services layer within Personal Communications. For more information about the presentation services layer, refer to Systems Network Architecture Concepts and Products.

The LU services functions are a part of the SNA-session message flow layers. These functions supply support before session establishment, build session structures, and take down session structures. LUA functions interface with common Personal Communications and Communications Server support to define LUs and to start and stop SNA sessions.

Using SNA Sessions

Before an LUA application program can communicate with a partner host application program, the respective LUs must be connected in a mutual relationship called a session. An SNA session is a logical connection that enables two network addressable units (NAUs) to communicate with each other; an LU is one kind of NAU. Because the session connects two LUs, it is called an LU-LU session. LU-LU sessions enable end users to exchange data.

A session manages how data moves between a pair of LUs in an SNA network. Therefore, sessions are concerned with such things as the quantity of data being transmitted, data security, network routing, data loss, and traffic congestion. Session characteristics are determined by the SNA BIND command originating from the primary LU, when the secondary LU accepts the BIND command.

Prerequisites to an SNA Session

An LU-LU session consists of communication between a primary logical unit (PLU) and a secondary logical unit (SLU). The SLU is implemented by the LUA application program. Before data can be transferred between a PLU and an SLU on an LU-LU session, the following events must occur:

  1. Personal Communications and Communications Server activate the data link.
  2. When the data link is ready, the system services control point (SSCP) establishes a session between itself and a physical unit (SSCP-PU session) by sending an Activate Physical Unit (ACTPU) command and reading a positive response from either the Personal Communications or Communications Server program. Then either program sends a positive response if the PU address from the ACTPU command corresponds to the configuration information.
  3. The SSCP establishes a session between itself and the logical unit (SSCP-LU session) by sending an Activate Logical Unit (ACTLU) command and reading a positive response from either the Personal Communications or Communications Server program. Then either program sends a positive response if the LU address from the ACTLU command corresponds to the configuration information.

Starting Sessions

Either the SLU or the PLU can start an LU-LU session.

Starting an LU-LU Session from an SLU

After the SSCP-LU session is established, the SLU program can request an LU-LU session by sending the Initiate Self (INITSELF) command to the SSCP. The SSCP receives the INITSELF command and checks whether the named host application program is valid. A host application program is valid if it is known and active. If the host application program is valid, the SSCP sends a positive response to the SLU, and the PLU starts the session. If the host application program is not valid, the SSCP sends a negative response to the SLU, and the PLU does not start the session.

If the SSCP sends a positive response to an INITSELF command but the session cannot be established, the SSCP sends a Network Services Procedure Error (NSPE) command to the SLU to stop the attempt to establish a session. The SLU can reissue the INITSELF command after the NSPE command.

Starting an LU-LU Session from a PLU

The PLU program can start unsolicited LU-LU sessions. The PLU starts sessions by generating a BIND command. A subsequent positive response establishes the agreement to communicate. A data field that is associated with the BIND command contains the name of the PLU application program and the session BIND parameters. For more information about the format of this data field, refer to Systems Network Architecture: Formats.

For nonnegotiable BINDs, the SLU returns a positive response if the parameters are acceptable. If the parameters are unacceptable, the SLU returns a negative response with sense data to the PLU.

The negotiable BIND command permits the SLU to return a positive response with a minimum of 26 bytes of updated session parameters indicating compatibility with the PLU parameters. If the PLU finds the returned parameters acceptable, it sends a Start Data Traffic (SDT) command. If the returned parameters are unacceptable, the PLU sends an UNBIND command that indicates unacceptable negotiable BIND command parameters from the SLU.

Transferring Data on an LU-LU Session

After the LU-LU session is established and the SLU program responds to the SDT command, data transfer can begin. For a data transmission operation, a message moves from end-user storage to Personal Communications or Communications Server storage until it is transmitted. For a data-reception operation, either program would place a message in its own storage and then move the message into end-user storage.

Quiesce protocols suspend the transfer of data in an LU-LU session. The PLU or the SLU can send the following Quiesce protocol commands:

Stopping Sessions

When all data has been transferred and verified, the session can end. An SLU must end one session before it can begin a different session with either the same or another PLU.

Stopping an LU-LU Session by an SLU

An SLU can end an LU-LU session in either of two ways:

To end a session immediately, the SLU sends the TERMSELF command to the SSCP, which checks whether the named LUA application program is the one participating in this session. If it is, the SSCP sends a positive, nondata response. Depending on the host SNA version being used, the SSCP can send a CLEAR command, which purges all messages from the LU-LU session, and can then send an UNBIND command to end the session. Alternatively, the SLU can send an UNBIND command to the PLU.

Stopping an LU-LU Session by a PLU

A PLU can end an LU-LU session in either of two ways:

Ending the LU-LU session has no effect on the SSCP-LU session.

Stopping an SSCP-LU Session and an SSCP-PU Session

The SSCP-LU session ends when the host sends the Deactivate Logical Unit (DACTLU) command to the SLU. When the last SSCP-LU session for Personal Communications ends, the SSCP can end the SSCP-PU session by sending a Deactivate Physical Unit (DACTPU) command.

Disconnecting the Host Link

When the host receives the response to the DACTPU command, it returns a command to Personal Communications such as the Set Disconnect Response Mode (SDRM) command when using SDLC protocol. The SSCP can also disconnect immediately at any time by sending the same command to Personal Communications, which ends all sessions. When sessions are ended in this manner, all SLUs that were active earlier receive a loss-of-contact indication.

Message Numbers

All normal-flow messages that are transmitted between the SLU and the PLU during an LU-LU session are numbered in sequence. The SLU maintains a sequence number for normal-flow messages from the SLU to the PLU and another sequence number for normal-flow messages from the PLU to the SLU. Each normal-flow message gets a sequence number one greater than the sequence number of the preceding normal-flow message. There is one pair of sequence numbers for each session that is established between an SLU and a PLU.

For LU-LU expedited-flow messages and for all SSCP-LU and SSCP-PU messages, unsequenced identifiers are used instead of sequence numbers.

When a session is reestablished or a CLEAR command is sent, the PLU and the SLU set their sequence numbers to 0. The PLU can change the sequence numbers with the Set and Test Sequence Numbers (STSN) command. This enables correct sequence numbering when a session is recovered or restarted.

When the SLU encounters a sequence number error, it sends a negative response to the PLU if a response was requested. When the SLU reads a response, the SLU uses the response sequence number to correlate the response with the original request. When the SLU writes a response, the SLU must supply the sequence number of the original request.

Restarting and Resynchronizing a Session

If the PLU or the SLU encounters an unrecoverable error, such as a line failure, you might need to resynchronize the LU-LU session after restarting it. Resynchronizing the LU-LU session includes reprocessing recoverable messages and (optionally) resetting the message sequence numbers. The application programs can include routines to retransmit lost messages.

When a session is restarted and resynchronized, the PLU sends the BIND, the STSN, and the SDT commands. When the STSN command is sent, a dialog can occur to establish the sequence numbers that are acceptable to both the PLU and the SLU. This dialog consists of a series of STSN messages and positive responses.

If the SLU determines that resynchronization is required, the SLU can send a Request Recovery (RQR) command, a negative response, or an LU-Status command (LUSTAT) with a description of the failure in the user sense bytes. If the PLU discovers the failure or receives an RQR command from the SLU, the PLU sends a CLEAR command to purge all LU-LU messages from the network, an STSN command to establish new sequence numbers, and then an SDT command.

Using Protocols to Control Requests and Responses

Various protocols can control the sequencing rules for requests and responses. This section describes some of the protocols used for managing the SNA network, transferring data, and synchronizing the states of network components.

Using the Pacing Protocol

To avoid a message-flow rate that is too fast for Personal Communications or the host, you can specify pacing in the BIND command. Pacing applies to the LU-LU normal flow only. While pacing, Personal Communications permits a specified number of messages to flow and waits for a response before permitting additional messages to be sent. You can specify pacing on Personal Communications-to-host flow, the host-to-Personal Communications flow, or both. Once the LU-LU session starts, LUA handles all pacing with no participation by the application program.

Receive-Pacing Protocol

Receive-pacing protocol gives the PLU control over the number and the frequency of messages sent from the SLU on an LU-LU session. When the SLU receives pacing values in the BIND command, Personal Communications automatically enforces pacing for each SLU that communicates with the host.

During a positive response to a negotiable BIND command, you can change the pacing values to any number except 0. When the SLU sends the first message of a sequence, Personal Communications set a bit in the request/response header (RH) that indicates a pacing response is to be returned. If the pacing count is exhausted before either program receives a pacing response from the PLU, neither program can send additional data messages. If the application program issues a write operation and no pacing response is received, Personal Communications defer the write operation.

Send-Pacing Protocol

The SLU automatically controls the send-pacing protocol. If the pacing indicator is set on in a message from the PLU to the SLU, the SLU issues a pacing response when the application program reads the message. The message response can contain the pacing indicator or, if no response is required for the received message, the pacing response can be an isolated pacing response (IPR). The PLU can then send another pacing window of messages.

Using the Half-Duplex Contention/Flip-Flop Protocol

The change-direction (CD) indicator is used with both of the following protocols:

A CD indicator tells the receiver that transmitting can begin.

For example, if the SLU initiates a transaction, the SLU begins by sending the messages that completely describe the transaction. On the last message, the SLU sets the CD indicator to tell the PLU that it can begin transmitting a reply. If the PLU needs additional information to complete the transaction, it sends an inquiry and sets the CD indicator. The dialog proceeds in this half-duplex mode until the transaction is complete. During a half-duplex dialog, the SLU can use the SIG command to tell the PLU to stop sending data and to change the direction of the data flow.

Using the Bracket Protocol

Bracket protocol gives the SLU and the PLU context control of the data transmission, indicating that a session concerns a single transaction. Bracket protocol protects a current session from interruption by a concurrent transaction. A bracket encompasses the duration of a transaction.

The first message in the bracket contains a begin-bracket (BB) indicator, and the last message in the bracket contains an end-bracket (EB) indicator. A single message can be a bracket if it contains both indicators.

For a bracket session, the BIND command specifies one LU as the first speaker, and the other LU as the bidder. The first speaker can begin a bracket without permission from the other LU. The bidder, however, must request and receive permission from the first speaker to begin a bracket.

A BID command is a normal-flow request that is issued by the bidder to request permission to begin a bracket. A positive response to a BID command indicates that the first speaker will not begin a bracket but will wait for the bidder to begin a bracket. A negative response to a BID command indicates that the first speaker denies permission for the bidder to begin a bracket. The first speaker can send a Ready-to-Receive (RTR) command when permission is granted to start a bracket.

The first speaker indicates a negative response to a BID command with one of two response codes:

Bracket-Bid-Reject-RTR-Forthcoming
Indicates that an RTR command for that BID command will be sent later (granting permission to start a bracket). The bidder can wait for the RTR command or send the BID command again.
Bracket-Bid-Reject-No-RTR-Forthcoming
Indicates that no RTR command for that BID command will be sent later. The bidder must send the BID command again if the bidder still wants to begin a bracket.

Instead of sending a BID command followed by a first-in-chain FMD with a BB indicator, the bidder can attempt to initiate a bracket by sending a first-in-chain FMD with a BB indicator. The first speaker can grant the attempt with a positive response or it can refuse the attempt with a negative response that indicates either of the negative response codes. However, if the bidder stops the chain that carries the BB indicator by sending the CANCEL command, the bracket is not initiated, regardless of the response. The RTR command can be issued by the first speaker either to grant permission to the bidder to begin a bracket or to find out if the bidder wants to begin a bracket.

A positive response to an RTR command indicates that the bidder will initiate the next bracket. If the bidder does not want to initiate a bracket, the bidder issues a negative response with the RTR-Not-Required sense code.

Using the Data-Chaining Protocol

Data chaining is an optional protocol for transmitting a group of related messages. To send chained messages from the SLU, the SLU sets to 1 the begin-chain (BC) indicator for the message to indicate the first message in a chain. For all messages between the first and the last in the chain, the SLU sets the BC and the end-chain (EC) indicators to 0. For the last message in the chain, the EC is set to 1 again. When the SLU receives messages, it tests the chaining indicator to determine if the messages are chained.

The data-chaining protocol comprises three types of chains, as follows:

When sending a message chain to the PLU, the SLU can send a CANCEL command if the SLU or the PLU finds a message error. If the SLU sends a CANCEL command to the PLU, the PLU discards all messages in the chain that it has received. If the PLU sends a negative response to any element of a chain, the SLU ends the chain normally or sends a CANCEL command.

Data Exchange Control Methods

An SNA session is conducted under rules for orderly exchange of data.

Flow Protocols

At the transport level, data is exchanged through either a half-duplex (HDX) protocol or a full-duplex (FDX) protocol.

When a half-duplex protocol is used, data flows in only one direction at a time, with one LU sending only and the other receiving only. In a half-duplex flip-flop protocol, both LUs recognize which LU has the right to send and which to receive. At specified times the partner LUs agree to change the direction so that the receiver can send and the sender can receive.

When a full-duplex protocol is used, data can flow in either direction at any time. Both LUs can send and receive without constraint.

Response Modes

Each SNA message is either a request or a response. Every request from one LU elicits a matching response from the partner LU. Because the response carries the same transmission sequence number as the request, responses and requests can be matched by their sequence numbers.

When your application has received a request whose RH specifies a mandatory response, your application must generate and send a response message. The response mode rule determines when the response must be sent.

Under immediate response mode, your application must send a response to a request before it sends any request of its own. Under delayed response mode, however, responses can be sent at any time after a request is received.

LUA Correlation Tables

LUA keeps track of the sequence numbers of incoming and outgoing requests until they receive responses, until the application issues a response to an incoming request, or until the PLU responds to an outgoing request. These numbers are recorded in Personal Communications and Communications Server areas called correlation tables.

Under immediate response mode, only a few outstanding requests can be generated in a session, typically one at most. Under delayed response mode, the number can be larger.

The LUA correlation tables are managed dynamically. LUA can record any number of responses. If a very large number of responses accumulate (probably due to a program logic error), the server runs low on memory and Personal Communications might shut down.

Exception Response Requests (RQEs)

In most cases, LUA can correlate requests and responses automatically, without any help from your program. LUA observes the request and response RUs as they flow in the session. LUA can tell when a request needs a response, and when the response has been sent. However, there is one case in which LUA cannot tell if a response will be sent, and your program must tell it.

Bit fields in the RH of a request specify whether a response is mandatory, not wanted, or optional. When no response is wanted, LUA need not store the request number in its correlation table. A mandatory response must be sent as the next message on that flow. LUA enters the message in the correlation table, but it will quickly be cleared because the response must come next.

The error response indicator (ERI) in the RH specifies that a response is optional, required only if the receiving LU cannot accept or process the RU. This optional-response RU is called an exception response request (abbreviated RQE). LUA cannot always manage its correlation table automatically in the presence of RQEs. Table Table 11 summarizes the instances in which LUA can clear a received RQE automatically from its correlation table, and those in which LUA must wait for a signal from the application before clearing a received RQE.

Table 11. Clearing of RQEs
Immediate Response Mode Delayed Response Mode
Verbs HDX FDX HDX FDX
RUI_READ Automatic Automatic Application response Application response
RUI_WRITE Automatic Application response Application response Application response

In immediate response mode on either an HDX or FDX session, LUA can discard the number of an RQE as soon as the application requests input (uses RUI_READ), because, in immediate response mode, a response must be sent before another request can be issued. Also, in immediate response mode on an HDX connection, LUA can discard the number of an RQE as soon as the application requests output (uses RUI_WRITE)--because the output will either be the RQE response, or no response is going to be sent.

In all other instances, LUA cannot be sure whether a response to the RQE will be produced. The application must format and send a positive response to an RQE, not for the benefit of the PLU (which wants only negative responses) but to inform LUA that the RQE was accepted and will not be generating a negative response.

LUA can then clear the RQE from its table. Because the response is a positive one and the PLU wanted only negative ones, LUA does not transmit the application's response on the network.

In short, simply to assist LUA, your application must treat received RQE RUs as if they were definite-response RUs.

Session Profiles

The specific SNA protocols and conventions that can be used on a given session, taken together, comprise the profile of the session. Two profiles, the transmission services (TS) profile and the function management (FM) profile, can be bound to the session. The choice of profiles is made at BIND time.

TS Profiles

Five TS profiles, numbered 1, 2, 3, 4, and 7 are defined by SNA. However, because TS profile 1 is used only between the SSCP and the PU, only profiles 2, 3, 4, and 7 are applicable to an LUA application. They differ in the SNA commands that can be issued, as shown in Table Table 12.

Table 12. TS Profile Characteristics
Profile Pacing Use CLEAR CRV RQR SDT STSN
2 Always Used Not used Not used Not used Not used
3 Always Used Optional Not used Used Not used
4 Always Used Optional Used Used Used
7 Optional Not used Optional Not used Not used Not used

FM Profiles

Eight FM profiles, numbered 0, 2, 3, 4, 6, 7, 18, and 19 are defined by SNA. However, because profiles 0 and 6 are used only by the SSCP, and profile 19 is used only with LU type 6.2, five profiles can be applicable to an LUA application. Each profile differs in the SNA facilities that are restricted.

An approximate summary of the FM profiles is shown in Table 13. In the table, a blank cell means that the SNA facility is not restricted in this profile--it can have any use that can be specified in the BIND parameters.

The LUA RUI supports FM profiles 2, 3, 4, 7, and 18.

Table 13. FM Profile Characteristics
SNA Facility FMP 2 FMP 3 FMP 4 FMP 7 FMP 18
Request mode SLU uses delayed
Response mode SLU uses immediate Immediate Immediate Immediate Immediate
RU chains Single RU chains only
Length-checked compression LU 0 only
FMH-1 session control block (SCB) compression Not allowed
Data flow control RUs allowed None
  • CANCEL
  • SIGNAL
  • LUSTAT (SLU only)
  • CHASE
  • SHUTD
  • SHUTC
  • RSHUTD
  • BID, RTR
  • CANCEL
  • SIGNAL
  • LUSTAT
  • QEC
  • QC
  • RELQ
  • CHASE
  • SHUTD
  • SHUTC
  • RSHUTD
  • BID, RTR
  • CANCEL
  • SIGNAL
  • LUSTAT
  • RSHUTD
  • CANCEL
  • SIGNAL
  • LUSTAT
  • CHASE
  • BIS, SBI
  • BID, RTR
FM Headers Not allowed
Brackets Restricted use
Flow protocol FDX
Recovery By PLU only

Using RUI LUA Verbs

An application accesses LUA through LUA verbs. Each verb supplies parameters to LUA, which performs the desired function and returns parameters to the application.

Verb Summary

The following is a brief summary of the seven LUA verbs that an application can use. (For a detailed explanation of each verb, see RUI Verbs.)

RUI_BID
Enables the application to determine when information from the host is available to be read.
RUI_INIT
Sets up the LU-SSCP session for an LUA application.
RUI_PURGE
Cancels an outstanding RUI_READ verb.
RUI_READ
Receives data or status information sent from the host to the LUA application's LU, on either the LU-SSCP session or the LU-LU session.
RUI_TERM
Ends the LU-SSCP session for an LUA application. It also brings down the LU-LU session if it is active.
RUI_WRITE
Sends data to the host on either the LU-SSCP session or the LU-LU session.

RUI Sessions

An RUI session consists of the ownership of an LU for a period of time determined by the application, which can include establishing a session between an SSCP and an LU (called an SSCP-LU session). An RUI session can also include establishing one or more non-overlapped LU-LU sessions. If the SSCP-LU session fails because of a loss-of-contact or another reset condition, the RUI session ends. An RUI session begins with an RUI_INIT verb and ends normally with an RUI_TERM verb.

Issuing RUI Verbs

Table 14 shows the valid conditions under which an RUI application program can issue verbs to the RUI API for a given LU. The entries in the leftmost column represent incoming verbs. The entries in the first row represent verbs that are in progress. If an entry in the table is OK, the combination of verbs represents a valid condition. If an entry in the table is Error, the combination of verbs represents an incorrect condition and an error code is returned to the LUA application program.

Table 14. RUI Verb Conditions
In-Progress Commands
Incoming
Commands
No Current Session RUI_INIT RUI_TERM RUI_WRITE RUI_READ RUI_PURGE RUI_BID
RUI_INIT OK Error Error Error Error Error Error
RUI_TERM Error OK Error OK OK OK OK
RUI_WRITE Error Error Error OK

(See Note 1)

OK OK OK
RUI_READ Error Error Error OK OK

(See Note 2)

OK OK
RUI_PURGE Error Error Error OK OK Error OK
RUI_BID Error Error Error OK OK OK Error
Note:
  1. The RUI permits a maximum of two active RUI_WRITE verbs per session at the same time. The active RUI_WRITE verbs must be for different session flows. Four session flows are possible:
    • SSCP-LU expedited
    • SSCP-LU normal
    • LU-LU expedited
    • LU-LU normal
  2. The RUI permits a maximum of four active RUI_READ verbs per session at the same time. The active RUI_READ verbs must be for different session flows.

Asynchronous Verb Completion

Some LUA verbs complete quickly, after some local processing (for example the RUI_PURGE verb); however, most verbs take some time to complete because they require messages to be sent to and received from the host application. Because of this, LUA is implemented as an asynchronous interface; control can be returned to the application while a verb is still in progress, so the application is free to continue with further processing (including issuing other LUA verbs).The way that LUA returns control to the application is by way of an event handle in the verb.

If Personal Communications's verb response signal is delayed (for example, because it needs to wait for information from the remote node), then the stub should return the verb asynchronously. The API does this by setting the primary return code to LUA_IN_PROGRESS, and the lua_flag2 to LUA_ASYNC. The application can now either perform other processing, or wait for notification from the API that the verb has completed. When the verb completes, the application is notified by the setting of the primary return code in the VCB to its final value, and leaving the lua_flag2 set to LUA_ASYNC.

Sample LUA Communication Sequence

The following is an example of an LUA communication sequence. It shows the LUA verbs used to start a session, exchange data, and end the session, and the SNA messages sent and received. The arrows indicate the direction in which SNA messages flow.

The following abbreviations are used:

SSCP norm
LU-SSCP session, normal flow
LU norm
LU-LU session, normal flow
LU exp
LU-LU session, expedited flow
+rsp
Positive response to the indicated message
BC
Begin chain
MC
Middle of chain
EC
End chain
CD
Change direction indicator set
RQD
Definite response required
Verb issued by
LUA application
SNA message
Flow direction
Application     Host
RUI_INIT
(ACTLU)
<-----
 
(ACTLU +rsp)
----->
RUI_WRITE (SSCP norm)
INITSELF
----->
RUI_READ (SSCP norm)
INITSELF +rsp
<-----
RUI_READ (LU exp)
BIND
<-----
RUI_WRITE (LU exp)
BIND +rsp
----->
RUI_READ (LU exp)
SDT
<-----
RUI_WRITE (LU exp)
SDT +rsp
----->
RUI_WRITE (LU norm)
data, BC
----->
RUI_WRITE (LU norm)
data, MC
----->
RUI_WRITE (LU norm)
data, EC, CD, RQD
----->
RUI_READ (LU norm)
data +rsp
<-----
RUI_READ (LU norm)
data, BC
<-----
RUI_READ (LU norm)
data, MC
<-----
RUI_READ (LU norm)
data, EC, RQD
<-----
RUI_WRITE (LU norm)
data +rsp
----->
RUI_READ (LU exp)
UNBIND
<-----
RUI_WRITE (LU exp)
UNBIND +rsp
----->
RUI_TERM
(NOTIFY)
----->
 
(NOTIFY +rsp)
<-----
 
 
 

In this example, the application performs the following steps:

  1. Issues the RUI_INIT verb to establish the LU-SSCP session. (The RUI_INIT verb does not complete until Personal Communications programs have received an ACTLU message from the host and sent a positive response; however, these messages are handled by each program and not exposed to the LUA application.)
  2. Sends an INITSELF message to the SSCP to request a BIND, and reads the response.
  3. Reads a BIND message from the host, and writes the response. This establishes the LU-LU session.
  4. Reads an SDT message from the host, which indicates that initialization is complete and data transfer can begin.
  5. Sends a chain of data consisting of three RUs (the last indicates that a definite response is required), and reads the response.
  6. Reads a chain of data consisting of three RUs, and writes the response.
  7. Reads an UNBIND message from the host, and writes the response. This terminates the LU-LU session.
  8. Issues the RUI_TERM verb to terminate the LU-SSCP session. (Personal Communications programs send a NOTIFY message to the host and waits for a positive response; however, these messages are handled by each program and are not exposed to the LUA application.)

BIND Checking

During initialization of the LU-LU session, the host sends a BIND message to the Personal Communications LUA application that contains information such as RU sizes to be used by the LU-LU session. Personal Communications returns this message to the LUA application on an RUI_READ verb. It is the responsibility of the LUA application to check that the parameters specified on the BIND are suitable. The application has the following options:

See RUI Verbs, for more information on the RUI_WRITE verb.

Note:
Validation of the BIND parameters, and ensuring that all messages sent are consistent with them, is the responsibility of the LUA application. However, the following two restrictions apply:

Negative Responses and SNA Sense Codes

SNA sense codes may be returned to an LUA application in the following cases:

Distinguishing SNA Sense Codes from Other Secondary Return Codes

For a secondary return code which is not a sense code, the first two bytes of this value are always zero. For an SNA sense code, the first two bytes are non-zero; the first byte gives the sense code category, and the second identifies a particular sense code within that category. (The third and fourth bytes may contain additional information, or may be zero.)

Information on SNA Sense Codes

If you need information on a returned sense code, refer to IBM Systems Network Architecture: Formats. The sense codes are listed in numeric order by category.

Pacing

Pacing is handled by LUA; an LUA application does not need to control pacing, and should never set the Pacing Indicator flag.

If pacing is being used on data sent from the LUA application to the host (this is determined by the BIND), an RUI_WRITE verb may take some time to complete. This is because Personal Communications must wait for a pacing response from the host before it can send more data.

If an LUA application is used to transfer large quantities of data in one direction, either to the host or from the host (for example, a file transfer application), then the host configuration should specify that pacing is used in that direction; this is to ensure that the node receiving the data is not flooded with data and does not run out of data storage.

Segmentation

Segmentation of RUs is handled by LUA. LUA always passes complete RUs to the application, and the application should pass complete RUs to LUA.

Courtesy Acknowledgments

Personal Communications and Communications Server keep a record of requests received from the host in order to correlate any response sent by the application with the appropriate request.When the application sends a response, the Personal Communications programs correlate this with the data from the original request, and can then free the storage associated with it.

If the host specifies exception response only (a negative response may be sent, but a positive response should not be sent), Personal Communications must still keep a record of the request in case the application subsequently sends a negative response. If the application does not send a response, the storage associated with this request cannot be freed.

Because of this, Personal Communications enable the LUA application to issue a positive response to an exception-response-only request from the host (this is known as a courtesy acknowledgment). The response is not sent to the host, but is used by Personal Communications to clear the storage associated with the request.

Purging Data to End of Chain

When the host sends a chain of request units to an LUA application, the application may wait until the last RU in the chain is received before sending a response, or it may send a negative response to an RU which is not the last in the chain. If a negative response is sent mid-chain, Personal Communications purge all subsequent RUs from this chain, and do not send them to the application.

When Personal Communications receive the last RU in the chain, it indicates this to the application by setting the primary return code of an RUI_READ or RUI_BID verb to LUA_NEGATIVE_RSP with a zero secondary return code.

Note:
The host may terminate the chain by sending a message such as CANCEL while in mid-chain. In this case, the CANCEL message is returned to the application on an RUI_READ verb, and the LUA_NEGATIVE_RSP return code is not used.

Configuration

Each LU used by an LUA application must be configured using Personal Communications NOF verbs or through the SNA Node Configuration program. (Refer to System Management Programming for more information.) In addition, the configuration may include LUA LU pools.A pool is a group of LUs with similar characteristics, such that an application can use any free LU from the group. This can be used to allocate LUs on a first-come, first-served basis when there are more applications than LUs available, or to provide a choice of LUs on different links.

LUA LU Pool (Optional)

If required, you can configure more than one LUA LU for use by the application, and group the LUs into a pool. This means that an application can specify the pool rather than a specific LU when attempting to start a session, and will be assigned the first available LU from the pool.

An LUA application indicates to Personal Communications that it wants to start a session by issuing an RUI_INIT verb with an LU name. This name must match the name of an LUA LU or LU pool that has previously been defined in System Management Programming. Personal Communications and Communications Server use this name as follows:

SNA API Client Considerations

If your LUA application resides on a client workstation, an LUA session should also be defined on the local workstation. This LUA session name can contain multiple communication servers and LUA definitions, thus allowing the SNA client code to roll over to new servers when connections become unavailable.