Copyright: 3270 Emulator Interface Specification
Citation: 3270 Emulator Interface Specification


Microsoft SNA Server Master Table of Contents
Microsoft SNA Server

Master Table of Contents

	SNA Server Enhancements Guide
	SNA Server Installation Guide
	SNA Server Administration Guide
	Managing Microsoft SNA Server
	SNA Server Planning Guide
	SNA Server TN3270 Service
	3270/5250 Applet User's Guide
	SNA Server Reference
	SNA Server Glossary
	APPC Programmer's Guide
	CPI-C Programmer's Guide
	LUA Programmer's Guide
	SNA Device Interface Specification
	3270 Emulator Interface Specification
	Comprehensive Index


3270 Emulator Interface Spacification Contents
Microsoft SNA Server

3270 Emulator Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

Chapter 2	The DL-BASE/DMOD Interface

Chapter 3	The Function Management Interface (FMI)

Chapter 4	FMI: Message Formats

Chapter 5	FMI: Status, Error, and Sense Codes

Chapter 6	Configuration Information

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix


3270 Emulator Interface Spacification Contents
Microsoft SNA Server

3270 Emulator Interface Specification

Contents

Before You Begin

About This Manual

Operating Systems

Network Operating Systems

Chapter 1	Introduction

Chapter 2	The DL-BASE/DMOD Interface

Chapter 3	The Function Management Interface (FMI)

Chapter 4	FMI: Message Formats

Chapter 5	FMI: Status, Error, and Sense Codes

Chapter 6	Configuration Information

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix


3270 Emulator Interface Spacification Contents
Microsoft SNA Server

3270 Emulator Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

1.1  Structure of SNA Server Components

1.1.1  The Role of the BASE

1.1.2  Localities and DMODs

1.1.3  Application Localities

1.1.4  Partners

1.2  Messages

1.2.1  Overview of Message Formats

1.2.2  Buffer Header Format

1.2.3  Buffer Element Format

1.3  LPI Connections

1.3.1  Paths and DMODs

1.3.2  LPI Addresses

1.3.3  Making Connections

1.4  How DMODs Communicate

1.5  Internal Data Structures

Chapter 2	The DL-BASE/DMOD Interface

Chapter 3	The Function Management Interface (FMI)

Chapter 4	FMI: Message Formats

Chapter 5	FMI: Status, Error, and Sense Codes

Chapter 6	Configuration Information

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix


3270 Emulator Interface Spacification Contents
Microsoft SNA Server

3270 Emulator Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

Chapter 2	The DL-BASE/DMOD Interface

2.1  Introduction

2.1.1  Initialization

2.1.2  Sending Messages

2.1.3  Receiving Messages

2.1.4  Opening a Connection

2.1.5  Termination

2.2  MS-DOS  based 3270 Emulation

2.2.1  DOS 5 / Windows Task Switching

2.2.2  Client Environment for MS-DOS  Based Emulators

2.3  DL-BASE/DMOD Entry Points

2.3.1  DL-BASE Entry Points

SBPUINIT  Initialize the DL-Base

SBPURCVX  Process Open Responses from Routing Procedure

SBPUSEND  Send Message

SBPUTERM  Terminate

2.3.2  DMOD Entry Points

ROUTPROC  Sample Routing Procedure

SEPDCHNK  Get FMI Chunk Size

SEPDCREC  Get Configuration Information

SEPDGETINFO  Get System Information

SEPDROUT  Set Up Routing Procedure

SEPWROUT  Set Up Routing Procedure

CMDGoTSR  Force MS-DOS  based emulator resident

CMDStopFG  Suspend scheduling of foreground task

CMDStartFG  Resume scheduling of foreground task

RegisterSwitchProc  Register task switch procedure

CMDSemClear  Clear a RAM semaphore

CMDSemSet  Set a RAM semaphore

CMDSemWait  Wait until a RAM semaphore is cleared

CMDSemRequest  Request a RAM semaphore

SNAGetVersion  Get Version Number

2.3.3  Buffer Management Entry Points

SBPIBEGT  Get Buffer Element

SBPIBERL  Release Buffer Element

SEPDBUBL  Get Buffer

SEPDBURL  Release Buffer

2.4  Sample Code

2.4.1  Receiving Using Routing Procedure

Chapter 3	The Function Management Interface (FMI)

Chapter 4	FMI: Message Formats

Chapter 5	FMI: Status, Error, and Sense Codes

Chapter 6	Configuration Information

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix


3270 Emulator Interface Spacification Contents
Microsoft SNA Server

3270 Emulator Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

Chapter 2	The DL-BASE/DMOD Interface

Chapter 3	The Function Management Interface (FMI)

3.1  Introduction

3.1.1  Sessions and Connections

3.1.2  Application Flags

3.2  The SSCP Connection

3.2.1  Opening the SSCP Connection

LU Groups

Resource Location for Open SSCP

3.2.2  Closing the SSCP Connection

3.2.3  Using the SSCP Session

SSCP Session Characteristics

SSCP Session Status

3.2.4  RTM Parameters

3.2.5  3270 User Alerts

3.3  The PLU Connection

3.3.1  Opening the PLU Connection

BIND Checking

3.3.2  Closing the PLU Connection

3.3.3  Using the PLU Session

PLU Session Characteristics

PLU Session Status

3.3.4  Outbound Chaining

3.3.5  Inbound Chaining

3.3.6  Segment Delivery

3.3.7  Brackets

Bracket Initiation

Bracket Termination

3.3.8  Direction

Half Duplex Flip-Flop Direction

Half Duplex Contention

3.3.9  Pacing and Chunking

Outbound Pacing

Chunking

3.3.10  Confirmation and Rejection of Data

Confirmation and Rejection of Inbound Data

Confirmation and Rejection of Outbound Data

3.3.11  Shutdown and Quiesce

Shutdown

Quiesce

3.3.12  Recovery

Application Cancel

Direction After Receiving a Negative Response

Direction After Sending a Negative Response

Critical Failure

RQR and CLEAR

STSN

Link Service Failure

Local Node Failure

Client Failure

3.3.13  Application-Initiated Termination

3.3.14  LUSTATs

3.3.15  Response Time Monitor Data

3.4  Data Flow

3.4.1  Outbound Data

3.4.2  Inbound Data

3.4.3  Inbound Data from LUA Applications

3.5  Status Messages

3.5.1  Status-Acknowledge

3.5.2  Status-Control

Status-Control(...)ACKLUA

3.5.3  Status-Error

3.5.4  Status-Resource

3.5.5  Status-Session

3.5.6  Status-RTM

3.6  FMI Message Summary

Chapter 4	FMI: Message Formats

Chapter 5	FMI: Status, Error, and Sense Codes

Chapter 6	Configuration Information

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix


3270 Emulator Interface Spacification Contents
Microsoft SNA Server

3270 Emulator Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

Chapter 2	The DL-BASE/DMOD Interface

Chapter 3	The Function Management Interface (FMI)

Chapter 4	FMI: Message Formats

4.1  Open(SSCP)

4.1.1  Open(SSCP) Request

4.1.2  Open(SSCP) Response

4.2  Open(PLU)

4.2.1  Open(PLU) Request

4.2.2  Open(PLU) OK Response

4.2.3  Open(PLU) Error Response

4.2.4  Open(PLU) OK Confirm

4.2.5  Open(PLU) Error Confirm

4.3  Close(SSCP)

4.3.1  Close(SSCP) Request

4.3.2  Close(SSCP) Response

4.4  Close(PLU)

4.4.1  Close (PLU) Request

4.4.2  Close(PLU) Response

4.5  Data

4.6  Status-Acknowledge

4.6.1  Status-Acknowledge(Ack)

4.6.2  Status-Acknowledge(Nack-1)

4.6.3  Status-Acknowledge(Nack-2)

4.6.4  Status-Acknowledge(ACKLUA)

4.7  Status-Control

4.7.1  Status-Control(...) Request

4.7.2  Status-Control(..) Acknowledge

4.7.3  Status-Control(..) Negative-Acknowledge-1

4.7.4  Status-Control(..) Negative-Acknowledge-2

4.7.5  Status-Control(..) ACKLUA

4.8  Status-Error

4.9  Status-Resource

4.10  Status-Session

4.11  Status-RTM

Chapter 5	FMI: Status, Error, and Sense Codes

Chapter 6	Configuration Information

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix


3270 Emulator Interface Spacification Contents
Microsoft SNA Server

3270 Emulator Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

Chapter 2	The DL-BASE/DMOD Interface

Chapter 3	The Function Management Interface (FMI)

Chapter 4	FMI: Message Formats

Chapter 5	FMI: Status, Error, and Sense Codes

5.1  Status-Session Codes

5.2  Error and Sense Codes

5.2.1  Error Codes for Open Messages

Open (SSCP) Error Response

Open (PLU) Confirm Error

5.2.2  Error Codes for Nack-2 Messages

5.2.3  Error Codes for Status-Error Messages

5.2.4  Sense Codes for System Detected Error Indicator(SDI) Messages

Chapter 6	Configuration Information

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix


3270 Emulator Interface Spacification Contents
Microsoft SNA Server

3270 Emulator Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

Chapter 2	The DL-BASE/DMOD Interface

Chapter 3	The Function Management Interface (FMI)

Chapter 4	FMI: Message Formats

Chapter 5	FMI: Status, Error, and Sense Codes

Chapter 6	Configuration Information

6.1  Accessing the Configuration File

6.2  Formats of Configuration Records

6.2.1  3270 User Records

6.2.2  Diagnostics Record

6.2.3  Creating Specific NetView User Alerts

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix


3270 Emulator Interface Spacification Contents
Microsoft SNA Server

3270 Emulator Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

Chapter 2	The DL-BASE/DMOD Interface

Chapter 3	The Function Management Interface (FMI)

Chapter 4	FMI: Message Formats

Chapter 5	FMI: Status, Error, and Sense Codes

Chapter 6	Configuration Information

Chapter 7	Diagnostics

7.1  Error and Audit Log Messages

7.1.1  Options for Logging

7.1.2  SNA Server DMOD Logging Macros

Message Severities

Logging Macros

Examples

7.1.3  LOG_MESSAGE Common Service Verb

7.2  Internal Tracing

7.2.1  Internal Tracing Macros

COM_ENTRY

TRACEn

7.2.2  Controlling Internal Tracing

7.3  HLLAPI Parameter Tracing

7.4  FMI Tracing

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix


3270 Emulator Interface Spacification Contents
Microsoft SNA Server

3270 Emulator Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

Chapter 2	The DL-BASE/DMOD Interface

Chapter 3	The Function Management Interface (FMI)

Chapter 4	FMI: Message Formats

Chapter 5	FMI: Status, Error, and Sense Codes

Chapter 6	Configuration Information

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

8.1  SNA Server Client Files

8.2  Included Files

8.3  Compiler Options

8.4  Linking

Appendix A	Appendix


3270 Emulator Interface Spacification Contents
Microsoft SNA Server

3270 Emulator Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

Chapter 2	The DL-BASE/DMOD Interface

Chapter 3	The Function Management Interface (FMI)

Chapter 4	FMI: Message Formats

Chapter 5	FMI: Status, Error, and Sense Codes

Chapter 6	Configuration Information

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix

FMI Extensions for the Windows Environment

GetFmiReturnCode( )


Before You Begin
1 of 4

Before You Begin

This manual is intended for independent software vendors who are developing their own 3270 emulation client software to work with Microsoft SNA Server. It provides the following information:

Internal concepts of SNA Server that are required to integrate 3270 client software

Definitions of the interfaces used by the client software to communicate with  SNA Server components

Information on using SNA Server's configuration and diagnostics features

Instructions for compiling and linking the client software with the necessary SNA Server supplied files

Before using this manual, you should be familiar with SNA Server concepts.


About This Manual
Before You Begin	2 of 4

About This Manual

This manual contains the following chapters:

Chapter 1, "Introduction"

Introduces the key concepts used in SNA Server that you need to consider when integrating client software.

Chapter 2, "The DL-BASE/DMOD Interface"

Describes the interface that client programs use to communicate with the DL-BASE and explains the entry points available for use by clients.

Chapter 3, "The Function Management Interface"

Explains the messages and message sequences used for communications between the client and the local 2.1 node — the Function Management Interface (FMI).

Chapter 4, "FMI: Message Formats"

Provides detailed information on the format of each of the messages covered in Chapter 3.

Chapter 5, "FMI: Status, Error, and Sense Codes"

Provides reference information on status and sense codes that are used in various FMI messages.

Chapter 6, "Configuration Information"

Describes the mechanism used by clients to gain access to SNA Server configuration information and how to interpret and use this information.

Chapter 7, "Diagnostics"

Describes the interfaces to the SNA Server message logging and tracing facilities and explains how client processes can use them.

Chapter 8, "Compiling and Linking with SNA Server"

Explains how to include the required SNA Server header files and libraries when compiling and linking your client application and provides information on compiler flags to be used.

Appendix

Describes the FMI extension for the Windows environment. This extension converts link status and error codes to a printable string.


Operating Systems
Before You Begin	3 of 4

Operating Systems

This manual contains information relating to all of the four operating systems: OS/2 [image], Windows [image] version 3.x, MS-DOS [image], and Windows NT [image]. At present, SNA Server only supports the development of client applications for OS/2, Windows 3.x, and Windows NT. The MS-DOS interface is described here for completeness, but MS-DOS client application development is not supported. Under Windows NT, support for client applications is provided only for the Win32 [image] subsystem.

Where there are differences in this information for the different operating systems, they are indicated as follows.

An icon such as those shown below, indicating one or two of the supported operating systems, indicates that the text that follows it is applicable only to the operating system or systems indicated.

Indicates the OS/2 operating system

Indicates the 16bit Windows environment provided by Windows version 3.x; does not include the 16bit Windows subsystem of the Windows NT operating system.

Indicates MS-DOS

Indicates the Win32 subsystem of the Windows NT operating system

The end of the text to which this applies is indicated either by another icon indicating a different operating system or systems, as shown below:

or by an empty icon as shown below:

Text following an empty icon applies to all operating systems.


Network Operating Systems
Before You Begin	4 of 4

Network Operating Systems

The network operating systems (NOS) supported by SNA Server version 2.1 are Microsoft LAN Manager, IBM [image] Lan Server, Novell [image] NetWare [image], native TCP/IP, and Banyan [image] VINES [image].


Introduction
Chapter 1	1 of 16

Introduction

This chapter describes some key concepts used in SNA Server. Since the purpose of this document is to enable independent software vendors to integrate their 3270 emulators with an SNA Server system, only the relevant parts of the SNA Server architecture are described.


1.1  Structure of SNA Server Components
Introduction	2 of 16

1.1  Structure of SNA Server Components

The components of SNA Server are local nodes, link services, the 3270 emulation program, and so on. This section introduces the structure of these components and explains terms used to refer to this structure.


1.1.1  The Role of the BASE
Introduction	3 of 16

1.1  Structure of SNA Server Components

1.1.1  The Role of the BASE

The BASE is a part of each SNA Server component, such as the local 2.1 node or a link service, that provides the operating environment for the core functions of that component. It passes messages between components and provides functions common to all components, such as diagnostic tracing.

This document is concerned with the DL-Base, which is the type of base used by SNA Server 3270 emulation programs. The SNA Server DL-Base supports a single SNA Server component or a single User Application and has entry points for initialization, sending messages, receiving messages, and termination.


1.1.2  Localities and DMODs
Introduction	4 of 16

1.1  Structure of SNA Server Components

1.1.2  Localities and DMODs

A BASE and the components within it (that is, a SNA Server executable program) is called a Locality. The SNA Server system therefore consists of one or more communicating localities (all the running SNA Server executable programs within the LAN Manager domain). For each SNA Server system, there is a single configuration file.

In a system such as SNA Server, where the number of localities and their types are not configured in advance, the relationships between the localities are set up dynamically as individual localities come and go. Localities that can enter and leave a system in this way are called Dynamic Localities.

Dynamic Localities communicate using the DMOD (Dynamic Access Module) component, which provides the communications facilities needed to pass messages between the BASEs. This is illustrated in Figure 1.1.

Figure 1.1.    Dynamic localities.

This diagram shows a system consisting of three Dynamic Localities. Dynamic Localities can enter/leave this system at any time.

The DMOD is implemented as a Dynamic Link Library (DLL). The above diagram can therefore be represented as shown in Figure 1.2.

Figure 1.2.    .EXE and .DLL structure.


1.1.3  Application Localities
Introduction	5 of 16

1.1  Structure of SNA Server Components

1.1.3  Application Localities

Applications, such as 3270 emulators, may enter dynamically into an SNA Server system. The application, in conjunction with the Base, acts as a whole locality and communicates with the other localities in the system using a DMOD.

Chapter 2 of this document describes the interface to the BASE and the DMOD that allows an Application to participate in an SNA Server system.


1.1.4  Partners
Introduction	6 of 16

1.1  Structure of SNA Server Components

1.1.4  Partners

In order for SNA Server components and applications to communicate with each other, it must be possible to identify a Partner within a locality. The term Partner refers to an addressable component of a locality — that is, code to which messages can be sent. In an SNA Server system, there is generally only one partner within a locality (such as a link service or the 3270 emulation program); however, separate functions within the local 2.1 node (such as the 3270 and APPC functions) may be considered to be separate partners.


1.2  Messages
Introduction	7 of 16

1.2  Messages

Messages are used to pass data between Partners in the SNA Server system.


1.2.1  Overview of Message Formats
Introduction	8 of 16

1.2  Messages

1.2.1  Overview of Message Formats

A Message always contains fixed-format header information such as a message type and addressing information. It may also contain other header information specific to a particular message type (such as the message subtype) and/or an indefinite amount of extra data.

Messages are saved in Buffers. These buffers consist of one Header and zero or more Elements:

Header	This contains the fixed format information and a pointer to an element. (This pointer will be NULL if there are no elements associated with the message.)

Element	This contains any extra data for a message and a pointer to another element (if there is insufficient room in this element for all the data).

Buffer headers and elements are regarded as contiguous (8-bit) byte sequences.

Messages of any length can be built up by chaining sufficient elements to a header.

Figure 1.3 illustrates a typical message with two elements. The individual fields in the header and elements are explained in the following sections.

Figure 1.3.    Typical message format.

The following sections provide more information on the format of buffer headers and elements.


1.2.2  Buffer Header Format
Introduction	9 of 16

1.2  Messages

1.2.2  Buffer Header Format

This section lists the common fields that always occur at the start of a buffer header. These will be followed by further fields specific to the particular message; see Chapter 4 for details of individual message formats.

Field	Type	Description
nxtqptr	PTRBFHDR	When the buffer is in a queue, this field points to the header of the next buffer in the queue (NULL if it is the last buffer in the queue). When the buffer is not in a queue, this field points to itself; the SNA Server buffer management routines use this to check for buffer corruption.
hdreptr	PTRBFELT	Pointer to the first buffer element in the associated chain of buffer elements; NULL if the message consists only of a buffer header.
numelts	CHAR	Number of buffer elements chained from the header; zero if the message consists only of a buffer header.
msgtype	CHAR	Message type: see individual message descriptions in Chapter 4.
srcl	CHAR	Source Locality: see LPI Addresses in the following section.
srcp	CHAR	Source Partner: see LPI Addresses in the following section.
srci	INTEGER	Source Index: see LPI Addresses in the following section.
destl	CHAR	Destination Locality: see LPI Addresses in the following section.
destp	CHAR	Destination Partner: see LPI Addresses in the following section.
desti	INTEGER	Destination Index: see LPI Addresses in the following section.
Note that fields that occupy two bytes — such as opresid in Open(PLU) Request (see section 4.2) — are normally represented with the arithmetically most significant byte in the lowest byte address, irrespective of the normal orientation used by the processor on which the software executes. That is, the 2-byte value X'1234' has the byte X'12' in the lowest byte address. However, the following fields are exceptions:

srci and desti in buffer headers are stored in the local format of the application which assigns them (only the assigning application needs to interpret these values)

startd and endd fields in elements are always stored in lowbyte, highbyte orientation (the normal orientation of an Intel processor)


1.2.3  Buffer Element Format
Introduction	10 of 16

1.2  Messages

1.2.3  Buffer Element Format

This section lists the common fields that always occur at the start of a buffer element. The DATARU field contains information specific to the particular message; see Chapter 4 for details of individual message formats.

Field	Type	Description
hdreptr->elteptr	PTRBFELT	Pointer to next buffer element in the chain; NULL if this element is the last or only element in the chain.
hdreptr->startd	INTEGER	Start of valid data in this element. The index into DATARU of the first byte of valid data.
hdreptr->endd	INTEGER	End of valid data in this element. The index into DATARU of the last byte of valid data.
hdreptr->trpad	CHAR	Pad byte (reserved).
hdreptr->dataru	CHAR[268]	An array of characters that contains the data for this element. Note that the valid data may not occupy the whole of the element; startd and endd (see above) give the indexes into this array of the start and end of the valid data.
The following information will help you to interpret the message formats:

Certain messages are shown as having two elements in the message formats; for example, the Open(PLU) Request has the CICB field in the first element, and the BIND RU in the second element. This indicates that the message consists of two distinct linked element chains; the elteptr field in the first element points to the second element.

Fields that occupy two bytes are represented with the arithmetically most significant byte in the lowest byte address, irrespective of the normal orientation used by the processor on which the software executes. That is, the 2-byte value X'1234' has the byte X'12' in the lowest byte address. The exceptions to this are the startd and endd fields in elements, which are always stored in low-byte, high-byte orientation (the normal orientation of an Intel processor).

The offsets indicated by the startd and endd fields are expressed in terms of the first byte of dataru being offset 1; the first byte of valid data is at dataru[startd-1]. For example, if startd is 11 and endd is 18, then dataru begins with 10 bytes that are not valid data, followed by 8 bytes of valid data.

It is possible for an element to arrive with startd greater than endd. This indicates there is no valid data in DATARU.

In the example message format illustrated in Figure 1.3, each element has a startd of 13, indicating 12 bytes of padding before the start of the valid data. This leaves room for 256 bytes of data, and hence the element data (300 bytes long in this example) requires 2 elements.


1.3  LPI Connections
Introduction	11 of 16

1.3  LPI Connections

As explained earlier, partners communicate by passing messages to each other. If two partners wish to communicate with each other, an LPI Connection is set up between two partners. Messages then flow between the partners over this connection. The term "LPI connection" is explained in section 1.3.2; note that this is not related to the SNA Server concept of a connection between the local node and a remote system.


1.3.1  Paths and DMODs
Introduction	12 of 16

1.3  LPI Connections

1.3.1  Paths and DMODs

As already stated, DMODs are responsible for the communication between localities. When the DMODs in two localities can successfully pass messages between them, a Path is said to exist between the two localities. A path must exist between two localities before a connection can exist between partners in those localities.

SNA Server establishes a path using an appropriate method for the network operating system in use. For example, with LAN Manager, a named pipe is used; with NetWare, an SPX connection is used. When the two localities are on the same PC, a "local pipe" is used; this is implemented using shared buffers to increase performance, but is used by the application in exactly the same way as communication with a remote locality.

The DMOD provides communication between dynamic localities and provides guaranteed in-order delivery of messages flowing over paths between localities. If the DMOD loses its path to another locality, it informs the Base.

Figure 1.4 illustrates the paths and connections between an SNA Server local node and two 3270 emulation programs. 3270 "A" has two connections to the local node (one for each of two sessions); 3270 "B" has one connection to the local node.

Figure 1.4.    Paths, DMODs, and connections.


1.3.2  LPI Addresses
Introduction	13 of 16

1.3  LPI Connections

1.3.2  LPI Addresses

An LPI address is used to identify each end of a connection. It has three components, L, P and I.

Locality	A 1-byte identifier that uniquely identifies a locality within a system (from the viewpoint of a particular locality). This corresponds to an SNA Server component (local node, link service, 3270 emulator, and so on).

Partner	A 1-byte identifier that uniquely identifies a partner within the locality. This is not always used, but can be used to distinguish between parts of a component (for example, the 3270 functions in the local node rather than the APPC functions).

Index	A 2-byte identifier that uniquely identifies a logical entity within the partner. The meaning and use of this field is defined by the communicating partners; it is used to distinguish multiple connections between the same partners (for example, to identify one of many 3270 sessions between the local node and a particular 3270 emulator). The value of 0 should not be used as an I value. Applications must assign unique I values for every active LPI connection with the node.

A Message flowing over a connection carries a pair of LPIs, identifying the source and destination of the message. These are the Source LPI and Destination LPI of the message — together they identify the connection on which the message is flowing.

Note that more than one connection may exist between any pair of partners. The I values are then used to distinguish the connections. For example, in communications between the local node and a 3270 emulator, the L and P values identify the message as being 3270 data for that local node, and the I value indicates which session the data is intended for.

The LPIs are assigned by a combination of the partners and the DMODs when the connection is opened, as described in Section 1.3.3.

Because they are assigned dynamically for each component, the L values are not the same across a whole system. For example, a local 2.1 node locality could be known as Locality 4 to one 3270 locality, and Locality 6 to a second 3270 locality. However, from the viewpoint of any locality, there exists a unique L value for each remote locality within which a path exists; this L value is used as an index into an internal table that identifies the path to that locality.

Figure 1.5 shows an example of the L values that could be used between the components shown in Figure 1.4. Figures 1.6 and 1.7 show examples of the LPI values that would be used by the local node on messages flowing between the components. (See Figure 3.3.2 in Chapter 3 of this manual for more information on how the LPI values are assigned and used.)

Figure 1.5.    Example L values.

Figure 1.6.    L values specified on messages between the local node and 3270 "A."

Figure 1.7.    LPI values specified on messages flowing on two different connections between the local node and 3270 "A."

The BASE is called by any piece of code that wishes to send a message. It uses the Destination L value on the message to work out where to send it. When the message gets to the remote locality, the BASE in that locality routes it to the appropriate partner (if the locality contains more than one partner).


1.3.3  Making Connections
Introduction	14 of 16

1.3  LPI Connections

1.3.3  Making Connections

Before messages can flow across connections, the connection must be established, or "opened." This is necessary since a partner (P1) does not initially know the LPI address of the partner with which it wishes to communicate; indeed, there may not even be a suitable partner for it to communicate with.

A component of the BASE, known as the Resource Locator, and a message with type of Open, known as an Open Message, are used to establish a connection between partners.

The following is an outline of how a connection is established. For more information on opening the connection for a specific session, see the appropriate sections in Chapter 3.

The Open message has two forms; an Open(Request) and an Open(Response). The Open(Request) contains information on the type of partner P1 is looking for.

P1 fills in an Open(Request) and calls the BASE with it. Since it does not know the LPI address of its partner, it sets the destination LPI values to zero.

The BASE cannot forward the Open to a particular partner, since it has no Destination LPI address yet. Hence, it passes the Open to the Resource Locator, which attempts to find a locality that will accept the Open. The DMOD has a record of all the localities that could accept this type of Open. The Resource Locator tries each of these localities until the Open is accepted. If no locality is found, the Resource Locator gives up and tells the sender that no partner could be found (by returning a "Negative Response" to the Open).

When a remote locality receives an Open, the BASE passes it to the partner (P2). If P2 can accept the Open, it responds by sending back a Positive Open(Response) message to P1.

The Open(Response) message returned to P1 contains both the source and destination LPI values for the particular connection. At the end of this exchange, therefore, both P1 and P2 know each other's addresses, and can communicate over the connection.

Note that the terms Source and Destination in the context of LPIs refer to the source and destination of the particular message. Hence, when the 3270 emulator builds a message to send to the local 2.1 node, it needs to swap the Source and Destination LPIs received on the Open Response from the local 2.1 node.

For a detailed example of how LPI addresses are assigned during initialization of the SSCP and PLU sessions, see Figure 3.3.2 in The PLU Connection(section 3.3.).


1.4  How DMODs Communicate
Introduction	15 of 16

1.4  How DMODs Communicate

Each locality has a DMOD that handles communication with other localities. It performs the following functions:

passing messages to DMODs in other localities

detecting/reporting lost localities

finding server localities

dynamically loading other localities

Communication is possible between different localities running on the same PC, as well as between localities on different PCs. There is one named pipe for every path that is open to another locality.

Figure 1.8 shows three localities, each with its own DMOD, distributed over two LAN connected PCs. All the localities can communicate with each other via their DMODs. Locality A communicates with Locality B via a "local named pipe," as described in this section. Locality A communicates with Locality C using a pipe across the LAN.

The Network Access Process (NAP) performs the following functions:

Distributes details of the services available on its PC to the other PCs.

Maintains details of all the server localities in the Network, for use by the DMOD in resource location.

Handles dynamic load requests to load localities on its PC.

Locates the configuration file.

The NAP is present at all times on PCs that wish to participate in the SNA Server network, regardless of whether any localities are currently running. It is also necessary on all PCs where dynamic loading is to be performed.

Figure 1.8.    How DMODs communicate.


1.5  Internal Data Structures
Introduction	16 of 16

1.5  Internal Data Structures

Two tables are required to support the DMOD function. The Service Table is in shared memory, since it is common for all DMODs and the Network Access Process. The L-table is specific to each DMOD and is held in the DMOD's private data segment. Below is a brief description of the use of each table. Figure 1.9 shows the tables in use.

SERVICE TABLE: This lists all known server localities on the Network that can be resource located.

L TABLE: Maps the L values known to a BASE to the pipe handle for a specific locality on the network.

Figure 1.9.    Main DMOD data structures.


The DL-BASE/DMOD Interface
Chapter 2	1 of 14

The DL-BASE/DMOD Interface

This chapter describes the interface to the SNA Server DL-BASE. It includes a listing of the entry points that an application, such as a 3270 emulator, can call. These entry points allow messages to be sent to and received from Services such as the local 2.1 node.


2.1  Introduction
The DL-BASE/DMOD Interface	2 of 14

2.1  Introduction

In the following description, we will assume that a 3270 emulator is to be adapted to use SNA Server. It needs to communicate with the local 2.1 node.


2.1.1  Initialization
The DL-BASE/DMOD Interface	3 of 14

2.1  Introduction

2.1.1  Initialization

The 3270 emulator should initialize the DL-Base and then call the DMOD to obtain the necessary configuration information (this also registers the user name with the DMOD). It may then obtain further system information such as the SNA Server version number, if required.

The routines involved are:

SBPUINIT	Initialize the DL-BASE

SEPDCREC	Get configuration information

SEPDGETINFO	Get system information

SBPUINIT should always be called before any other DL-BASE/DMOD entry points except SNAGetVersion. For new emulators, SEPDCREC should be called after SBPUINIT. (Because of the order of calls used in older emulators, a call to SEPDCREC before SBPUINIT is still supported, but this order is not recommended.)


2.1.2  Sending Messages
The DL-BASE/DMOD Interface	4 of 14

2.1  Introduction

2.1.2  Sending Messages

The 3270 emulator should insert the message in a buffer and then call the DL-BASE to send it. The message contains Source and Destination LPIs, which are set up when the connection is opened; see section 1.3 for more information.

The application may either obtain a new buffer to contain the message to be sent (using SEPDBUBL), or reuse one in which it has previously received a message. The application is responsible for any buffer it has obtained, or in which it has received a message; it must either use (or reuse) the buffer to send a message, or release it (using SEPDBURL). If the buffer to be reused does not contain the correct number of elements for the message to be sent, the application may obtain additional elements (using SBPIBEGT) or release existing ones (using SBPIBERL); in this case, it must also ensure that the numelts field in the buffer header indicates the correct number of elements.

The routine used to send the message is SBPUSEND.


2.1.3  Receiving Messages
The DL-BASE/DMOD Interface	5 of 14

2.1  Introduction

2.1.3  Receiving Messages

The method for receiving messages from the DMOD is illustrated in Figure 2.1.1.

Figure 2.1.1    Receiving messages using a routing procedure.

After DMOD Initialization, the 3270 emulator registers the routing procedure by calling SEPDROUT. When the DMOD receives a message, it calls the 3270 emulator routing procedure, which can then process the message.

With this approach, there is no context switch between the DMOD thread and the 3270 emulator thread. However, the routing procedure must return control to the DMOD fairly quickly. For instance, it cannot suspend waiting for a keyboard input.

The application must determine whether the received message is for this application or for another application; if the message is not for this application, the routing procedure must return, indicating that the message was not processed. If the application processes the message, it is responsible for freeing the buffer when it has finished processing the message.

In some cases, the routing procedure may be able to process the message to completion. An alternative is for the routing procedure to put the message on an application queue and then clear an application semaphore. The application can then subsequently process the message.

A further performance gain may be achieved by sending a Status-Resource message (to return credit to the local node, allowing it to send further data) from the routing procedure when a message is received, rather than waiting until the message is processed to completion. The example source code in section 2.4.1 illustrates this usage. See section 3.3.9 for more information on credit and flow control.

If an application wishes to schedule its main (noncallback) part on receipt of a message, it may do so by posting a Windows message to its WndProc.

Note that, once the application has received a message, it is responsible for the buffer in which the message was received; it must either reuse the buffer to send a message (using SBPUSEND) or release it (using SEPDBURL). If the buffer to be reused does not contain the correct number of elements for the message to be sent, the application may obtain additional elements (using SBPIBEGT) or release existing ones (using SBPIBERL); in this case, it must also ensure that the numelts field in the buffer header indicates the correct number of elements.


2.1.4  Opening a Connection
The DL-BASE/DMOD Interface	6 of 14

2.1  Introduction

2.1.4  Opening a Connection

Before an LPI connection can be used to transfer data, it needs to be opened. This is performed by sending Open messages, starting with an Open Request. The format of the Open messages is defined by the interface being used. For example, the 3270 emulator uses the Function Management Interface (FMI) to communicate with the local 2.1 node.

The interface also defines the initiator of the Open Request. In this case, the 3270 emulator sends the Open (SSCP) Request, and the local 2.1 node sends the Open (PLU) Request.

On the Open (SSCP) Request, the 3270 emulator sets all the Source and Destination LPIs to zero, apart from the Source Index, which can be used by the 3270 emulator for internal routing (for example, to distinguish between two sessions).

The DL-BASE and DMOD ensure that Opens are routed to a suitable destination. If a routing procedure is used, it should always first call SBPURCVX to process Open Responses; when SBPURCVX indicates that it has not processed a received message, and the received message is Open Response(OK), the application is informed that the connection was established successfully. For an example of this, see the sample code in section 2.4.1 of this chapter.


2.1.5  Termination
The DL-BASE/DMOD Interface	7 of 14

2.1  Introduction

2.1.5  Termination

The 3270 emulator must call SBPUTERM to free DL-BASE/DMOD resources before it terminates.


2.2  MS-DOS – based 3270 Emulation
The DL-BASE/DMOD Interface	8 of 14

2.2  MS-DOS – based 3270 Emulation

This section describes important information for emulator vendors who are writing for the MS-DOS operating system.

For simple emulators which will run as the sole application in a system, much of the following information is unnecessary — the only consideration for vendors of this type of emulator is support for task switching (described in section 2.2.1 below). However, for emulators which will support background operation it is vital that the facilities provided by the DMOD are used to ensure this functions correctly.

2.2.1  DOS 5 / Windows Task Switching

The DOS 5 and Windows operating systems both provide support for task switching MS-DOS applications. This is a facility which allows the user to switch between multiple applications running on the machine. When an application is not the currently running foreground task, it may be swapped out of memory onto disk by the operating system.

Due to the asynchronous nature of the DL-BASE interface, it is important that this task switching operation is detected. If the user task switches from an emulator running in the foreground to another application, and the emulator is removed from memory, it is important that the DL-BASE does not attempt to call the emulator's routing procedure with any received messages.

Task switching support is handled by the DMOD, and need not concern the 3270 emulator writer. However, the DMOD provides a means for the application to make use of the task switch detection. The emulator may call REGISTERSWITCHPROC to register a procedure which will be called whenever an application is being switched out or back in.

If the emulator changes the screen mode (e.g., to support model 5 emulation), the task switch notification mechanism must be used to restore the screen mode to its default whenever the application is being switched out. This is due to a problem in the MS-Windows task switching code — Windows does not restore the screen mode before attempting to redraw the screen.

2.2.2  Client Environment for MS-DOS – Based Emulators

The MS-DOS – based client NAP provides full support for applications which allow switching between foreground and background operation (i.e., TSR applications), including fully pre-emptive scheduling of a background thread.

To avoid possible interaction problems, it is important that client applications which intend supporting background operation make use of the facilities provided by the NAP, rather than implementing separate scheduling mechanisms hooked from MS-DOS interrupts.

Background operation

During its initialization sequence, the emulator should hook the keyboard interrupt to allow it to scan for the hotkey sequence which it uses to switch between foreground and background operation.

When the emulator has completed its initialization and wishes to go resident, it must call CMDGoTSR passing the address of a procedure which is used to start a background thread of execution. The call executes an MS-DOS Terminate and Stay-Resident (TSR) call to force the emulator to be resident, and will never return control to the emulator.

The background thread may be used to perform any items of work which are required (such as processing messages received from the local node, initiating a file transfer, etc.), but the emulator must not write any output to the screen whilst in background mode.

When the emulator detects a hotkey sequence which command it to return to the foreground, it must first call CMDStopFG to suspend the current foreground thread, and gain control of the screen area. If this call returns a non-zero value, the foreground thread has been stopped within MS-DOS. The emulator must not switch into the foreground, and should restart the foreground thread.

An example of a typical scheduling loop is given in section 2.3.2.

Scheduler

The scheduler provided by the NAP component takes complete control of scheduling all applications running in the system. It is fully pre-emptive, and allows several processes to run concurrently. Only the current foreground process is permitted to write to the screen.

The entry point provided by the 3270 emulator on the CMDGoTSR call is executed as a fully independent background thread of execution. Scheduling between the foreground application's thread and the emulator background thread occurs in response to:

MS-DOS interrupts

Timer ticks

API calls which affect semaphores

Semaphores

In any pre-emptively scheduled environment, the use of semaphores is vital to protect data structures which may be accessed by more than one thread of execution. The standard semaphore functions (Set, Clear, Wait, Request) are provided as DMOD entry points.

For example, if the emulator uses the "routing procedure" method of receiving messages, the routing procedure will be called from a different thread context to the main application thread. This may require the use of semaphore protection around emulator data structures.


2.3  DL-BASE/DMOD Entry Points
The DL-BASE/DMOD Interface	9 of 14

2.3  DL-BASE/DMOD Entry Points

This section gives definitions for the entry points to the DL-BASE and DMOD. They are divided into the categories DL-BASE, DMOD, and Buffer Management and are listed in alphabetical order within each category.

In summary the entry points are:

DL-BASE

SBPUINIT	Initialize the DL-BASE

SBPURCVX	Process Opens from routing procedure

SBPUSEND	Send message

SBPUTERM	Terminate

DMOD

(ROUTPROC	Sample routing procedure)

SEPDCHNK	Get FMI chunk size

SEPDCREC	Get user and diagnostics records from configuration file

SEPDGETINFO	Get SNA Server system information

SEPDROUT	Set up routing procedure (OS/2, WIN32, and DOS only)

SEPWROUT	Set up routing procedure (WIN16 only)

REGISTERSWITCHPROC	Register a task-switch detection procedure

CMDGoTSR	Start background thread and go resident

CMDStopFG	Suspend current foreground process

CMDStartFG	Resume scheduling of current foreground process

CMDSemClear

CMDSemSet	Standard semaphore functions for DOS environment

CMDSemWait

CMDSemRequest

Buffer Management

SBPIBEGT	Get buffer element

SBPIBERL	Release buffer element

SEPDBUBL	Get buffer

SEPDBURL	Release buffer

Note

The PASCAL calling convention is used for all entry points including routing procedures, with the exception of WIN32, where the standard-call convention is used.

The format of buffer headers and elements is described in Section 1.2.1; the formats of individual messages contained in buffers are defined in Chapter 4.


2.3.1  DL-BASE Entry Points
The DL-BASE/DMOD Interface	10 of 14

2.3  DL-BASE/DMOD Entry Points

2.3.1  DL-BASE Entry Points

SBPUINIT — Initialize the DL-Base

The application calls this routine to initialize the DL-Base.

C Declaration

USHORT FAR sbpuinit(sema4ptr, proctype, servtype)

HSEM FAR * sema4ptr;

USHORT proctype;

USHORT servtype;

USHORT FAR sbpuinit(sema4ptr, proctype, servtype, uname)

HSEM FAR * sema4ptr;

USHORT proctype;

USHORT servtype;

UCHAR * uname;

USHORT sbpuinit(sema4ptr, proctype, servtype, uname)

HANDLE * sema4ptr;

USHORT proctype;

USHORT servtype;

UCHAR * uname;

USHORT FAR sbpuinit(proctype, servtype, uname)

USHORT proctype;

USHORT servtype;

UCHAR FAR * uname;

Function Return Value

NO_ERROR	initialization successful

Any other return value indicates that the initialization failed. In general this will be an operating system return code. The following values are also used:

DMLTABF	(555)	L-Table is full
DMMNWGI	(562)	Failed to get network operating system information
DMDSTFL	(563)	Service Table is full
DMMPIPF	(567)	Failed to make a named pipe
DMCOMNM	(582)	No name registered for this application
DMCOMDUP	(596)	A service is already running with the same name
DMNOTLOG	(598)	User is not logged on to network operating system
DMCFGOPN	(616)	Failed to open configuration file
DMCFGREAD	(618)	Failed to read from configuration file
DMNONAP	(625)	The NAP is not started
DMMAXAPP	(953)	Windows only:Maximum number of concurrent applications exceeded
Parameter	Description
sema4ptr	Semaphore, created by DMOD, cleared by DMOD when a message is available.For DOS, the application should supply the address of a 4-byte (long) integer. This is for SNA Server internal use — the application should not subsequently attempt to reference the address.
proctype	Type of process:	CLIENT	2
servtype	Type of service/client:	CES3270	2
uname	Pointer to a character buffer of length at least 21 characters; the LAN Manager user name, or other identifying name appropriate to the network operating system, is returned to the application in this buffer. The application does not need to use this parameter, but may use it for display or logging.
Usage Notes

SBPUINIT should always be called before any other DL-BASE/DMOD entry points except SNAGetVersion. For new emulators, SEPDCREC should be called after SBPUINIT. (Because of the order of calls used in older emulators, a call to SEPDCREC before SBPUINIT is still supported, but this order is not recommended.)

SBPURCVX — Process Open Responses from Routing Procedure

An application can define a routing procedure that is called by the DMOD when a message is received. This procedure should first call sbpurcvx to handle any Open response messages received; this ensures that Open responses intended for the Resource Locator are handled correctly.

C Declaration

USHORT FAR sbpurcvx (msgptr, locl, retstat)

BUFHDR FAR * FAR * msgptr;

INTEGER locl;

INTEGER retstat;

USHORT sbpurcvx (msgptr, locl, retstat)

BUFHDR * * msgptr;

INTEGER locl;

INTEGER retstat;

FunctionReturn Value	Description
TRUE	The Resource Locator has accepted the message; the application should not process it any further
FALSE	The message should be processed by the application
msgptr	Pointer to the message returned by the DMOD to the routing procedure
locl	Locality from which message was received (if retstat indicates message received), or locality to which path was lost (if retstat indicates path error)
retstat	Reason for call
	CEDINMSG	1	message returned
	CEDINLLN	2	path error
Usage Notes

This routine is called by a routing procedure that is called by the DMOD; it is not called directly by the application.

The parameters for sbpurcvx should be taken from the parameters for the routing procedure — see the sample routing procedure ROUTPROC in section 2.4.1. Note, however, that the first parameter to sbpurcvx is a pointer to a pointer to a buffer header (that is, a pointer to the corresponding parameter for the routing procedure, not the parameter itself).

SBPUSEND — Send Message

This routine sends a message from an application to a partner on an LPI connection.

C Declaration

VOID FAR sbpusend (msgptr)

PTRBFHDR msgptr;

VOID sbpusend (msgptr)

PTRBFHDR msgptr;

Parameter	Description

msgptr	Pointer to the message to be sent

Usage Notes

The message buffer is released after transmission by the DMOD. It cannot be accessed by the application again.

For an Open Request message, the DESTL parameter may be zero. In this case, the Resource Locator will attempt to find a suitable destination for the Open message.

SBPUTERM — Terminate

This routine must be called when the application terminates. It frees the DL-BASE / DMOD resources used by the application.

For Win32, do not call SBPUTERM from an entry point in a detached DLL process because it may cause a deadlock inside the SNADMOD.DLL.

C Declaration

VOID FAR sbputerm(VOID)

VOID sbputerm(VOID)


2.3.2  DMOD Entry Points
The DL-BASE/DMOD Interface	11 of 14

2.3  DL-BASE/DMOD Entry Points

2.3.2  DMOD Entry Points

ROUTPROC — Sample Routing Procedure

This routine must be supplied as part of the application. It is called by the DMOD with a message, which may or may not be for this application; the DMOD calls routing procedures in turn until one accepts the message.

C Declaration

USHORT FAR _loadds routproc(msgptr, locl, retstat)

BUFHDR FAR * msgptr;

USHORT locl;

USHORT retstat;

DWORD routproc(msgptr, locl, retstat)

BUFHDR * msgptr;

USHORT locl;

USHORT retstat;

FunctionReturn Value	Description

TRUE	The routing procedure has accepted the message

FALSE	The message is not for this routing procedure

Parameter	Description
msgptr	Pointer to the message passed by the DMOD to the routing procedure
locl	Locality from which message was received (if retstat indicates message received), or locality to which path was lost (if retstat indicates path error)
retstat	Reason for call:
	CEDINMSG	1	message returned
	CEDINLLN	2	path error (see Usage Notes below)
Usage Notes

The routing procedure should first call sbpurcvx, which handles any Open response messages, as follows:

sbpurcvx(&msgptr, locl, retstat)

A return code of TRUE from sbpurcvx indicates that sbpurcvx has accepted the message; an Open error response has been received for this application, and resource location is continuing. The routing procedure should not process the message any further and should return TRUE to prevent the DMOD from calling further routing procedures.

A return code of FALSE from sbpurcvx indicates that the routing procedure should:

If the message is for this application, take responsibility for the message and return TRUE to prevent the DMOD from calling further routing procedures

If the message is not for this application, return FALSE in order that the DMOD tries further routing procedures

If a path error is returned, msgptr will not point to a valid message, and no more FMI messages will be returned for the locality value indicated. The application is responsible for ending all sessions using this locality. The routing procedure must return FALSE; this ensures that the lost locality is reported to all other routing procedures.

If the message is for this application, the routing procedure can either process the message immediately or put the message on an application queue and then post the application using a semaphore — see Section 2.1.3.

SEPDCHNK — Get FMI Chunk Size

The application calls this routine to obtain the chunk size that should be used on the FMI. See section 3.3.9 for more information on FMI chunking; this feature is supported in Comm Server version 1.2 and later and in SNA Server for Windows NT.

C Declaration

VOID FAR sepdchnk (pipesizeptr, chunksizeptr)

USHORT FAR * pipesizeptr;

USHORT FAR * chunksizeptr;

VOID sepdchnk (pipesizeptr, chunksizeptr)

USHORT * pipesizeptr;

USHORT * chunksizeptr;

Parameter	Description

pipesizeptr	Size in bytes of the pipe between the application and the local node

chunksizeptr	DMOD chunk size in bytes

Usage Notes

The application does not need to use the pipe size returned by this call. (It is included on this call because the local node uses the same call to obtain both the pipe size and the chunk size.)

SEPDCREC — Get Configuration Information

The application calls this routine to obtain the 3270 configuration information for the name with which the user logged on to the network operating system. The call also registers this user name in the service table.

C Declaration

USHORT FAR sepdcrec (pBuffer, length, numbytes)

UCHAR FAR	* pBuffer;

USHORT	length;

USHORT FAR	* numbytes;

USHORT sepdcrec (pBuffer, length, numbytes)

UCHAR 	* pBuffer;

USHORT	length;

USHORT	* numbytes;

FunctionReturn Value		Description
NO_ERROR	(0)	OK
NOCSSRVR	(1)	No configuration file server available
NODGNREC	(2)	No diagnostics record found in configuration file
NOUSRREC	(3)	No user record found in configuration file for this user
BUF2SMAL	(4)	Supplied buffer was too small
NONOS	(5)	Network operating system is not started
NOTLOGON	(6)	User is not logged on to the network operating system
READERR	(7)	Failed to read from configuration file
NONAP	(8)	The NAP is not started
MAXAPP	(9)	Windows only: Maximum number of concurrent applications exceeded
Parameter	Description

pbuffer	Pointer to buffer supplied by application, in which configuration information is returned

length	Size of the supplied buffer

numbytes	Used by SNA Server to return the number of bytes of information returned in the buffer

Usage Notes

SBPUINIT should always be called before any other DL-BASE/DMOD entry points except SNAGetVersion. For new emulators, SEPDCREC should be called after SBPUINIT. (Because of the order of calls used in older emulators, a call to SEPDCREC before SBPUINIT is still supported, but this order is not recommended.)

On successful return, the buffer contains pointers to the appropriate 3270 user record and the diagnostics record, followed by the records themselves. It is formatted as follows:

TECWRKUS FAR *	pUserRecord;

TEDIAGNS FAR *	pDiagRecord;

(UserRecord — variable length)

(DiagRecord)

TECWRKUS *	pUserRecord;

TEDIAGNS *	pDiagRecord;

(UserRecord — variable length)

(DiagRecord)

The two records should be accessed using the supplied pointers.

See Chapter 6 for details of the format of these records and of how the application uses the configuration file information.

If there is no 3270 user record for this user in the configuration file, or if no diagnostics record is found in the configuration file (an internal error), the application should terminate and not allow the user to use 3270 emulation. The SNA Server error log messages COM0438 and COM0437 can be used to report these failures.

If the supplied buffer is too small for the returned information, the contents of the buffer are undefined and should not be examined, but the numbytes parameter will contain the total number of bytes of information available (that is, the size of the two pointers plus the two configuration records). The application should retry with a buffer of at least this size.

SEPDGETINFO — Get System Information

C Declaration

USHORT FAR sepdgetinfo (pCSInfo)

struct cs_info FAR * pCSInfo;

USHORT sepdgetinfo (pCSInfo)

struct cs_info * pCSInfo;

struct cs_info		{
unsigned short		length;		/* length of the data structure		*/
				/* supplied by the application		*/
unsigned char		major_ver;		/* major version number		*/
				/* -1 for CS 1.1		*/
				/* -2 for CS 2.0		*/
unsigned char		minor_ver;		/* minor version number (decimal)		*/
				/* - 10 for CS 1.1 (indicates 1.10)		*/
				/* - 00 for CS 2.0 (indicates 2.00)		*/
unsigned char		config_share[80];		/* path of the running configuration file		*/
				/* \\server\share\ (null terminated)		*/
unsigned short		nos;		/* network operating system in use		*/
				/* 1: LAN Manager / LAN Server,		*/
				/* 2: NetWare		*/
		}
FunctionReturn Value		Description
NO_ERROR	(0)	OK
NOCSSRVR	(1)	No configuration file server available
BADLNGTH	(2)	Supplied buffer was too small
Parameter	Description

pCSInfo	Pointer to buffer supplied by application, containing a data structure in which system information is returned. The application must set the length field in this data structure (see note below); the other fields should be set to nulls or blanks.

Usage Notes

SBPUINIT should always be called before any other DL-BASE/DMOD entry points except SNAGetVersion. For new emulators, SEPDCREC should be called after SBPUINIT. (Because of the order of calls used in older emulators, a call to SEPDCREC before SBPUINIT is still supported, but this order is not recommended.)

The application must set the length parameter to the length of the cs_info structure (86 bytes in the current version). Any other value will be rejected. This parameter is used to ensure compatibility with future versions; an application supplying this length will always obtain the information shown here, but in future versions it may be possible to specify larger values and obtain further information.

On successful return, the data structure cs_info contains the version number of SNA Server, the path of the current configuration file, and the network operating system over which SNA Server is running.

Do not use the configuration file path returned by SEPDGETINFO because NetWare clients will not be able to access this path.

If there is no configuration file server available, only the version number fields are valid; the other fields should not be checked.

SEPDROUT — Set Up Routing Procedure

This routine allows an application to perform its own routing of received messages by setting up a procedure that is called by the DMOD when a message is received.

C Declaration

USHORT FAR sepdrout(proc_addr)

USHORT (FAR * FAR proc_addr)();

DWORD sepdrout(proc_addr)

DWORD (* proc_addr)(BUFHDR *, USHORT, USHORT);

FunctionReturn Value		Description
NO_ERROR	0	Successful
anything else		Unsuccessful
Parameter	Description
proc_addr	The routing procedure
Usage Notes

This facility is only available to Clients, as defined in the call to SBPUINIT.

An application can have up to four routing procedures. Note that the APPC and CSV libraries each use a routing procedure. When the DMOD receives a message, each routing procedure is called, until one accepts the message.

A sample routing procedure, ROUTPROC, is included earlier in this section.

SEPWROUT — Set Up Routing Procedure

This routine is the Windows version of SEPDROUT; it has the same parameters and is used in exactly the same way.

CMDGoTSR — Force MS-DOS – based emulator resident

This routine initiates a background thread for the emulator then executes an MS-DOS TSR interrupt.

C Declaration

USHORT  APIENTRY CMDGoTSR(EntryPoint, Stack, TopOfRam)

ULONG EntryPoint;

UCHAR FAR *Stack;

UCHAR FAR *TopOfRam;

Parameter	Description

EntryPoint	Pointer to the function where background thread will start execution.

Stack	Pointer to the stack of the background thread.

TopOfRam	Top of RAM; all memory above this address will be released by the NAP for LAN Manager or the NAP for NetWare (LMBase and NWBase, respectively).

Usage notes

An MS-DOS – based emulator should complete its initialization, then execute this call to go resident. A thread of execution will be created at the entrypoint specified.

This call will never return control to the calling program.

CMDStopFG — Suspend scheduling of foreground task

This routine requests that the foreground thread be suspended.

C Declaration

USHORT FAR CMDStopFG (Timeout)

USHORT Timeout;

Return value	Description

0	The foreground thread was successfully stopped

non-zero	The foreground thread was stopped within MS-DOS

Parameter	Description

Timeout	Maximum time to wait for the foreground thread to return from DOS before stopping it anyway

Usage Notes

The emulator should issue this call when it wishes to enter the foreground. If the return value is non zero, the foreground thread has been stopped within MS-DOS and it is not safe for the emulator to come to the foreground. Under these circumstances, the emulator should restart the foreground thread by calling CMDStartFG( ).

If the call was successful, the emulator should save the contents of the screen before writing to it. When returning to background operation, the emulator must restore the screen and call CMDStartFG to allow the previous foreground application to continue.

CMDStartFG — Resume scheduling of foreground task

This routine requests that scheduling of the foreground thread be resumed.

C Declaration

USHORT FAR CMDStartFG ( )

Return value	Description

0	The foreground thread was successfully stopped

non-zero	The foreground thread could not be stopped

Usage Notes

The emulator should issue this call after restoring the screen contents when returning to background operation.

RegisterSwitchProc — Register task switch procedure

This routine registers an application procedure which will be called whenever the 3270 emulator is about to be switched in or out of memory by the DOS 5 or WINDOWS task switching code.

C Declaration

USHORT FAR RegisterSwitchProc(SwitchProc)

ULONG SwitchProc;

Parameter	Description

SwitchProc	A far pointer to the function where task activity will be notified

VOID FAR PASCAL SwitchProc(InOut)

USHORT InOut;

Parameter	Description

InOut	0 if emulator is about to be switched out of memory, 1 if emulator is about to be switched back in memory

CMDSemClear — Clear a RAM semaphore

C Declaration

USHORT FAR CMDSemClear (RamSem)

ULONG FAR * RamSem;

Parameter	Description

RamSem	Address of the semaphore

CMDSemSet — Set a RAM semaphore

C Declaration

USHORT FAR CMDSemSet (RamSem)

ULONG FAR * RamSem;

Parameter	Description

RamSem	Address of the semaphore

CMDSemWait — Wait until a RAM semaphore is cleared

C Declaration

USHORT FAR CMDSemWait (RamSem, Timeout)

ULONG FAR * RamSem;

ULONG Timeout;

Return code	Description

0	OK

ERROR_SEM_TIMEOUT	Timeout expired before semaphore operation completed

ERROR_SEM_OWNED	This thread or another thread owns the semaphore, and the calling thread specified zero timeout

Parameter	Description

RamSem	Address of the semaphore

Timeout	Length of time in msec to wait before returning

CMDSemRequest — Request a RAM semaphore

C Declaration

USHORT FAR CMDSemRequest (RamSem, Timeout)

ULONG FAR * RamSem;

ULONG Timeout;

Return code	Description

0	OK

ERROR_SEM_TIMEOUT	Timeout expired before semaphore operation completed

ERROR_SEM_OWNED	This thread or another thread owns the semaphore, and the calling thread specified zero timeout

Parameter	Description

RamSem	Address of the semaphore

Timeout	Length of time in msec to wait before returning

SNAGetVersion — Get Version Number

This routine returns the major version number in the low byte and minor version number in high byte.

C Declaration

USHORT FAR snagetversion (void)


2.3.3  Buffer Management Entry Points
The DL-BASE/DMOD Interface	12 of 14

2.3  DL-BASE/DMOD Entry Points

2.3.3  Buffer Management Entry Points

See section 1.2 for more information on the format of buffer headers and elements.

SBPIBEGT — Get Buffer Element

The application calls this routine to get a buffer element to append to an existing buffer.

C Declaration

VOID FAR sbpibegt (eltptr)

PTRBFELT FAR * eltptr;

VOID sbpibegt (eltptr)

PTRBFELT * eltptr;

Parameter	Description

eltptr	Pointer to a pointer to an element. On return this points to a pointer to the element obtained, or to NULL if an element was not obtained (an internal error).

Usage Notes

This routine should only be used to get extra elements for an existing buffer. SEPDBUBL should be used to get a new buffer.

The new element should be added to the chain of elements from the existing buffer header and the count of the number of elements updated.

This routine would typically be used when a received buffer is being reused to transmit a message that is longer than the incoming message.

SBPIBERL — Release Buffer Element

The application calls this routine to release a buffer element from an existing buffer.

C Declaration

VOID FAR sbpiberl (eltptr)

PTRBFELT FAR * eltptr;

VOID sbpiberl (eltptr)

PTRBFELT * eltptr;

Parameter	Description

eltptr	Pointer to a pointer to the element to be released

Usage Notes

This routine should only be used to release surplus elements from a buffer. SEPDBURL should be called to release the entire buffer.

The released element should first be removed from the element chain and the count of the number of elements updated.

This routine would typically be used when a received buffer is being reused to transmit a message that is shorter than the incoming message.

SEPDBUBL — Get Buffer

The application calls this routine to get a buffer with a requested number of elements.

C Declaration

PTRBFHDR FAR sepdbubl (noelts)

USHORT noelts;

PTRBFHDR sepdbubl (noelts)

USHORT noelts;

Function Return Value

A pointer to the buffer obtained; NULL if a buffer could not be obtained.

Parameter	Description

noelts	Number of elements required

Usage Notes

Each element has a size of 268 — the constant SNANBEDA in the header file FMI.H.

The returned buffer consists of a header and the required number of elements. The header points to the first element, which points to the next element, and so on to make an element chain.

It is possible to add an element to an existing buffer by calling SBPIBEGT to get the extra element. The new element should be added to the element chain of the buffer, and the "number of elements" count should be updated.

The application must release any buffers that are not transmitted.

SEPDBURL — Release Buffer

The application calls this routine to release a buffer.

C Declaration

VOID FAR sepdburl (msgptr)

PTRBFHDR msgptr;

VOID sepdburl (msgptr)

PTRBFHDR msgptr;

Parameter	Description

msgptr	Pointer to the buffer to be released

Usage Notes

It is important that buffers are released after use. This is done automatically when a message is transmitted. For messages received, it is the responsibility of the application either to release or to reuse the buffer.

This routine releases both the buffer header and any associated buffer elements. It is possible to release single elements from a buffer by using the routine SBPIBERL.


2.4  Sample Code
The DL-BASE/DMOD Interface	13 of 14

2.4  Sample Code

This section contains outlines of source code for receiving messages from the DMOD.


2.4.1  Receiving Using Routing Procedure
The DL-BASE/DMOD Interface	14 of 14

2.4  Sample Code

2.4.1  Receiving Using Routing Procedure

/*****************************************************************************/

/* Sample code for initialization and routing procedure.	*/

/*****************************************************************************/

HSEM  dummysem = NULL;	/* This semaphore is never used	*/

/*****************************************************************************/

/* Initialization procedure	*/

/*****************************************************************************/

USHORT init_proc()

{

COM_ENTRY("initp");

rc = sbpuinit(&dmodsem, CLIENT, CES3270, username);

TRACE4()"DMOD initialized, rc=%d",rc));

if (rc == NO_ERROR)

{

/*************************************************************************/

/* The procedure ROUTPROC will be called whenever a message is received	*/
/* by the DMOD. This is used to post back the application, but take	*/
/* care to protect any queues against concurrent access by multiple	*/
/* threads.	*/

/*************************************************************************/

rc = sepdrout(routproc);

TRACE4()"Rout proc set up, rc=%d",rc));

if (rc == NO_ERROR)

{

/* Other initialization here	*/
}

}

return (rc);

}

/*****************************************************************************/

/* The routine routproc is called whenever the DMOD receives a message or a	*/
/* status indication	*/

/*****************************************************************************/

USHORT FAR _loadds routproc(buf, srcl, status)

BUFHDR FAR *	buf;	/* Buffer that has been received	*/
USHORT	srcl;	/* Locality from which buffer was received	*/
USHORT	status;	/* Reason for call	*/
		/* CEDINMSG = message received	*/
		/* CEDINLLN = path error occurred (on srcl)	*/
{

COM_ENTRY("routp");	/* initialize rc=FALSE	*/
	/* Call the DL BASE to handle re-resource location	*/
if (!sbpurcvx(&buf, srcl, status))

{

switch (status) {

case CEDINMSG:

if (buf->destp == S3PROD)	/* Is the message for us?	*/
{

/*******************************************************************/

/* Process the received message.	*/
/*	*/
/* If the message is DATAFMI on the PLU-SLU session, and the	*/
/* application has requested to use flow control on the session,	*/
/* then this processing should include:	*/
/* -		increment number of messages received by the client	*/
/* -		check whether the number received exceeds the threshold for	*/
/*		normally returning credit to the node. If so, check whether	*/
/*		it's OK to return credit (e.g. not short of buffers), and if	*/
/*		OK send a status-resource message to the node to give it	*/
/*		credit to send more messages to the client.	*/

/*******************************************************************/

rc = TRUE;

TRACE2()"Routing proc got message at %p",buf));

}

else

{

TRACE2()"Routing proc did not take message at %p",buf));

}

break;

case CEDINLLN:

TRACE2()"Path error on %d",srcl));

/*********************************************************************/

/* Process the path error status.	*/

/*********************************************************************/

break;

}

/*************************************************************************/

/* If the message/status cannot be completely processed here, the app	*/
/* can queue the message and clear a semaphore for the main thread to	*/
/* continue the processing.	*/

/*************************************************************************/

} else {

rc = TRUE;	/* DLBase handled the message on our behalf	*/
}

/* Returning a value of TRUE indicates that we processed the event	*/
return(rc);

}


The Function Management Interface (FMI)
Chapter 3	1 of 37

The Function Management Interface (FMI)

This chapter includes the following sections:

Section 3.1 introduces the Function Management Interface (FMI), the three FMI LPI connections and the SNA sessions to which they relate, and the use of the FMI application flags. See Chapter 1 for more information on LPI connections.

Section 3.2 describes the use of the System Services Control Point (SSCP) connection.

Section 3.3 describes the use of the Primary Logical Unit (PLU) connection.

Section 3.4 explains data flow protocols on all FMI connections.

Section 3.5 explains the use of the FMI Status messages.

Section 3.6 lists all the message types used at the FMI, with a summary of their usage and references to more detailed explanations.


3.1  Introduction
The Function Management Interface (FMI)	2 of 37

3.1  Introduction

The FMI provides applications with direct access to SNA data flows and information about SNA control flows by means of status messages, while shielding them from the full complexities of SNA protocol handling. It is particularly suited to the requirements of applications emulating 3270-type controllers.

The local node provides the SNA layers of Path Control (PC), Transmission Control (TC), and Data Flow Control (DFC), as well as Logical Unit (LU) Services — see Figure 3.1.1 below. In terms of the SNA layers, the FMI is between Presentation Services (PS) and DFC. This means that most of the SNA protocol handling is performed by the local node. In particular, the local node's DFC layer is responsible for the state changes associated with chaining, bracket, and quiesce protocols.

The FMI is defined in terms of the messages that are sent across the interface. Note that this is logically distinct from the definition of the DL-BASE/DMOD interface, which defines the mechanism for sending messages between two components in SNA Server (for example between the local node and the 3270 emulator).

The FMI is used by LU types 0, 1, 2, and 3, but not by LU type 6.2. It provides access to the SSCP-LU session as well as the main PLU-SLU session (see section 3.1.1 for more information on these sessions). An application can use the FMI to access multiple sessions, and hence multiple LUs, simultaneously.

Figure 3.1.1.    Example SNA Server system.

The 3270 emulator on the client communicates over the LAN with the local node on the server machine by exchanging messages. The content and format of the messages is defined by the FMI. The NAP and DMOD components are used to transport the messages, but do not interpret them. The local node provides the SNA layers of DFC, TC, and PC, together with Network Services. The link service and the DLC driver are responsible for transferring data between the PC layer of the node and the DLC adapter.


3.1.1  Sessions and Connections
The Function Management Interface (FMI)	3 of 37

3.1  Introduction

3.1.1  Sessions and Connections

An application using the FMI can communicate with the host on three SNA sessions:

The SSCP session, between an SNA Server LU and the host SSCP, provides information on the activation of the LU and supports communication with the SSCP for commands such as character-coded and field-formatted logon/logoff. There is one SSCP session for each SNA Server LU.

The PLU session, between an SNA Server LU and the host PLU, is the main session for data transfer between the local application and the host application. There is one PLU session for each SNA Server LU.

The PU-SSCP session, between the Physical Unit (local node) and the host SSCP, supports the reporting of alert information and link statistics to the host SSCP.

The three sessions are illustrated in Figure 3.1.2:

Figure 3.1.2.    Sessions between the application, the local node, and the host.

The application can communicate with the local node by means of three LPI connections. Rather than specifying the session on which a message is to flow, the application sends the message to the local node on one of these connections; the local node then routes it to the appropriate SNA session.

The connections are used as follows:

The SSCP connection is used for the initial start-up and logon information for a 3270 session. The SNA Server 3270 emulation programs also send network management information, such as user alerts and Response Time Monitor (RTM) statistics, to the local node on this session. See section 3.2 for more information on this connection.

The PLU connection is used for the transfer of application data, and for status and flow control messages between the application and the local node. See section 3.3 for more information on this connection.

The connections are illustrated in Figure 3.1.3:

Figure 3.1.3.    LPI Connections between the application and the local node.

These connections are specific to the local node and the application. Data and Status messages passed across a connection result in SNA data and SNA control requests being sent on the appropriate SNA session. Similarly, SNA data and SNA control responses received on an SNA session result in data and control messages being passed to the application on the appropriate connection.

The relationship between the three SNA sessions and the three connections is as follows:

SNA messages on the SSCP session from the host to the local node result in messages from the local node to the application on the SSCP connection. Messages from the application to the local node on the SSCP connection normally result in SNA messages on the SSCP session from the local node to the host (with the exception of network management information, which results in messages on the PU-SSCP session — see below).

SNA messages on the PLU session from the host to the local node result in messages from the local node to the application on the PLU connection. Messages from the application to the local node on the PLU connection result in SNA messages on the PLU session from the local node to the host.

SNA messages on the PU-SSCP session from the local node to the host are generated by messages from the application to the local node on the SSCP connection. When the application sends network management information such as 3270 user alerts on the SSCP connection, the local node distinguishes it from other data on this connection (which normally corresponds to the SSCP session) and sends the appropriate information on the PU-SSCP session to the host. See section 3.2.5 for more information.

Note the distinction between these SNA sessions and 3270 emulation sessions. A 3270 emulator may have more than one 3270 emulation session; for each emulation session, there are separate SSCP and PLU sessions.

Each connection between the application and the local node is opened, managed, and closed separately. This means that an application must maintain a separate internal control block containing the LPI pair, message keys, and state of the connection for each of the SNA sessions associated with each 3270 emulation session; for example, an application using three 3270 emulation sessions, each with an SSCP session and a PLU session, will require six control blocks.

An application identifies the connection (and hence the session) session to which a particular message belongs using the LPI pair present in the message. On a received message, the destination I value contains the application's identifier for the connection, and the source I value contains the local node's identifier for the connection. These are reversed for messages sent by the application.

The application selects the LU within the local node that it can use for communications by the relationship in the Configuration Table between the LU and APPL records (see section 3.2.1). The application may be unaware of which LU it accesses if the LUs are arranged within LU Groups.


3.1.2  Application Flags
The Function Management Interface (FMI)	4 of 37

3.1  Introduction

3.1.2  Application Flags

Application flags are included on the following messages:

All data messages (both inbound and outbound)

Status-Acknowledge (Ack) (outbound only)

Status-Acknowledge (Nack-1) (outbound only)

All Status-Control messages (both inbound and outbound)

These flags represent key indicators of the state of the session to which the message relates and are closely related (but not always equivalent) to the Request Header or Response Header (RH) indicators in the SNA Request or Response. Note that for inbound messages applications need to set the flags on data messages and Status-Control messages only.

For outbound messages the local node sets the application flags to reflect the contents of the RH in the corresponding SNA message. The local node performs checks on the SNA message before sending it to the application; therefore, the application can assume that the RH indicators obey the SNA protocols, and need not perform its own checks. The application's task in interpreting the application flags is much simpler than if the local node presented the message with the uninterpreted RH. For example:

If the application specified the "segment delivery" option when the PLU connection was opened (see section 3.3.1), the End Chain (EC) indicator on an SNA Request will occur on the first segment of the last request unit (RU) in a chain, but the chain is not complete until the last segment of that RU is received. In this case, the local node manipulates the application flags so that the End Chain Indicator (ECI) flag is set in the last segment rather than the first.

Applications using TS profile 4 (Transmission Services profile 4) on the PLU session can receive the DR2 (Definite Response 2) RH indicator in combination with DR1 (Definite Response 1) or ER (Exception Response) to give RQD2, RQD3, RQE2, and RQE3 Requests. The local node interprets the RH indicators and sets the COMMIT application flag accordingly.

For inbound data and Status-Control messages, the application should set the flags to control session characteristics such as chaining, direction control, and brackets. For Status-Acknowledge messages, the local node generates an SNA response and sets the RH indicators from information saved from the corresponding request; the application does not need to set the flags on this message.

For information on application flag usage when FMI chunking is being used, see Chunking in section 3.3.9 of this manual.

In most cases, the application will not need to take account of the application flags on Status-Acknowledge(Ack) messages, which derive from the RH indicators on the corresponding Response. However certain applications do require access to the RH flags on Responses — for example transaction-processing applications using TS profile 4 may receive the DR2 flag on Responses, which will appear as the COMMIT flag in the application flags.

The application flag usage on Status-Control messages is derived from the RH indicators in the corresponding DFC or Session Control (SC) RU. Applications may require to be aware of the RH flags for Status-Control messages. For example, LUSTAT Request type 6 is a "no-op" used solely to allow RH flags to be sent when no other request is allowed. The local node delivers the Request to the application as a Status-Control(LUSTAT) with the relevant application flags set. See SNA Format and Protocol Reference Manual: Architectural Logic (IBM publication SC30-3112) for summaries of valid RH usage for DFC RUs and of valid RH indicators for SC requests.

In the summary of the application flags below, bits are numbered with bit 0 as the most significant bit in a byte and bit 7 as the least significant. An application flag is "set" if the relevant bit for the flag is 1 and "not set" if the bit is 0.

Flag 1 occurs in all messages. The meanings of the individual bits and values that can be ORed together to set them are listed below.

FMHI [bit 0, flag 1] Value: AF_FMH (X'80')		Function Management Header Indicator — set if a function management header is present in the message, or the message is a FMD (Function Management Data) NS (network services) request. Only valid on data messages. This flag is always set for 3270 user alerts, which are sent on the SSCP connection (see section 3.2.5).
BCI [bit 1, flag 1] Value: AF_BC (X'40')		Begin Chain Indicator — set if this message starts a chain (see sections 3.3.4, "Outbound Chaining," and 3.3.5, "Inbound Chaining").
ECI [bit 2, flag 1] Value: AF_EC (X'20')		End Chain Indicator — set if this message ends a chain (see sections 3.3.4, "Outbound Chaining," and 3.3.5, "Inbound Chaining").
COMMIT [bit 3, flag 1] Value: AF_COMM (X'10')		Commit Indicator — set if chain carries DR2 (Definite Response 2).
BBI [bit 4, flag 1] Value: AF_BB (X'08')		Begin Bracket Indicator — set if chain carries BB (Begin Bracket). Note that this does not necessarily indicate that the bracket has been initiated; see section 3.3.7, "Brackets."
EBI [bit 5, flag 1] Value: AF_EB (X'04')		End Bracket Indicator — set if chain carries EB (End Bracket). Note that it does not indicate the bracket has terminated; see section 3.3.7, "Brackets."
CDI [bit 6, flag 1] Value: AF_CD (X'02')		Change Direction Indicator — set if chain carries CD (Change Direction); see section 3.3.8, "Direction."
SDI [bit 7, flag 1] Value: AF_SD (X'01')		System Detected Error Indicator — set if the local node detects an error in outbound data; see section 3.4.1, "Outbound Data."
Flag 2 occurs in all messages except for Status-Control (STSN), where the indicators included in this byte are not applicable. The meanings of the individual bits and values which can be ORed together to set them are listed below.

CODE [bit 0, flag 2] Value: AF_CODE (X'80')		Alternate Code Indicator — set if the alternate code set (usually ASCII) is used for this data message. Note that Function Management headers are unaffected by the code selection indicator.
ENCRYP [bit 1, flag 2] Value: AF_ENCR (X'40')		Enciphered Data Indicator — set to indicate that the information in the data message is enciphered under session level cryptography protocols. Users should note that they must provide the necessary support for data encryption; the SNA Server local node does not support cryptography.
ENPAD [bit 2, flag 2] Value: AF_ENPD (X'20')		Padded Data Indicator — set in conjunction with the ENCRYP flag to indicate that the data was padded at the end to the next integral multiple of 8 bytes before encipherment.
QRI [bit 3, flag 2] Value: AF_QRI (X'10')		Queued Response Indicator — set if the response to this request is to be queued in the Transmission Control and Data Flow Control layers. This flag is only significant for inbound messages.
CEI [bit 4, flag 2] Value: AF_CEI (X'08')		Chain Ending Indicator — set on a message corresponding to an outbound SNA Request with EC (End Chain) and BBIU (Begin Basic Information Unit). This flag is provided solely for the use of SNA Server components; your application should not attempt to use it.
BBIUI [bit 5, flag 2] Value: AF_BBIU (X'04')		Begin Basic Information Unit Indicator — set on a message corresponding to an outbound SNA Request with BBIU (Begin Basic Information Unit). This flag is provided for the use of SNA Server components and for applications using segment delivery and outbound pacing together (see section 3.3.9); your application should not attempt to use it.
EBIUI [bit 6, flag 2] Value: AF_EBIU (X'02')		End Basic Information Unit Indicator — set on a message corresponding to an outbound SNA Request with EBIU (End Basic Information Unit). This flag is provided solely for the use of SNA Server components; your application should not attempt to use it.
RBI [bit 7, flag 2] Value: AF_RBI (X'01')		Real BID Indicator — set on Status-Control (BID) Requests from the local node only. X'01' indicates that the message is due to an SNA BID RU, X'00' indicates that the message is due to an outbound FMD (Function Management Data) RU with BB (Begin Bracket) set.


3.2  The SSCP Connection
The Function Management Interface (FMI)	5 of 37

3.2  The SSCP Connection

The application's SSCP connection to the local node provides access to the SSCP session between the SNA Server secondary LU and the host SSCP. This section describes:

How an application opens and closes its SSCP connection.

The use of the SSCP connection.

For simplicity, this section describes the SSCP connection as if an application only uses a single SNA Server LU (and therefore a single SSCP connection); in practice, applications can use multiple LUs.


3.2.1  Opening the SSCP Connection
The Function Management Interface (FMI)	6 of 37

3.2  The SSCP Connection

3.2.1  Opening the SSCP Connection

An application gains access to the SSCP session by opening an SSCP connection to the local node. To do this an application sends an Open(SSCP) Request message to the local node, which responds with an Open(SSCP) Response. The local node follows a positive Open(SSCP) Response with a Status-Session message reporting the current state of the SSCP session (see section 3.2.3).

The message flow is shown in Figure 3.2.1 below. For a more detailed message flow diagram, including the LPI values used during initialization of both the SSCP and PLU sessions, see Figure 3.3.2 in The PLU Connection (section 3.3).

Figure 3.2.1.    Opening the SSCP connection.

LU Groups

Note that SNA Server supports LU groups; a group consists of a number of LUs of the same type (3270 display LUs or LUA LUs) such that any of the LUs in the group can be used for the same task.

If an application sends an Open (SSCP) Request specifying the name of a 3270 display LU Group, the local node may select any LU within the group to be used by the application. LUA LU groups are used in the same way, except that the application may specify either the name of the group or the name of any LU within the group in order to access the group.

Resource Location for Open SSCP

When attempting to find a free LU across more than one local node, the application does not need to be aware of which local node owns the LU. The DL-Base is responsible for finding a suitable local node, using the mechanism described below. This mechanism need not concern the application; the description is intended to assist in interpreting traces of the message flows involved.

The Open Force Type field in the Open (SSCP) Request (see section 4.1.1 for details of the message format) specifies either a forced or nonforced Open. If the LU for which the Open is intended does not have an active SSCP session because its link is inactive, a forced Open instructs the local node to attempt to activate the link and the SSCP session; a nonforced Open will succeed only if the SSCP session is already active and will otherwise return with an error code indicating the state of the LU's connection.

When the application issues the Open (SSCP) Request, it does not set the Open Force Type field. The DL-Base then issues a nonforced Open to each node in turn until it finds an LU that already has an active SSCP session. If none of these Opens succeeds, it then issues a forced Open to the node that returned the "best" error code — that is, the one most likely to be able to activate the session.

The sample message flows in Figure 3.2.2 below illustrate this process for two local nodes. The DL-Base tries each in turn, using nonforced Opens; the error code from #2 indicates that it is more likely to be able to activate the SSCP session than #1 so the DL-Base sends a forced Open to #2. The application is aware only of the first request and its response.

Figure 3.2.2.    Resource location for open SSCP.

In order to allow applications to restart after a disastrous failure (such as terminating the 3270 emulation program), the local node will also accept an Open (SSCP) Request from an application that has failed and restarts (providing the same source LPI fields are used). In this case a TERM-SELF message is sent to the Host if the LU is bound.

The SNA Server LU that the application communicates through is selected by the relationship between the APPL record and the LU or LU Group record in the configuration file. The application specifies its name using the source name field on the Open (SSCP) Request; the local node fills in the LU or LU Group number, selects an unused LU within the LU Group (if the association is to an LU Group), and informs the application of this LU number on the Open (SSCP) OK response.

The Open(SSCP) Request specifies:

The source application name.

A resource identifier that can be used by the application to correlate the Open (PLU) Request that is sent to the application (see section 3.3.1).

A Connection Information Control Block (CICB) that specifies the RH usage checks that the local node should perform for the LU (see section 3.3.1 and section 4.1). If the field for a code is set to X'01', then that receive check will be carried out by the DFC layer of the local node on data arriving from the Host. The corresponding send checks are unaffected and are always performed. The CICB is provided because these receive checks are optional in SNA; however, it is anticipated that most applications will require all these checks to be performed (all values set to X'01').

An indicator that specifies whether the application is to be treated as high or low priority. All SNA Server 3270 LUs are marked as high priority (printers do not send significant data inbound). The effect of high priority is to allow data to be progressed to the Host faster when the link is busy.

An indicator that specifies whether the application is an LUA application. This determines whether the local node and the application will communicate using the LUA variant of the FMI (see section 3.1).

An indicator that specifies a nonforced or forced Open. This determines whether the local node will attempt to activate the SSCP session if it is not currently active (see Resource Location for Open SSCP earlier in this section).

The Open (SSCP) Request may fail for one of several reasons, which can be determined from the error codes on the Open (SSCP) Error response sent to the application:

The local node may still be initializing (retrieving information from the configuration file). In this case, the application can retry immediately.

The configuration file may not have an entry for the application, or the application record in the configuration file may not point to an LU or LU Group record.

For a nonforced Open, the SSCP session may be inactive.


3.2.2  Closing the SSCP Connection
The Function Management Interface (FMI)	7 of 37

3.2  The SSCP Connection

3.2.2  Closing the SSCP Connection

To close the SSCP connection, an application sends a Close(SSCP) Request to the local node, which responds with a Close(SSCP) Response. The Close(SSCP) Request is unconditional; the Close(SSCP) Response always reports that the connection was successfully closed. The Close(SSCP) Response is provided so that applications can determine when outstanding data and status messages on the session have been delivered.

If the LU is bound, the local node sends a TERM-SELF message to the SSCP on behalf of the application to elicit an UNBIND. An application that merely wishes to be unbound need only issue Close (PLU) (see Section 3.3.2). Normally, the SSCP connection can be maintained while the application task is active, even if it is idle.

Closing the connection invalidates the LPI pair for the connection but does not alter the state of the SSCP session. The message flow is shown in Figure 3.2.3:

Figure 3.2.3.    Closing the SSCP connection.


3.2.3  Using the SSCP Session
The Function Management Interface (FMI)	8 of 37

3.2  The SSCP Connection

3.2.3  Using the SSCP Session

Once the application has opened an SSCP connection, it has access to the SSCP session and can send data to the host SSCP.

SSCP Session Characteristics

For SNA Type 2.1 nodes, the SSCP session uses FM (Function Management) profile 0 and TS (Transmission Services) profile 1. This combination of profiles gives the following session characteristics:

The primary and secondary half-sessions both use immediate request mode.

The primary and secondary half-sessions both use immediate response mode.

Only definite-response single RU chains are allowed.

The maximum RU size is limited to 256 bytes.

DFC RUs are not supported.

Pacing is not supported.

Identifiers are used (rather than sequence numbers) on the normal flows.

This implies that the SSCP connection has the following characteristics:

All data messages have the ACKRQD (acknowledgment required) field set.

All data messages have the BCI (Begin Chain Indicator) and ECI (End Chain Indicator) application flags set.

Status-Control messages do not flow on the connection.

Status-Session messages from the local node to the application only report changes in the activation state of the session.

The chaining, bracket, confirmation, and recovery protocols (described in section 3.3 for the PLU connection) do not apply.

Using the SSCP connection, the application can send and receive data messages corresponding to FMD NS(s) (Function Management Data Network Services) (session services) Requests and FMD Data Requests. Examples of FMD NS (session services) requests are:

INIT-SELF: Requests from the secondary to the host SSCP requesting that the SSCP assist in the initiation of a session to the host PLU; effectively requesting a BIND (see section 3.3.1)

TERM-SELF: Requests from the secondary to the host SSCP requesting that the PLU-SLU session be terminated with an UNBIND (see section 3.3.2)

Character-coded Requests: such as logon, logoff or test commands from the secondary display, or a logon prompt from the host application

NOTIFY: Requests used by the secondary to notify the host SSCP that a device is available after a BIND was rejected with sense X'0845'; for example, where a device emulator supports logical power-off

The local node will send a NOTIFY request to the SSCP on behalf of the LU whenever the application's SSCP connection state changes while the LU is active. A NOTIFY, vector key X'0C' with byte 5 set to X'03' (can now act as secondary LU) is sent in the following cases:

When an Open (SSCP) Request is received when the LU is already active

When an ACTLU request is accepted when the SSCP connection is already opened

A NOTIFY, vector key X'0C' with byte 5 set to X'01' (cannot currently act as secondary LU) is sent in the following cases:

When an ACTLU is received when the SSCP connection is not open

When a Close (SSCP) Request is received when the PLU session is not bound

When an UNBIND Request is received when the SSCP connection is not open

In addition the long response including the NOTIFY vector is used to ACTLU Requests

These NOTIFY messages can be used by the Host in conjunction with the negative response X'0845' that the local node gives to a BIND received when the SSCP connection is not open (see section 3.3.1).

SSCP Session Status

While the SSCP connection is open, the local node reports the initial state and any subsequent changes of state of the SSCP session to the application using Status-Session messages (see section 3.5.5). There are four distinct Status-Session status codes that can occur for the SSCP connection:

No-Session: The SSCP session between the SNA Server LU and the host SSCP is not active because the SNA Server PU and/or LU is not activated. The Status-Session carries a qualifying status code to indicate why the SSCP session is inactive. The application cannot use the SSCP connection to send data to the host SSCP. The qualifiers are:

PU-INACTIVE: ACTPU has not been received or DACTPU has been received.

PU-ACTIVE: ACTPU(COLD) has been received from the SSCP.

PU-REACTIVATED: ACTPU(COLD) has been received while the PU was active (the application is not informed if ACTPU(ERP) is received while the PU is active).

LU-INACTIVE: ACTLU has not been received, or DACTLU has been received.

Link-Error: The SSCP session between the SNA Server LU and the host SSCP is not active, due to a Data Link Control link error. The Status-Session carries a qualifying status code that gives the error code reported by Data Link Control. The application cannot use the SSCP connection to send data to the host SSCP.

Note that this session state is reported when the local node is informed that the locality containing the  SNA Server SDLC link service has been lost due to a path failure; the qualifier X'0D' is used. The link service will close the link when it is informed of the path error so the application can treat this as an outage.

LU-Active: The SSCP session is active due to the receipt of ACTLU. The application can use the SSCP connection to send data to the host SSCP.

LU-Reactivated: The SSCP session has been reactivated due to the receipt of an ACTLU from the host SSCP. The SSCP connection is still active, but data may have been lost.

Section 5.1 describes the Status-Session status codes.


3.2.4  RTM Parameters
The Function Management Interface (FMI)	9 of 37

3.2  The SSCP Connection

3.2.4  RTM Parameters

The Status-RTM message is sent to the application by the local node to indicate the Response Time Monitor (RTM) parameters being used by the host. The host can specify the following parameters:

Whether RTM measurement is active or inactive

Whether local display of RTM data by the application is permitted

The definition by which response times are to be measured:

Until the first character of a response is written to the screen

Until the keyboard is unlocked

Until the application is allowed to send data (CD or EB received)

The boundaries by which response times are to be classified into time bands

The initial values of the counters, which indicate how many responses have been received in each time band (as defined by the boundaries)

The local node is responsible for interpreting the response times reported to it by the application, and for sending RTM statistics to the host when required; the application is responsible for measuring the response times and reporting them to the local node. (The application reports response times to the local node using the Status-Acknowledge message — see section 3.3.15 for more information on measuring and reporting response times).

If the application does not wish to provide a local display of RTM data, it only needs to determine whether RTM measurement is active and (if so) the definition by which response times are measured; it can ignore the other parameters. If RTM measurement is not active, the application need not measure and report response times.

If the application wishes to provide a local display of RTM data, it should use the information from the Status-RTM message to ensure that the local interpretation of response times matches the interpretation used by the host. In particular, it should not display RTM data at all if the Status-RTM message indicates that local display is not permitted (or if the "permission to view RTM data" field in the 3270 user configuration record indicates that it is not permitted). The application is responsible for maintaining its own RTM statistics for local display; that is, for classifying the response times according to the boundaries specified by the host and maintaining counts of responses in each category. Although the local node maintains these statistics for sending to the host when required, it does not report them to the application.

Note that RTM statistics are maintained for a specific LU, not for a specific application's use of that LU. This means that when the Status-RTM message is received at start of day the counters may be nonzero to include a previous use of the LU. The counters are only reset when the host requests the local node to reset them or when the local node sends unsolicited RTM data to the host.


3.2.5  3270 User Alerts
The Function Management Interface (FMI)	10 of 37

3.2  The SSCP Connection

3.2.5  3270 User Alerts

An SNA Server 3270 emulation program can send 3270 User Alerts to the local node on the SSCP connection. This allows the local node to route each alert to the appropriate host for the 3270 session on which it was sent.

To send a 3270 user alert, the application should send it as a data message on the SSCP connection. The local node will recognize it as a 3270 user alert if both of the following are true:

The FMHI (Function Management Header Indicator) bit in the Application Flags 1 byte is set.

The first three bytes of the data are X'41038D', indicating an NMVT (Network Management Vector Transport).

The local node sends the alert to the appropriate host for the 3270 session on which it was received. If a relative time subvector is present (X'42') with increment type X'EF' (sequence), then the local node will set the sequence number in each message (starting at 1 from power up and incrementing by 1 for each message sent). Note that Comm Server allows sequence number values up to 2^16. Apart from this, the local node does not alter the contents of the alert.

Note that there may be some delay before the application receives a response to the alert; the response is sent on the SSCP connection as for other data on this connection. The application must not send further data on the SSCP connection (including further alerts) until it has received a response to this alert.


3.3  The PLU Connection
The Function Management Interface (FMI)	11 of 37

3.3  The PLU Connection

The application's PLU connection to the local node provides access to the PLU session between the SNA Server LU and a PLU (Primary LU) in the host. This section describes:

How an application opens and closes its PLU connection.

The use of the PLU connection.

For simplicity, this section describes the PLU connection as if an application only uses a single SNA Server LU (and therefore a single PLU connection); in practice applications can use multiple LUs.


3.3.1  Opening the PLU Connection
The Function Management Interface (FMI)	12 of 37

3.3  The PLU Connection

3.3.1  Opening the PLU Connection

The opening of the PLU connection is closely associated with the establishment of the PLU session. The local node opens the PLU connection when it receives a BIND command from the host for an LU for which an application has previously opened an SSCP connection. Possible sequences are:

An application opens its SSCP connection and sends a character-coded logon Request or INIT-SELF request to the host SSCP. A host PLU subsequently sends a BIND Request to the SNA Server LU, and the local node opens the PLU connection.

A host PLU sends an unsolicited BIND command to the SNA Server LU. If the SSCP connection for the LU is open, the local node opens the PLU connection. If the local node is supporting NOTIFY, then the Host can be configured to send a BIND when it receives the NOTIFY message sent by the local node when the application opens its SSCP connection (see section 3.2).

A host PLU sends a BIND command to the SNA Server LU. If the SSCP connection for the LU is not open, the local node returns a negative Response to the BIND Request. The sense code used is X'0845' (NOTIFY will be sent). The local node does not open the PLU connection. In this case the local node sends NOTIFY when the SSCP connection is opened (see section 3.2).

To open the PLU connection, the local node sends an Open(PLU) Request to the application. The application responds with an Open(PLU) Response. Finally the local node sends an Open(PLU) Confirm to the application.  This exchange of messages opens the PLU connection and establishes the PLU session. It should be noted that a successful PLU opening sequence is a "three-way handshake," in comparison to the opening of the SSCP connection (see section 3.2), which is a "two-way handshake."

The Open (PLU) Request is delivered to the application using the SSCP connection for the LU. The Open (PLU) Request contains the application name and open resource ID in order to allow applications to correlate the PLU and SSCP connections.

The Open(PLU) Request indicates the Logical Unit that the BIND Request was directed to, references the Resource Identifier supplied in the Open(SSCP) Request for that LU, and carries the actual BIND RU received from the host (see section 4.2). It also carries the maximum RU sizes, chunk sizes (if appropriate), and pacing windows for the PLU session, to enable the application to determine the initial credit if it wishes to be involved in outbound pacing (see section 3.3.9).

The message flow for a successful opening of the PLU connection (on receipt of a nonnegotiable BIND) is shown in Figure 3.3.1 below.

Figure 3.3.1.    Opening the PLU connection. Note that the BIND parameters are verified (at [1]) only when the application has supplied the BIND Check Table Index as part of the CICB (Connection Information Control Block).

Figure 3.3.2 below shows the message sequence for the initiation of both the SSCP and PLU sessions, including details of where the LPI values are assigned. (The application's source P value of 0x12 indicates that it is a 3270 emulator; see section 4.1.1 of this manual for more details of how the source LPI values are set on the Open(SSCP) Request.) The message flow shown assumes that the connection to the host is already established and that the configuration and the BIND are both valid.

After this message sequence, there are now two valid sets of LPI values, one for the SSCP session and one for the PLU session. The application can access either session at any time until UNBIND and can use the LPI values to distinguish between received data on the two sessions.

Figure 3.3.2.    Opening the SSCP and PLU connections.

BIND Checking

The Open(PLU) Response contains the Connection Information Control Block (CICB), which allows the application to "tailor" certain characteristics of the connection and contains information used in BIND verification. Note that the local node verifies the BIND parameters carried on the Open(PLU) Response; it does not maintain a copy of the original BIND RU from the host. If the BIND is negotiable, the application is permitted to modify the parameters in the BIND RU, but if it is nonnegotiable it should return the BIND RU unmodified. A negotiable BIND flag is provided in the Open (PLU) Request. See section 4.2 for a description of the Open(PLU) Response message format.

While many characteristics of the PLU session are determined by the BIND parameters, the application may select certain characteristics by specifying fields in the CICB; see Figure 3.3.3 below. More detailed information on CICB usage and the effect on the PLU session of selecting various CICB options is given in context in the later sections of this chapter that deal with PLU session characteristics such as chaining and pacing.

The BIND is verified using a BIND Check Table entry (whose index is specified in the CICB); the entries in this correspond to the various fields in the BIND. The BIND Check Table entries are stored in the configuration file. For example, the BIND Check Table entry may specify that the BIND be accepted if the secondary chain response protocol is either "definite response" or "definite or exception response" (byte 5 bits 2 and 3 = B'10' or B'11'); this would be appropriate if the application did not want to send RQE chains.

Field		Explanation
Segment delivery option		A value of X'00' indicates that the local node should perform outbound segment assembly and only deliver complete RUs. A value of X'01' indicates that the application wishes the local node to deliver RU segments. See section 3.3.6.
Application Pacing option		A value of X'00' indicates that the application requires the local node to handle pacing. A value of X'01' indicates that the application wishes to be involved with outbound pacing via Status-Resource messages. See section 3.3.9.
Application Cancel option		A value of X'00' indicates that the local node should automatically generate CANCEL. A value of X'01' indicates that the application will generate CANCEL. See section 3.3.5.
Application Transaction Numbers option		A value of X'00' indicates that the application does not support transaction numbers, while a value of X'01' indicates that the application does support transaction numbers. See section 3.3.12.
BIND Check Index		Gives the index of the BIND Check Table entry against which the BIND parameters should be verified. One of the following values should be used:
		0x01	-	3270 printer session
		0x02	-	3270 display session
		0x10	-	LUA (LU type 0) application
Figure 3.3.3.    Connection information control block usage.

The Open(PLU) Confirm from the local node to the application indicates whether the BIND verification was successful and if so supplies the Bind Information Control Block (BICB). The BICB summarizes the session BIND parameters in a format suitable for high-level languages and effectively defines the characteristics of the PLU session. The application not negotiating the BIND should not usually require to examine the BIND on the Open (PLU) Request and should use the BICB on the Open (PLU) Confirm.

Figure 3.3.4 summarizes the fields in the BICB and their correspondence to the parameters in the BIND RU. For more detailed information, see the IBM manual Systems Network Architecture: Formats, (GA27-3136). More detailed information is given in context in the parts of this section dealing with PLU session characteristics such as pacing and brackets, and the Open(PLU) Confirm message format is described in section 4.2.

Position on Open(PLU) Confirm	Position in Bind RU [byte,bit]	Description
dataru[0]	[ 2,    ]	FM Profile
dataru[1]	[ 3,    ]	TS Profile
dataru[2]	[ 4,   0]	Primary Chaining Use
dataru[3]	[ 4,   1]	Primary Request Control Mode
dataru[4]	[ 4,2-3]	Primary Chain Response Protocol
dataru[5]	[ 4,   4]	Primary 2-Phase Commit
dataru[6]	[ 4,   6]	Primary Compression Indicator
dataru[7]	[ 4,   7]	Primary Send EB Indicator
dataru[8]	[ 5,   0]	Secondary Chaining Use
dataru[9]	[ 5,   1]	Secondary Request Control Mode
dataru[10]	[ 5,2-3]	Secondary Chain Response Protocol
dataru[11]	[ 5,   4]	Secondary 2-Phase Commit
dataru[12]	[ 5,   6]	Secondary Compression Indicator
dataru[13]	[ 5,   7]	Secondary Send EB Indicator
dataru[14]	[ 6,   1]	FM Header Usage
dataru[15]	[ 6,   2]	Bracket Usage1
dataru[16]	[ 6,   2]	Bracket Reset State2
dataru[17]	[ 6,   3]	Bracket Termination Rule
dataru[18]	[ 6,   4]	Alternate Code Set Indicator
dataru[19]	[ 6,   5]	Sequence Number Availability
dataru[20]	[ 7,0-1]	Normal-Flow Send/Receive Mode
dataru[21]	[ 7,   7]	Half-Duplex Flip-Flop Reset
dataru[22]	[ 8,2-7]	Secondary Pacing Send Window
dataru[23]	[ 9,2-7]	Secondary Pacing Receive Window
dataru[24-25]*	[10,    ]	Secondary Send Maximum RU Size
dataru[26-27]*	[11,    ]	Primary Send Maximum RU Size
dataru[28]	[14,1-7]	LU-LU Session Type
dataru[29]	[27,    ]	PLU Name Size
dataru[30-37]	[28,    ]	PLU Name (in EBCDIC)
dataru[38]	[15,0-3]	Session Type 1: PS FMH Type
dataru[39]	[15,4-7]	PS Data Stream Profile
dataru[40]	[16,   0]	Number of Outstanding Destinations
dataru[41]	[16,   1]	Compacted Data Indicator
dataru[42]	[16,   2]	PDIR Allowed Indicator
dataru[43]	[15,   0]	Session Type 2 or 3: Query Support
dataru[44]	[24,1-7]	Dynamic Screen Size
dataru[45]	[20,    ]	Basic Row Size
dataru[46]	[21,    ]	Basic Column Size
dataru[47]	[22,    ]	Alternate Row Size
dataru[48]	[23,    ]	Alternate Column Size
1	X'00' = Brackets not usedX'01' = Brackets used

2	X'01' = Bracket Reset State is BETB (Between Brackets)X'02' = bracket Reset State is INB (In Bracket)

*These values are of type INTEGER (all others are of type CHAR)

Figure 3.3.4.    Bind information control block usage.

The opening PLU sequence can fail if the application rejects the Open(PLU) Request (for example if the BIND parameters are unacceptable on a nonnegotiable BIND) by sending Open(PLU) Error-Response and appropriate sense codes. The local node sends a negative Response to the BIND Request to the host containing the supplied sense codes. The PLU connection is considered to be closed after an Open(PLU) Error-Response, and the local node does not generate an Open(PLU) Confirm.

Figure 3.3.5.    Failure to open the PLU connection (for a nonnegotiable BIND), due to the application rejecting the Open(PLU) request.

The opening PLU sequence can also fail if the BIND verification against the BIND Check Table entry specified by the application fails. The local node sends a negative Response to the BIND Request to the host with appropriate sense codes and an Open(PLU) Error-Confirm to the application with the first word of the sense codes as the first error code and the index of the BIND parameter in error as the second error code. The PLU connection is considered to be closed after the Open(PLU) Error-Confirm.

Figure 3.3.6.    Failure to open the PLU connection due to BIND verification failure. Note that Error Code 2 gives the index in the RU of the BIND parameter in error.


3.3.2  Closing the PLU Connection
The Function Management Interface (FMI)	13 of 37

3.3  The PLU Connection

3.3.2  Closing the PLU Connection

Either the application or the local node may terminate the PLU connection. The criteria for closing are:

The local node closes the PLU connection if it receives an UNBIND Request from the host PLU, which terminates the PLU session. If the UNBIND type is "BIND forthcoming" (X'02'), the local node will set the BIND-forthcoming indicator in the Close(PLU) Request, so that the application can reserve any necessary resources.

The local node closes the PLU connection if it receives a DACTLU or DACTPU request from the SSCP.

The local node closes the PLU connection if it receives an outage notification from Data Link Control.

The local node closes the PLU connection if it detects a critical error in a message from the application, putting the application in a "critically failed" state. In this case the local node will send a TERM-SELF Request to the Host to elicit an UNBIND.

The application should close the PLU connection for logical power-off conditions — for example if its resources are temporarily unavailable, or when the user finishes using the session.

When the local node issues a Close (PLU), the application can determine the reason from the Close control field. There may be an associated Status message on either the PLU connection (a Status-Ack (NACK-2)) or the SSCP connection (a Status-Session message if the LU has been deactivated).

Whether the local node or the application closes the connection, the message is the same. The initiator of the Close sequence sends a Close(PLU) Request to its partner, which responds with a Close(PLU) Response. The Close(PLU) Request is unconditional — the Close(PLU) Response always reports that the connection was successfully closed.

The Close(PLU) Response is provided so that the initiator of the Close sequence can determine when outstanding data and status messages have been delivered. To avoid possible "race" conditions, the application should discard all messages it receives on the PLU connection after issuing a Close(PLU) Request, including any Close(PLU) Requests from the local node, until it receives the Close(PLU) Response.

Note that, if the application sends a Close(SSCP) while the PLU session is active, the local node will close the PLU connection (as if Close(PLU) had been sent) as well as the SSCP connection.

The message sequence for an application-initiated Close is shown in Figure 3.3.7. The local node will send a TERM-SELF request to the Host to elicit an UNBIND.

If the Host generates an UNBIND automatically on receipt of a TERM-SELF, the application can view Close (PLU) as equivalent to the termination of the PLU-SLU session.

Figure 3.3.7.    Closing the PLU connection; application initiated.

The message flow for a local node initiated Close after receiving an UNBIND Request from the host is shown in Figure 3.3.8.

Figure 3.3.8.    Closing the PLU connection; local node initiated.


3.3.3  Using the PLU Session
The Function Management Interface (FMI)	14 of 37

3.3  The PLU Connection

3.3.3  Using the PLU Session

Once the PLU connection is open, the application has access to the PLU session and can communicate with the host PLU.

PLU Session Characteristics

The local node provides support on the PLU session for FM profiles 2, 3, 4, and 7 and TS profiles 2, 3, 4, and 7. Support of these profiles means that the local node supports LU-LU session types 0, 1, 2, and 3. Using the PLU connection, the application can send and receive any FM data that is valid for the LU-LU types above.

The protocols appropriate to a particular session are determined by the parameters in the BIND Request that establishes the session. The BIND parameters are reported to the application in the BICB on the Open(PLU) Confirm message (see section 3.3.1 "Opening the PLU Connection"). It is the application's responsibility to conform to the session protocols reported in the BICB.

Due to the wide range of BIND parameters allowable on a session and the options available to an application in the CICB on the Open(PLU) Response, this document does not attempt a complete description of the protocols for a particular session. The remainder of this section (section 3.3.4 to section 3.3.14) describes the general protocol characteristics of the PLU session, such as chaining, brackets, etc.

Most of the protocol descriptions in the remainder of this section are accompanied by figures to illustrate the important features. The figures show:

The relevant RH flags in SNA Requests/Responses.

The sequence number of SNA Requests/Responses.

Any sense data (shown as "SENSE=...") on SNA Responses or data messages.

The ACKRQD field in data/Status-Control messages.

The relevant application flags (see section 3.1.2) in data/Status-Control messages.

The message key field in data messages.

Any error codes (shown as "ERROR=...") in Status-Acknowledge or Status-Control messages.

For simplicity it is assumed that all messages are Function management data flowing on the same PLU session which:

Uses half-duplex flip-flop protocols.

Uses brackets, with reset state of Between-Bracket.

Does not use the PLU CICB "segment delivery" option (see section 3.3.6).

PLU Session Status

While the PLU connection is open, the local node reports any changes of state to the application via Status-Session messages (see section 3.5.5). There is only one Status-Session status code that can occur on the PLU connection:

BETB	The PLU session has made the transition from the In-Bracket state to the Between-Bracket state (see section 3.3.7, "Brackets").
Section 5.1 describes the Status-Session status codes.


3.3.4  Outbound Chaining
The Function Management Interface (FMI)	15 of 37

3.3  The PLU Connection

3.3.4  Outbound Chaining

The local node checks that outbound chains of Requests conform to the correct SNA usage, to the chaining usage for the session, and to the current state of the session. The local node will accept valid outbound chains of data from the host if it is in one of the following states:

Data traffic is active on a full-duplex session.

Receive: the session is in a state where it can receive data.

Contention: the session is between brackets with neither half-session currently sending (see section 3.3.7, "Brackets"), or the session is in contention for a half-duplex contention session.

Error Recovery Pending: the session is waiting for the host to initiate a recovery procedure (see section 3.3.12, "Recovery"); for example, the local node has sent a negative Response to an outbound chain.

The local node sends a data message to the application for each outbound Request — but note the effects of the application specifying the "segment delivery" option in the Connection Information Control Block (see section 3.3.6, "Segment Delivery"). If the application does not specify "segment delivery," then the BCI and ECI application flags in the message header reflect the chaining indicators in the RH of the Request.

An outbound chain may terminate in several ways:

The chain is received complete and without error; all the Requests in the chain have been passed to the application as data messages and have been acknowledged where applicable (see Figure 3.3.9).

The application detects an error in a data message while receiving the chain. The application should send a Status-Acknowledgment(Nack-1) with associated sense data to the local node, which sends a negative Response plus the sense data to the host for the Request corresponding to data message in error (see Figure 3.3.10). The local node will not purge the remainder of the chain, so the application will see EC. Alternatively, the Host may terminate the chain with a CANCEL, which is delivered to the application as a Status-Control (CANCEL) with ACKRQD set.

The local node detects an error in a Request and presents the application with a System Detected Error data message to report the premature termination of the chain. This message carries the SDI (System Detected Error Indicator) and ECI (End Chain Indicator) application flags, the sense codes for the error, and the ACKRQD (Acknowledgment Required) indicator; it does not carry user data. When the application responds with Status-Acknowledge(Ack), the local node generates a negative Response to the chain using the appropriate sense code (see Figure 3.3.11). The application may use the reported sense codes to generate diagnostic information for the user (for example, a 3270 emulator would generate PROG Check Codes). The local node will purge the remainder of the chain, so the application may not see EC (End Chain). Alternatively, the Host may terminate the chain with a CANCEL, which is delivered to the application as a Status-Control (CANCEL) with ACKRQD set.

The host may cancel the chain while sending, by sending the CANCEL Request. The local node sends a Status-Control(CANCEL) message to the application, which the application must acknowledge (see Figure 3.3.12).

If an error occurs while receiving a chain, and the session uses half-duplex flip-flop protocols, then the application must assume an Error-Recovery-Pending state (see section 3.3.12, "Recovery").

For a session using half-duplex flip-flop protocols, if the application flags in the last data message of the chain have the CDI (Change Direction) flag set then:

If the chain was received without error, the application has direction.

If the application rejected any message in the chain, then the host retains direction.

Figures 3.3.9 through 3.3.12 illustrate the outbound chaining protocol between the local node and the application and how those protocols relate to the underlying SNA protocols.

Figure 3.3.9.    A complete outbound chain is received without error and accepted by the application; note that after sending Status-Acknowledge(Ack) the application has direction.

Figure 3.3.10.    A complete outbound chain is received without error, but is rejected by the application; note that even though the chain carried CD, the application does not have direction.

Figure 3.3.11.    The local node detects the invalid use of RQD without EC and converts the Request to a data message with the SDI application flag set, plus ACKRQD and appropriate sense codes. The application's Status-Acknowledge(Ack) drives the negative Response to the host (this example assumes that the receive check 4007 has been specified in the CICB on the Open (SSCP)).

Figure 3.3.12.    The host cancels the outbound chain.


3.3.5  Inbound Chaining
The Function Management Interface (FMI)	16 of 37

3.3  The PLU Connection

3.3.5  Inbound Chaining

The division of application data into data messages and the control of inbound chaining are the responsibility of the application.

The secondary maximum send RU size for the session is a parameter in the BIND from the host and is available in the Bind Information Control Block (BICB) on the Open(PLU) Confirm message (see section 3.3.1, "Opening the PLU Connection"). The application should ensure that each inbound data message corresponds to a single RU; that is, it does not contain more data than the maximum RU size given in the BICB.

The application should use the BCI and ECI application flags in the data message headers to control chaining (see section 3.1.2, "Application Flags"). The chain is the unit of recovery, and if recoverable errors occur in the chain, then the application should assume responsibility for recovery (see section 3.3.12, "Recovery").

An inbound chain may terminate in the following ways:

The complete chain is sent without errors; that is, all the data messages in the chain have been passed to the host. If the session allows the secondary to send definite-response chains, and the application set the ACKRQD field in the last data message of the chain, then the application receives a Status-Acknowledge(Ack) from the local node when the host supplies a Response (see Figure 3.3.13).

The local node detects a critical error in the format of a data message from the application or in the state of the session. The local node rejects the data message with a Status-Acknowledge(Nack-2) containing an error code and closes the PLU connection. Note that the local node will generate an inbound CANCEL Request before closing the PLU connection (see Figure 3.3.14). The local node will send a TERM-SELF Request to the Host to elicit an UNBIND.

The host sends a negative Response to a Request in the chain. The local node sends a Status-Acknowledge(Nack-1) message to the application with the sense codes and sequence number from the negative Response (see Figure 3.3.15). Where the host rejects a Request that does not carry the ECI application flag, and the application did not specify the "Application Cancel," option in the PLU CICB, the local node also generates an inbound CANCEL Request. When the application specifies "Application Cancel," then it must send EC or Status-Control(CANCEL) to terminate the chain. Any subsequent inbound chains are rejected with a noncritical Status-Acknowledge (Nack-2), sense code X'2002' or X'2004' (chaining or direction). When the application receives the Status-Acknowledge(Nack-1) message, it should stop sending data after this chain for half-duplex flip-flop sessions as the direction has passed to the Host (see section 3.3.8).

The application cancels the chain while sending, by sending a Status-Control(CANCEL) message to the local node. The local node sends a CANCEL Request to the host and sends a Status-Control(CANCEL) Ack to the application on receiving a positive response from the host (see Figure 3.3.16). Responses from the host to Requests sent before the CANCEL will generate appropriate Status-Acknowledge messages to the application if the original data messages had the ACKRQD field set.

The application closes the PLU connection while sending the chain. The local node sends a Close(PLU) response to the application. Responses from the host to Requests sent before the Close(PLU) message will not generate Status-Acknowledge messages to the application. Note that the local node will also generate an inbound CANCEL Request (see Figure 3.3.17) and a TERM-SELF request to elicit an UNBIND.

If the local node detects a noncritical error in the format of a data message from the application or the state of the session, it does not close the PLU connection. Instead, it rejects the data message in error with a Status-Acknowledge(Nack-2) containing an appropriate error code (see Figure 3.3.18). No data is sent to the Host.

If an inbound chain terminates with an error, then if the session uses half-duplex protocols, the application must assume a receive state (see section 3.3.12 "Recovery").

Figures 3.3.13 through 3.3.18 illustrate the inbound chaining protocol between the local node and the application and how those protocols relate to the underlying SNA protocols.

Figure 3.3.13.    A complete inbound chain is sent without error and accepted by the host; note that after receiving Status-Acknowledge(Ack) the application relinquishes direction to the host.

Figure 3.3.14.    The local node detects a critical error in the format of the second data message in the chain (ACKRQD without the ECI application flag), sends a Status-Acknowledge(Nack-2) to the application with the appropriate error code, and closes the PLU connection. Note that the local node only generates the CANCEL where the session's FM Profile supports CANCEL.

Figure 3.3.15.    A complete inbound chain is sent without error, but is rejected by the host; after the negative response, the application must enter receive state, pending error-recovery (see section 3.3.12, "Recovery").

Figure 3.3.16.    The application cancels the chain by sending Status-Control (CANCEL); note that the application still has direction and may commence a new chain.

Figure 3.3.17.    The application closes the PLU session while sending the chain; the local node only generates the CANCEL where the session's FM Profile supports CANCEL.

Figure 3.3.18.    The local node detects a noncritical error in the format of the second data message in the chain and sends a Status-Acknowledge(Nack-2) to the application with the appropriate error code.


3.3.6  Segment Delivery
The Function Management Interface (FMI)	17 of 37

3.3  The PLU Connection

3.3.6  Segment Delivery

Where the maximum RU size for a session (supplied in the BIND parameters) allows RUs that are larger than the maximum size of a Data Link Control transmission unit (for example an SDLC frame), then the local node's Path Control is responsible for assembling outbound segments into RUs and segmenting inbound RUs where required.

However, certain IBM products (for example SNA models of the 3270 controllers) do not perform outbound segment assembly, to improve perceived response times at display terminals by displaying each segment as soon as it is received — this feature is referred to as "window shading."

The local node allows an application to specify a "segment delivery" option in the Connection Information Control Block on the Open(PLU) Response (see section 3.3.1, "Opening the PLU Connection"). If an application specifies this option, the local node's Path Control does not assemble outbound segments into complete RUs, and the local node delivers the segments to the application in data messages. This allows an application emulating a 3270 device to reproduce the perceived response characteristics of the IBM device. In cases where throughput is high, such as 3270 file transfer, segment delivery can give improved performance compared to RU delivery.

Note that there is no comparable feature for inbound data — the application must present data messages containing complete RUs to the local node. Also, there is no support for segment delivery on the SSCP session and connection (where the maximum RU size is limited to 256 bytes).

The local node supports the "segment delivery" option in such a way that the constraints placed on an application receiving data in either form are identical. If complete RUs are required, then the local node rebuilds the RUs from segments in Path Control. If segments are required, the local node handles all segmentation indicators and modifies processing within its SNA layers to cater for segmented RUs.

All data messages delivered to the application contain application flags — whereas only the first segment in an RU contains an RH. The local node "delays" the EC and CD indicators if they occur in the RH of the RU's first segment and sets the corresponding ECI and CDI application flags in the data message corresponding to the last segment of the RU. Therefore the data messages corresponding to RU segments have application flags set as if they corresponded to whole RUs. This considerably simplifies the handling of chaining, bracket, and half-duplex protocols for an application using the "segment delivery" option.

Note that EB is not delayed until EBIU since the application should use the Status-Session Between Brackets message to determine when to enter the between brackets state.


3.3.7  Brackets
The Function Management Interface (FMI)	18 of 37

3.3  The PLU Connection

3.3.7  Brackets

This section primarily describes the bracket protocols between the local node and an application for a session supporting "half-duplex flip-flop with brackets."

The local node enforces no bracket protocols for full-duplex sessions; therefore, messages with BB are not presented as Status-Control (BID) messages, and there are no Status-Session (BETB) messages.

The management of this protocol for a generalized application is complex, and there is a significant amount of code in the local node to simplify the application's perception of the protocol. An application is only aware of two states:

In-bracket

Between-bracket

The local node, in addition to the states of In-Bracket and Between-Bracket, maintains additional transient states with a large state transition matrix, or Finite-State Machine, governing the half-session's state at a particular time.

Bracket Initiation

While a session is in the Between-Bracket state, "contention" exists. Either the application or the host PLU may attempt to initiate a bracket, as follows:

The application initiates a bracket by sending a data message with the BBI application flag and ACKRQD set while in the Between-Bracket state. The local node sends a Request corresponding to the data message to the host PLU (see Figure 3.3.19). The application has successfully initiated a bracket and is in the In-Bracket state. Flip-flop protocols are now in force until the bracket is terminated.

The application initiates a bracket by sending a Status-Control(LUSTAT) with the BBI application flag set while in the Between-Bracket state. The local node sends an LUSTAT Request to the host PLU (see Figure 3.3.20). The application has successfully initiated a bracket and is in the In-Bracket state. Flip-flop protocols are now in force until the bracket is terminated.

The host PLU sends a BID Request while in the Between-Bracket state. The local node sends a Status-Control(BID) with ACKRQD to the application (see section 3.5.2). The application replies with a Status-Control(BID) ACK, to indicate that it is willing to accept a bracket. The local node sends a positive response to the BID Request (see Figure 3.3.21). The host PLU has successfully initiated a bracket, and the application's state is In-Bracket, with flip-flop protocols applying until the bracket is terminated.

The host PLU sends data in an RU carrying the BB indicator in the RH while in the Between-Bracket state. The local node presents this method of initiating a bracket in the same way as if the host PLU had initiated the bracket with BID. The local node sends a Status-Control(BID) with ACKRQD to the application. The application replies with a Status-Control(BID) positive response to indicate that it is willing to accept the bracket. The local node sends the data message corresponding to the RU to the application and sends a positive response to the data RU (see Figure 3.3.22). The host PLU has successfully initiated a bracket, and the application's state is In-Bracket, with flip-flop protocols applying until the bracket is terminated.

The host PLU sends an LUSTAT Request carrying the BB indicator in the RH. The local node presents this method of initiating a bracket in the same way as if the host PLU had initiated the bracket with BID. The local node sends a Status-Control(BID) with ACKRQD to the application. The application replies with a Status-Control(BID) positive response to indicate that it is willing to accept the bracket. The local node sends a Status-Control(LUSTAT) to the application, which requires an acknowledgment (see Figure 3.3.23). The host PLU has successfully initiated a bracket, and the application's state is In-Bracket, with flip-flop protocols applying until the bracket is terminated.

The host attempts to initiate a bracket using a BID Request or an RU carrying BB, which the local node sends to the application as a Status-Control(BID), but the application cannot accept the bracket. The application should send a negative Status-Control(BID) response with an appropriate sense code. The local node sends a negative response to the BID carrying the sense code supplied by the application (see Figure 3.3.24). The application's state is still Between-Bracket. The application should use one of the following sense codes:

X'081B' if it has already committed resources for an inbound transfer; for example, a terminal operator has begun typing.

X'0814' if it currently cannot begin a bracket but will notify the host when resources become available; for example, a 3270 printer is being used for local copy in Between-Bracket printer sharing mode. At a later stage when the resources become available, the application should temporarily reserve the resources and send a Status-Control (RTR) to the local node. If the host rejects the RTR, the local node returns a Status-Control(RTR) NACK-1 response, and the application may release the resources. Otherwise, the host attempts to initiate a bracket that the application must now accept.

Where the application has successfully initiated a bracket, a bracket race may occur due to the host PLU attempting to initiate a bracket. The application gets a Status-Control (BID) Request, which it should reject X'080B' or X'0813'. The application retains direction after race negative responses (see section 3.3.12). The application's bracket state remains as In-Bracket.

The application needs to be aware of one further complication in bracket initiation. All the above cases relate to sessions whose bracket reset state is Between-Bracket; that is, a state of contention exists, and either half-session may attempt to begin a bracket.

However, the BIND parameters for the session may specify a bracket reset state of In-Bracket. Where the Bracket reset state is In-Bracket, one half-session is considered to have already successfully initiated a bracket. Flip-flop protocols will then apply until a Status-Session(BETB) is received, at which time the session reverts to a contention state and bracket initiation proceeds as described above.

The application must set its Bracket state when the PLU connection is opened (that is, on receipt of the Open(PLU) Confirm message) and reset it each time the session is reset (that is, after receipt of a Status-Control(CLEAR) Request). The appropriate Bracket reset state for the session is supplied to the application in the BIND Information Control Block on the Open(PLU) Confirm message.

Figures 3.3.19 through 3.3.24 illustrate the bracket initiation protocol between the local node and the application and how those protocols relate to the underlying SNA protocols.

Figure 3.3.19.    The application initiates a bracket by sending an inbound chain with the BBI application flag set when its state is Between-Bracket. The application's state is In-Bracket until it receives a Status-Session(BETB). (If the application can send RQE chains, a bracket may be opened by sending an RQE chain).

Figure 3.3.20.    The application initiates a bracket by sending a Status-Control(LUSTAT) with the BBI (Begin Bracket Indicator) application flag set when its state is Between-Bracket. The application's state is In-Bracket until it receives a Status-Session(BETB). The LUSTAT may be sent NOACKRQD (that is, RQE) if required.

Figure 3.3.21.    The host initiates a bracket by sending BID, accepted by the application. The application's state is In-Bracket and the host can send.

Figure 3.3.22.    The host PLU initiates a bracket by sending a Request with BB (Begin Bracket), accepted by the application. The application's state is In-Bracket, and the host can send. Note that the perception of the application is identical to that in Figure 3.3.21 (except for the RBI flag).

Figure 3.3.23.    The host initiates a bracket by sending an LUSTAT with BB, accepted by the application. The application's state is In-Bracket, and the host can send.

Figure 3.3.24.    The host and application both attempt to initiate a bracket in Between-Bracket state; the application rejects the host "bid" with sense code X'0813', and the local node delivers the application's data. After sending the data, the application's state is In-Bracket, and the application can send.

Bracket Termination

The local node supports Bracket Termination Rule One (conditional) and Bracket Termination Rule Two (unconditional), as specified in the BIND request. Some sessions only allow bracket termination by one session partner; this is a BIND option (supplied in the BICB on Open(PLU) Confirm), and it is the application's responsibility to determine if (and when) it should request bracket termination.

If an application is allowed by its BIND to terminate brackets, it does so by setting the EBI application flag in an inbound data or Status-Control (LUSTAT/CHASE/QC/CANCEL) message. The bracket is only terminated when the application receives a Status-Session(BETB) from the local node.

If the host terminates a bracket successfully, the local node sends a Status-Session(BETB) to the application. Note that the EBI application flag on outbound messages does not indicate bracket termination, but indicates that the corresponding RU carried EB. The bracket is only terminated when the application receives Status-Session(BETB).

Note that if the application queues data, then it should also queue Status-Session (BETB) messages; they must not be processed as "expedited."

Figures 3.3.25 through 3.3.26 illustrate the bracket termination protocol between the local node and the application and how those protocols relate to the underlying SNA protocols.

Figure 3.3.25.    The application successfully terminates a Bracket by sending an EBI data chain when the application's state is In-Bracket, which the host accepts. The local node sends a Status-Session(BETB) to indicate that the application's state is now Between-Bracket.

Figure 3.3.26.    The host successfully terminates a Bracket by sending an EBI data chain when the application's state is In-Bracket, which the application accepts. The local node sends a Status-Session(BETB) to indicate that the application's state is now Between-Bracket.


3.3.8  Direction
The Function Management Interface (FMI)	19 of 37

3.3  The PLU Connection

3.3.8  Direction

When an FMI application is communicating on its PLU connection with a normal flow request mode other than full duplex (that is, half duplex flip-flop or half duplex contention), it must obey the SNA direction protocol. These two modes are treated separately.

Half Duplex Flip-Flop Direction

The BIND used to establish the session carries information about the initial state of the bracket and direction machines. This may be specified in the BIND if either of the following conditions are satisfied:

Brackets are not used

Brackets reset state is ‘in-bracket'

If neither of the conditions hold, then the initial direction state is contention.

When the direction is specified in the BIND, the application should assume the direction state specified in the half-duplex reset state as soon as data can flow. This field can be obtained indirectly by using a BIND check index that only accepts a particular direction, or directly by reading the HDXRSET field in the BICB on the Open (PLU) Confirm OK message (see section 3.3.1), or by reading the BIND on the Open (PLU) Request.

When in contention state, either the PLU or the application may initiate a bracket (see section 3.3.7); the successful initiator of the bracket obtains direction (unless direction is relinquished when opening the bracket by sending BB, BC, EC, CD). Since the secondary is assumed to be the contention winner, the application may assume send state from contention sending BB and rejecting any subsequent Status-Control (BID) Request from the local node before receiving Status-Session (BETB). When the application accepts a Status-Control (BID) Request in contention state, then it must assume receive state.

Half-duplex flip-flop direction may change through the following actions:

Sending or receiving data with the Change Direction (CD) indicator in the RH (and the corresponding CDI (Change Direction Indicator) flag on the DATAFMI and Status-Control messages). Note that CD is only used at the end of a chain (and for applications receiving segments will be delivered with ECI,EBIUI). Also note that CD is valid on the following normal flow Status Control Requests: LUSTAT, CANCEL, CHASE and QC.

Receiving a negative response when the application should assume receive state (error recovery pending state — see section 3.3.12).

If the application rejects data from the Host carrying CDI, then it must remain in receive state.

Providing the FM Profile is correct (3, 4, or 7), the application may request direction from the host using a Status Control (SIGNAL) Request with CODE1 set to X'0001'; CODE2 is set to a user-defined value.

Figures 3.3.27 through 3.3.29 illustrate the direction protocol for applications using the half duplex flip-flop mode.

Figure 3.3.27.    The application issues and receives CD without error.

Figure 3.3.28.    Host sends negative response to inbound data; the application assumes receive state, then the host sends CD to give the application direction.

Figure 3.3.29.    A complete outbound chain is received without error, but is rejected by the application; note that even though the chain carried CD, the application does not have direction.

Half Duplex Contention

For Half Duplex Contention, the initial direction state is contention. Half Duplex protocol operates during a chain (only one partner may send), but the direction state normally returns to contention at the end of each chain. The CD indicator in the RH is thus not required; however, if the CD indicator is used, direction is reserved for the receiving half session. Therefore, if the application receives CD, it should assume send state and not expect to receive data. Conversely, if the application sends CD, then it may not send again until it has received a chain from the host.

In the event of an error being discovered by either half session, the application must assume receive state, since the Host is responsible for recovery.

If both half sessions attempt to start a chain when the direction state is contention, the race is resolved in favor of the secondary application using a sense code of X'081B'. However, the possible window between the local node and the application means that the local node cannot determine when outbound RQE data is received by the application. Therefore, if the local node receives data from the application while it determines that the half duplex contention state is receive, it will reject it with a noncritical NACK-2 (X'2004' direction).

Figures 3.3.30 and 3.3.31 illustrate the direction protocol for applications using half duplex contention mode. The Figures 3.3.27 through 3.3.29 would also be valid although CD does not need to be specified.

Figure 3.3.30.    The application issues and receives data using half duplex contention protocol without error.

Figure 3.3.31.    Half duplex contention race is resolved in favor of the application.


3.3.9  Pacing and Chunking
The Function Management Interface (FMI)	20 of 37

3.3  The PLU Connection

3.3.9  Pacing and Chunking

The local node supports session pacing inbound and outbound, according to the pacing values in the BIND parameters for the session. The application can be involved in outbound pacing through the use of the Status-Resource message; inbound pacing is handled transparently by the local node and need not concern the application.

Outbound Pacing

If the application has enough resources to handle outbound data as fast as the network can provide it (for example a screen), or if a higher level protocol (for example immediate request mode) constrains the data flow, then the application need not be involved in pacing, and it is possible for the local node to handle outbound pacing transparently.

However, certain types of applications may require involvement in outbound pacing. If the application has limited resources (for example a printer), then the application should specify the "application pacing" option in the Connection Information Control Block on the Open (PLU) Response (see section 3.3.1) and provide the local node with information on the state of these resources initially on the Open (PLU) OK Response and periodically using Status-Resource messages.

In order to assist the application in calculating the initial credit field in the Open (PLU) OK Response, the local node delivers the pacing window sizes and the primary and secondary maximum RU sizes on the Open (PLU) Request. The initial credit must be at least as large as the primary to secondary pacing window size; otherwise the BIND will be rejected and the application will be sent an Open (PLU) Confirm Error message. The local node fills in a suggested initial credit value of one more than the pacing window (to try to avoid stop-start situations).

Note that the local node will also reject the BIND if the application specifies that it wishes to be involved in pacing (of whatever initial credit), but the BIND specifies that there is no outbound pacing.

Only FMD (Function Management Data) requests are part of the credit scheme, so the application must maintain space within its buffer for one Status-Control request per RU in addition to the number of RUs specified by the initial credit count (a Status-Control message takes up 36 bytes).

Each unit of credit that the application delivers to the local node allows the local node to give the application a single RU (or a single chunk if chunking is being used; see below). Note that if the application is receiving segments, then this may correspond to several DATAFMI messages. The application can count RUs for the purpose of outbound flow control by using the BBIU (Begin Basic Information Unit) and EBIU (End Basic Information Unit) flags.

The application should maintain a credit used count, which it should report to the local node on Status-Resource messages. The actions that the application needs to take are as follows:

On processing (not receiving) DATAFMI messages with EBIU set (corresponding to FMD requests), increment the credit used count by one.

On processing Status-Control messages and all other messages from the local node, do not increment the credit used count.

Periodically report the current credit used count on a Status-Resource message.

The application must report the credit used count when its buffer becomes empty (whatever the last message processed was), unless the credit used count is zero.

When the credit used count is reported to the local node, reset it to zero.

The frequency at which the application provides Status-Resources is not architected. However, the local node will only send the application as many data messages as it has received credit for, and so when the application's credit used count reaches the initial credit value, the local node will not send any more data. The application should attempt to send a Status-Resource message before this happens, because if the local node cannot send a data message to the application and the host is still sending Requests, the local node may not be able to send a pacing response to the host when required, with a consequent degradation of performance.

If the pacing window is small, such as one or two, the application should send a Status-Resource after processing each DATAFMI message in order to allow the local node to send the suitable pacing response.

Figure 3.3.32 shows the local node handling outbound pacing when the application is not involved (APPLPAC = X'00'); the pacing window is assumed to be 2.

Figure 3.3.32.    Outbound pacing handled by the local node.

Figure 3.3.33 shows the local node and the application handling outbound pacing with the outbound pacing window assumed to be 2 and the initial credit from the local node to the application assumed to be 4. Note that the local node can send an Isolated Pacing Response (IPR) to the Host to get another window full of data as soon as the application has sufficient credit for the rest of the present window and the next window.

Figure 3.3.33.    Outbound pacing handled by the local node and the application.

Chunking

Note

Previous versions of this document indicated this as a future feature. The support is enabled in Comm Server 1.2 (and later) under OS/2, and in the first release of SNA Server for Windows NT. Applications should therefore test the product version returned on a call to sepdgetinfo for 1.2 or later before using the chunking system.

In some cases, the RU size used by the local node may be too large for the length of the path between the local node and an FMI application; for example, when using a 16MB token-ring link, which can support 16kB frames. The local node allows an FMI application to specify that data transfer should be in smaller units — "chunks."

For example, consider an implementation using OS/2 named pipes, with a maximum pipe size of 4k. If the maximum RU size is 8k, the application may specify that data is to be transferred in smaller chunks of 1k. Together with a credit limit, this ensures that the pipe will never be completely full. (It is important to ensure that the pipe is never filled, because if the local node attempts to write to a full pipe, it will be blocked, causing severe performance problems.)

Chunking may be thought of as similar to segmentation (see section 3.3.6 for more information); the distinction is that segmentation is determined by the communications link between the local node and the remote system, whereas chunking is determined by the communications link between the application and the local node.

The application indicates on the Open (SSCP) request whether it supports chunking, and (if it supports chunking) the chunk size in bytes that it wishes to use. The local node then uses the RU size, the chunk size, and the segment size (if applicable) to determine whether chunking is necessary. It then specifies the chunk sizes used for inbound and outbound flow (which need not be the same) on the Open (PLU) Request; these values are specified in units of elements (see section 1.2 for more information). A value of zero for either of these sizes indicates that chunking is not necessary because the chunk size is not the limiting factor. Note that in chunking data an RU will not be split in the middle of an element; this avoids data copying.

For example, assume that the local node is using an RU size of 8k and segments of 2k, and the application's Open (SSCP) Request specifies segment delivery and a chunk size of 4k. Chunking will be used on inbound data flow (because the chunk size is smaller than the RU size), but is not necessary on outbound data flow (because data will be delivered in segments that are smaller than the chunk size).

If chunking is being used in either direction, then all credit values (see the following sections) specify the number of chunks that can be sent in that direction, not the number of RUs. Note that the segment delivery option is included on the Open (SSCP) Request to allow the local node to calculate the initial chunk credit values on the corresponding PLU connection. The application must also set this option on the Open (PLU) response; if the Open (SSCP) Request and the Open (PLU) Response have different settings of this option, the setting from the Open (PLU) Response will be used. This may mean that the initial credit value used is not appropriate.

If session-level pacing is being used, the local node links this to the chunking credit. In particular, if the application withholds credit, the local node will delay sending a pacing response to the host, thereby applying back pressure to the host. This linkage is handled by the local node and need not concern the application.

Application flags (see section 3.1.2) on chunks of RUs are handled in the same way as those on segments (see section 3.3.6 for more information on segment delivery). In particular:

FMHI, BCI, COMMIT, BBI, EBI, CODE, ENCRYP, ENPAD, QRI, and CEI are only ever set on the first chunk of an RU.

ECI and CDI are only ever set on the last chunk of an RU.

BBIUI is always set on the first chunk of an RU.

EBIUI is always set on the last chunk of an RU.

Note that EBI is set on the first chunk of the last RU in a bracket and not on the last chunk as might be expected; this is the same behavior as for segment delivery. The application should use the Status-Session(BETB) message, not the EBI flag, to determine when a bracket has ended.

Chunks are identified using the segmentation flags BBIUI and EBIUI, and therefore the application cannot distinguish between chunks and segments if both segmentation and chunking are being used outbound. However, there is generally no need for the distinction; the application can perform "window shading" (see section 3.3.6 for more information) by displaying each unit of data as it is received, whether the unit of data is a segment or a chunk.


3.3.10  Confirmation and Rejection of Data
The Function Management Interface (FMI)	21 of 37

3.3  The PLU Connection

3.3.10  Confirmation and Rejection of Data

Confirmation and Rejection of Inbound Data

For every SNA chain of data sent or received for which responses are outstanding (RQE or RQD), the local node maintains a Correlation Table entry (CT). If the CTs become depleted, then the local node will terminate the session using the most CTs. A Status-Error message (code X'46') and a Close (PLU) Request are sent to the application, and a TERM-SELF message is sent to the host. CT shortages (inbound) can be avoided by sending CD (for half-duplex) data, or data ACKRQD, or any Status-Control (CHASE), or Status-Control (LUSTAT) with ACKRQD. Outbound shortages can be avoided by sending "Courtesy Acknowledge" messages as described in section 3.3.1.

The local node sends chains of data to the host with their chain response mode specified as follows:

1.	Definite

If the application sends a data message to the local node with the ACKRQD field set, and the BIND parameters specified that the secondary uses definite or definite/exception response mode.

2.	Exception

If the application sends a data message to the local node without the ACKRQD field set, and the BIND parameters specified that the secondary uses exception or definite/exception response mode.

3.	No-Response

If the application sends a data message to the local node without the ACKRQD field set, and the BIND parameters specified that the secondary uses no-response mode.

If the setting of ACKRQD on a data message from the application does not reflect the chain response mode specified in the BIND parameters, the local node returns a Status-Acknowledge (Nack-2) indicating a noncritical error code; for example, if the application specifies ACKRQD but the BIND parameters do not permit the local node to send definite response chains).

In case 1, the application receives an acknowledgment to all FMD chains it sends to the local node:

Positive responses from the host are returned to the application as Status-Acknowledge(Ack) messages.

Negative responses from the host are returned as Status-Acknowledge(Nack-1) messages carrying the SNA sense codes.

Errors detected by the local node when attempting to send the message are returned as Status-Acknowledge(Nack-2) messages carrying the equivalent error code.

In case 2, the application only receives an acknowledgment of an FMD chain it sends to the local node for:

Negative responses from the host, which are returned as Status-Acknowledge(Nack-1) messages carrying the SNA sense codes

Errors detected by the local node when attempting to send the message, which are returned as Status-Acknowledge(Nack-2) messages carrying the equivalent error code

In case 3, the application only receives an acknowledgment of an FMD chain it sends to the local node when the node detects an error in the message and sends the application a Status-Acknowledge(Nack-2). The only dissent that the Host can make is to send a subsequent LUSTAT X'400A' (no response not supported) with the sequence number of the request in the sense qualifier field; this is presented to the application as a Status-Control (LUSTAT) as usual.

Whenever an application receives a Status-Acknowledge(Ack) or Status-Acknowledge(Nack-1), it implicitly confirms receipt by the partner half-session in the host of all previously sent chains.

In case 2 the application does not usually receive such responses from the host to chains it has sent, and in case 3 the application never receives such responses. Therefore, to get the host to confirm receipt of all previously sent chains, the application should issue a Status-Control(CHASE) Request with ACKRQD set. This causes the local node to generate an SNA CHASE Request to the host. The receipt of the response to this CHASE confirms that the host has received this CHASE request and all previous chains sent by the application. The local node issues a Status-Control(CHASE) Ack to notify the application that this is so (see Figure 3.3.36).

Figures 3.3.34 through 3.3.36 illustrate the inbound data confirmation and rejection protocols between the local node and the application, and how those protocols relate to the underlying SNA protocols.

Figure 3.3.34.    An application sets the ACKRQD field in an inbound data chain to get the host to confirm receipt of the chain and all previously sent chains.

Figure 3.3.35.    The Status-Acknowledge(Nack-1) rejects the last chain, but confirms receipt by the host of all previously sent data chains.

Figure 3.3.36.    The application uses a Status-Control(CHASE) to get the host to confirm receipt of the corresponding CHASE Request and all previously sent chains.

Confirmation and Rejection of Outbound Data

The local node sends chains of data from the host to the application with their ACKRQD field set as follows:

1.	ACKRQD set

If the corresponding SNA request was received specifying definite response, and the BIND parameters specify that the primary uses definite or definite/exception chain response mode.

2a.	ACKRQD not set

If the corresponding SNA request was received specifying exception response, and the BIND parameters specify that the primary uses exception or definite/exception chain response mode.

2b.	ACKRQD not set

If the corresponding SNA request was received specifying no-response, and the BIND parameters specify that the primary uses no-response chain response mode.

In case 1, the application should always send an acknowledgment as follows:

If the application accepts the data, it should return a Status-Acknowledge(Ack) message.

If the application wishes to reject the data, it should return a Status-Control(Nack-1) message carrying the appropriate SNA sense codes.

In case 2a, the application should only send an acknowledgment in the following cases:

If the application wishes to reject the data, it should return a Status-Control(Nack-1) message carrying the appropriate SNA sense codes.

The application may send a courtesy Ack (see section 3.4.1) to an RQE message to clear up correlation data within the local node.

In case 2b the application should not send acknowledgments; however, the sending of a Status-Acknowledge (Ack) or (Nack-1) by the application has no effect — it is discarded.

Whenever an application sends a Status-Acknowledge(Ack) or Status-Acknowledge(Nack-1) to a received data message, it implicitly confirms receipt of this and all previously received data messages.

In case 2, the host may issue a CHASE Request; the local node sends a Status-Control(CHASE) Request with ACKRQD set to the application. When the application is in a position to confirm receipt of all outstanding data, it should issue a Status-Control (CHASE) Ack message, which the local node converts into a positive response to CHASE for the host.

In cases 1 and 2a, if the local node detects an error in a received Request, it converts the Request into a special data message, which it passes to the application. Regardless of the chain response mode specified for the secondary in the BIND parameters, this data message has the following characteristics:

ACKRQD is set; that is, the application must confirm receipt using a Status-Acknowledge(Ack) message.

The SDI application flag is set to indicate that this is a special data message used to inform the application of an error detected by the local node.

The ECI application flag is set to indicate that the received chain has now terminated.

The first four bytes of the buffer element hold the SNA sense codes detected by the local node that caused the termination.

This mechanism allows:

The application to reject any previously received data messages.

The local node to inform the application of any errors it detects in received requests.

The local node to send negative responses in the correct order.

Figures 3.3.37 through 3.3.39 illustrate the outbound data confirmation and rejection protocols between the local node and the application and how those protocols relate to the underlying SNA protocols.

Figure 3.3.37.    The host sends a definite response chain to get the application to confirm receipt of the RQD request and all previously sent RQE chains.

Figure 3.3.38.    A Status-Acknowledge(Nack-1) from the application rejects the last chain and confirms receipt of all previously sent data chains.

Figure 3.3.39.    The host sends a CHASE Request to get the application to confirm receipt of the CHASE and all previously sent chains.


3.3.11  Shutdown and Quiesce
The Function Management Interface (FMI)	22 of 37

3.3  The PLU Connection

3.3.11  Shutdown and Quiesce

Both shutdown and quiesce protocols involve a half-session entering a quiesced state, in which it may not send any more normal flow Requests, but must continue to receive and respond to Requests from its session partner. The essential differences are that shutdown can only be initiated by the host and only requires that the secondary quiesce as soon as is convenient (usually at the end of a bracket); quiesce can be initiated by both the host and the application and requires that the recipient quiesce at the end of the chain.

If the application has been quiesced but still attempts to send inbound data messages, they will be rejected with Status-Acknowledge(Nack-2) messages. The application may, however, continue to generate status messages.

Shutdown

The shutdown protocol provides a means for the host application to stop the application from sending any further normal flow Requests. This protocol is used when the host application wishes to end the session in an orderly manner and is only available for sessions using FM Profile 3 or 4.

If the local node receives a SHUTD Request from the host, it issues a Status-Control(SHUTD) Request (without ACKRQD) to request the application to enter a quiesced state at a convenient time. The application determines what is convenient — for example, it could be after a Status-Session(BETB) has been received.

When the application decides it is ready to quiesce, it should issue a Status-Control(SHUTC) Request (again without ACKRQD) to indicate this transition. The local node will notify the host of this change by sending a SHUTC Request. The host may continue sending normal flow outbound Requests and may subsequently take one of the following actions:

The host terminates the PLU session by sending an UNBIND Request. The local node closes the PLU connection by sending a Close(PLU) Request to the application (see Figure 3.3.35). The SSCP session remains active.

The host abandons the shutdown procedure by sending an RELQ Request. The local node sends a Status-Control(RELQ) Request (with ACKRQD) to the application to indicate that it may now resume sending on the PLU session (see Figure 3.3.36). RELQ is only supported on sessions using FM profile 4.

The host resets the session by sending CLEAR (TS Profile 3 or 4); one of the effects of this is to release the quiesced state (see section 3.3.12).

Figure 3.3.40 and Figure 3.3.41 illustrate the shutdown protocols between the local node and the application and how those protocols relate to the underlying SNA protocols.

Quiesce

The quiesce protocol is only supported on sessions using FM Profile 4. The quiesce protocol can be initiated by either half-session.

When an application wishes to quiesce its partner half-session in the host, it sends a Status-Control(QEC) Request to the local node. The node generates a QEC Request to the host, which asks the host to quiesce after completing the current outbound chain.

If the host quiesces, it sends a QC Request, which the local node presents to the application as a Status-Control(QC) Request (with ACKRQD). The host remains in a quiesced state until the application sends a Status-Control(RELQ) Request. The local node sends the RELQ Request to the host, and the host resumes communications on the PLU session (see Figure 3.3.42).

If the attempt to quiesce the host fails, the host responds with a negative QEC Response, which the local node presents to the application as a Status-Control(QEC) Nack-1 (see Figure 3.3.43).

Conversely, a Status-Control(QEC) Request (without ACKRQD) is presented to the application if a QEC Request is received from the host. In this direction QEC cannot be rejected; the local node will always force the application to quiesce after presenting it with a Status-Control(QEC) by rejecting further attempts to send inbound data. When the application has quiesced, it should send a Status-Control(QC) Request to the local node, which sends a QC Request to the host. The application may subsequently be released by an RELQ Request from the host, which the local node presents to the application as a Status-Control(RELQ) Request.

The receipt of a CLEAR or UNBIND BIND sequence (Close(PLU) Open(PLU)) causes the quiesced state to be released.

Figures 3.3.42 through 3.3.44 illustrate the quiesce protocols between the local node and the application and how those protocols relate to the underlying SNA protocols.

Figure 3.3.40.    The host sends SHUTD while the application is sending in In-Bracket state; the application completes the bracket, sends Status-Control(SHUTC) Request, and the host terminates the PLU session by sending UNBIND. The local node closes the PLU connection.

Figure 3.3.41.    The host sends SHUTD while the application is sending in In-Bracket state; the application completes the bracket, sends Status-Control(SHUTC) Request, and then the host releases the application from the quiesced state by sending RELQ. The local node sends a Status-Control(RELQ) Request to the application, which initiates a new bracket.

Figure 3.3.42.    The application quiesces the host and then releases the quiesce.

Figure 3.3.43.    The application attempts to quiesce the host, but the host rejects the quiesce and continues with the next chain.

Figure 3.3.44.    The host sends QEC while the application is sending a chain; the application completes the chain and sends Status-Control(QC) Request. The host releases the quiesce by sending RELQ, and the local node sends a Status-Control(RELQ) Request to the application, which then initiates a new chain.


3.3.12  Recovery
The Function Management Interface (FMI)	23 of 37

3.3  The PLU Connection

3.3.12  Recovery

This section covers the following issues to do with error recovery:

Application CANCEL

Direction after receiving a negative response

Direction after sending a negative response

Critical failure

RQR and CLEAR

STSN (Set and Test Sequence Numbers)

Failure of the link service, local node, or client computer

Application Cancel

One of the parameters on the Open (PLU) OK Response, which the application sends to the local node, specifies whether the application will generate CANCEL (or EC) to terminate an inbound chain that has received a negative response. If this option is not selected, the local node will generate a CANCEL request when it receives a negative response from the Host to an incomplete chain.

Direction After Receiving a Negative Response

Within the local node, error recovery for a half-duplex application (as specified by byte 7 bit 2 of the BIND) is assumed to be the responsibility of the Host. However, the application must be aware of the fact that an error recovery state has been entered in order to obey the direction protocol.

When an application using half-duplex protocols (flip-flop or contention) receives a negative response to an inbound chain that it sent that does not refer to a race, it must assume receive state. The sense codes used for race conditions that do not require the transition to receive state are:

0x080B	Bracket race error
0x081B	Receiver in transmit mode
Direction After Sending a Negative Response

When an application using half-duplex flip-flop protocol sends a negative response to an outbound chain (or sends a Status Ack (ACK) to a DATAFMI message with SDI set) that does not refer to a race, the application must assume an "error recovery pending" state. The sense codes used for race conditions that do not require the transition to "error recovery pending" state are:

0x080B	Bracket race error
0x0813	Bracket bid reject (no RTR forthcoming)
0x0814	Bracket bid reject (RTR forthcoming)
0x081B	Receiver in transmit mode
The application must therefore examine the sense code on an SDI message to detect such races.

Error recovery pending state differs from receive state only in one respect. The application may convey sense information to the host using Status-Control (LUSTAT) — see section 3.3.14. The LUSTAT must not have the CD or EB flags set (the host already has direction, and the bracket must not be terminated prematurely by the application). SNA Server also allows the FMI application to send Status-Control (LUSTAT) in receive state (see section 3.3.14).

An application using the half-duplex contention protocol does not have an "error recovery pending" state and must enter contention state whenever it sends a negative response.

Note that if the chain is canceled by the host with CD on the CANCEL, the application must assume send state.

Critical Failure

When an application makes a protocol error in sending data, the local node will reject the data using a Status-Ack (NACK-2) with a sense code indicating the reason for failure. The NACK-2 has a critical failure flag that indicates whether the local node has marked the session as unrecoverable. The sense codes are listed in Chapter 5.

If the error is noncritical, the application can proceed as if the message that caused the error had not been sent. If the error is critical, then the local node will issue a Close (PLU) Request to the application (providing that the PLU connection is open), which will mean that the application cannot communicate on the PLU-SLU session until an UNBIND — BIND sequence is received from the Host. The local node will also send a TERM-SELF Request to the Host in order to elicit an UNBIND; therefore, the application does not need to issue a LOGOFF request on the SSCP session.

RQR and CLEAR

An application using TS Profile 4 may request the session to be recovered by sending Status-Control (RQR); the local node presents this to the Host as an RQR Request. Note that, if the application has received a critical Status-Acknowledge (Nack-2), this option cannot be taken because the local node will send a Close (PLU) Request immediately following the Nack-2 to the application, and the PLU connection will no longer be valid. The RQR message requests the Host to reset the session by sending a CLEAR Request (see Figure 3.3.45 below).

The receipt of CLEAR causes the application to reset its session state to that following the BIND (that is, the Open (PLU)).

Another way for the application to deal with error conditions is to ask for an UNBIND by sending Status-Control (RSHUTD) (see section 3.3.13). Note that this may not require the Host to supply a new BIND, depending on the host configuration. A new SSCP request may be required (such as LOGON).

Figure 3.3.45.    The application requests recovery by issuing Status-Control (RQR); the Host sends CLEAR, and the application must reset its session to state that it was in following the BIND (Open (PLU)). In this case, this means that the application is now between brackets and awaiting SDT.

STSN

STSN (Set and Test Sequence numbers) is used on sessions with TS Profile 4 in order for applications to maintain transaction processing sequence numbers between sessions. This allows both partners on the session to discover the amount of data lost after a CLEAR or UNBIND-BIND sequence.

The STSN message is the only one that can reset such transaction processing sequence numbers; BIND, UNBIND and CLEAR do not affect them.

If the application wishes to maintain such transaction numbers, it must specify the APPLTRAN option in the Open (PLU) OK Response. The Host can send STSN after a BIND or CLEAR before sending SDT in order to set and/or test the application's transaction numbers. The local node resets its internal session sequence numbers to zero on receipt of BIND or CLEAR. When the local node receives an STSN specifying SET (or SET and TEST) for one half-session, it resets the corresponding internal session sequence number.

Unless both half-session actions are "ignore" (the action byte is X'00'), the STSN request is passed to the application (provided that it specified APPLTRAN), with the action byte and the two sequence numbers from the request, as a Status-Control (STSN) (see section 4.9). The application must examine the action byte in order to determine whether the action is ignore, set, test, or set and test. The application must send a positive response (Status-Control (STSN) Ack) to the STSN, with the sensed sequence numbers if required (sense or set and test). The local node is responsible for generating the correct result code for the STSN RSP (see the SNA Reference Summary).

Note that the application should perform the sense part of STSN first (by examining bits 0 and 2 of the action byte for the secondary-to-primary flow and primary-to-secondary flow respectively). The set part of the STSN is then performed (by examining bits 1 and 3 of the action byte).

The application should increment its transaction numbers when sending and receiving normal flow RUs from the Host (note that Status-Control messages corresponding to normal flow DFC requests cause the transaction numbers to be incremented). The sequence number is reported on DATAFMI messages and Status-Acknowledge messages. The application should be aware that, if a message from the host fails receive checks (and is converted to an SDI message), SNAP-2.1 will purge the remainder of the chain from the Host, and the application may miss some sequence numbers. Therefore, the application should reset its primary-to-secondary transaction number from the next outbound data after processing an SDI message.

Note that the second application flag byte is not valid for Status-Control (STSN); it is used for the STSN control byte.

Link Service Failure

When the server running a link service fails, the local node is informed of this; it treats the problem as a link outage with outage code 0x0D. This is reported to any active 3270 emulation sessions as a communications check code (-+z_nnn). The local node will attempt periodically to reconnect to the link service.

Local Node Failure

If the local node fails, applications are informed of this by the "path error" return code from the DMOD on the SBPURCV call (see Chapter 2), or from the routing procedure. All connections that use the destination locality value for which the path error is reported are closed. The application must:

Tidy up resources related to the closed connections, including resetting presentation spaces and displaying a communications check code (-+z_nnn) on the status line.

Attempt to re-establish connection with a local node by reinitiating the resource location process.

Client Failure

If the client computer fails, the local node will terminate the application's PLU-SLU session (if it is active) by sending TERM-SELF. The SSCP and PLU connections are both marked as closed and cannot be reused without being re-opened. Internally, the local node treats such a failure in the same way as the receipt of a Close (SSCP) Request from the application.


3.3.13  Application-Initiated Termination
The Function Management Interface (FMI)	24 of 37

3.3  The PLU Connection

3.3.13  Application-Initiated Termination

An application on a session with FM profile 3 or 4 may request termination of the PLU session. It should only do so if it has previously ensured that it is in a state where the PLU session can be terminated, that is, Between-Chain and Between-Bracket. Terminating the PLU session does not affect the state of the SSCP session.

Note that an application may issue a character coded or field formatted LOGOFF command on the SSCP session or send Close (PLU) to get the local node to send TERM-SELF on the application's behalf. All of these will elicit an UNBIND, either immediately or after session tidy up in the host.

The application requests termination of the PLU session by sending a Status-Control(RSHUTD) Request to the local node, which generates an SNA RSHUTD Request to the host.

After sending the Status-Control(RSHUTD) Request, the application must remain capable of accepting and responding to all outbound data it receives. The application may now expect one of two messages, depending on whether the state of the PLU session allows it to be terminated and whether the host wishes to terminate the PLU session:

If the state of the PLU session allows it to be terminated, and the host wishes to terminate the PLU session, the host generates a positive Response to the RSHUTD Request, which may be followed by an UNBIND Request. The local node closes the PLU connection; see section 3.3.2 and Figure 3.3.46 below.

If the state of the PLU session does not allow it to be terminated (for example, if the session is In-Bracket), or the host does not want to terminate the PLU session at this time, the host generates a negative Response to the RSHUTD Request, which the local node presents to the application as a Status-Control(RSHUTD) Nack-1 carrying the sense codes supplied on the negative Response. This indicates that the request to terminate the PLU session has been rejected by the host, and communication on the PLU session continues unaffected. See Figure 3.3.47 below.

Figures 3.3.46 and 3.3.47 illustrate the application-initiated termination protocol between the local node and the application and how this protocol relates to the underlying SNA protocols.

Figure 3.3.46.    The application requests termination of the PLU session, and the host sends UNBIND. The local node closes the PLU connection.

Figure 3.3.47.    The application requests termination of the PLU session, but the session is not in an appropriate state. The host sends a negative Response to the RSHUTD Request, which the local node presents as Status-Control(RSHUTD) Nack-1. Communication continues on the PLU session.


3.3.14  LUSTATs
The Function Management Interface (FMI)	25 of 37

3.3  The PLU Connection

3.3.14  LUSTATs

The DFC LUSTAT message is used within SNA to convey four bytes of sense data to the other session partner. It can also be used simply to send an RH to the other session partner (for example, to open a bracket; see Figure 3.3.20 and Figure 3.3.23). The message flows on the normal flow and so is subject to direction restrictions; however, it may be sent (without EB or CD) on a half-duplex flip-flop session that is in error recovery pending state (see section 3.3.12).

The local node allows the application to send Status-Control (LUSTAT) requests at any time that data traffic is active, except while sending data in chain. If the application is in a receiving state (using half-duplex protocol), the LUSTAT is queued up and used to  provide the sense codes, which are filled into the next outbound request, and the SDI flag is set. The application may therefore present the sense codes for an error state without waiting for the next outbound data if required.

The first byte of sense data must be X'08' in order to generate a DATAFMI message with SDI (to be converted to a negative response). Other LUSTATs are left queued on the session until they can be sent.

If multiple Status-Control (LUSTAT) messages are sent by the application while in a receive state, the local node will queue them all. Once outbound data has been delivered to the application with SDI set, as indicated above, and the application has converted it to a Status Ack (ACK), the local node will send the negative response and the remaining LUSTATs (which can now flow since the half-duplex flip-flop state is error recovery pending).

If the application intends to send multiple Status-Control (LUSTAT) messages to the Host, there is the possibility that the Host will attempt to initiate recovery before the last LUSTAT has been sent; in this case, the error recovery chain will be rejected by the next LUSTAT.

Note that the application may send Status-Control (LUSTAT) Request with or without ACKRQD; the local node will map these to RQD and RQE LUSTATs respectively.

Figures 3.3.48 through 3.3.50 illustrate the use of Status Control LUSTATs by an application using the half-duplex flip-flop mode.

Figure 3.3.48.    The application issues Status Control LUSTAT when it has direction.

Figure 3.3.49.    Application sends Status Control LUSTAT request when receiving data between chain. Next outbound data is delivered with SDI set which gets converted to negative RSP.

Figure 3.3.50.    Application sends several Status Control LUSTAT requests when receiving data in chain. Next outbound data is delivered with SDI set which gets converted to negative response. Subsequent LUSTATs are sent to Host.


3.3.15  Response Time Monitor Data
The Function Management Interface (FMI)	26 of 37

3.3  The PLU Connection

3.3.15  Response Time Monitor Data

For a 3270 display application, the local node maintains statistics on host response times — the time it takes the host to respond after the 3270 user presses ENTER or an AID key to send data to the host. These statistics can then be sent to the host for analysis.

The Status-RTM message, sent by the local node to the application, informs the application of the Response Time Monitor parameters specified by the host (see section 3.2.4 for more information). These parameters specify whether RTM data is to be collected, whether the application is permitted to display RTM statistics locally, the time boundaries by which response times are to be grouped, and the definition of response time. The time may be measured until the first character of the host response reaches the screen, until the keyboard is unlocked, or until the user can send further data (CD or EB received by the application).

If the host specifies that response times are to be measured for this session, the application is responsible for measuring response times and for reporting them to the local node. This involves:

Starting a timer when the user presses the ENTER key, or an AID key, to send data to the host.

Stopping the timer when the host's response to the inbound data is received, as defined by the RTM definition specified on the Status-RTM message.

Reporting the response time to the host on the Status-Acknowledge message, which acknowledges the host's response. One of the fields on this message specifies the last response time measured by the application, or specifies that no response time is to be reported. (See section 4.8 for details of the message format.)

Optionally displaying the most recent response time as a Last Transaction Time Indicator (LTTI) on the 3270 emulation status line.

If the application wishes to provide a local display of RTM data, it is responsible for maintaining its own response time statistics. It should use the same definition and boundaries as those specified on the Status-RTM message to ensure that the local data matches the data sent to the host by the local node. Note that the Status-RTM message may indicate that a local display of response times is not permitted; in this case, the application should not display either the response times or the LTTI.


3.4  Data Flow
The Function Management Interface (FMI)	27 of 37

3.4  Data Flow

3.4.1  Outbound Data

This section describes the outbound data flows from the local node to the application. The overall structure of the protocols described applies to the SSCP and PLU connections, but certain features (such as the use of delayed request mode) are only applicable to the PLU connection.

The local node presents data originating at the host to the application on different connections, depending on the SNA session on which the data flows, as follows:

FMD NS(session services) data and FMD data originating at the host SSCP and directed to the SNA Server LU is sent to the application on the SSCP connection.

FMD data originating at the host PLU and directed to an SNA Server LU is sent to the application on the PLU connection.

For all connections, only FMD Requests are presented to the application as data messages (that is, with message-type = DATAFMI). DFC and Session Control Requests are used to generate Status-Control messages (see section 3.5.2).

The local node performs the Data Flow Control state changes required by the RH indicators in the Request, before sending a data message to the application.

The SNA Request TH (Transmission Header) and RH indicators are not available to the application on outbound data messages. Instead, the local node provides application flags in the data message header, which reflect the settings of a subset of the RH indicators, but interpreted by the local node to shield the application from the more obscure aspects of chaining and bracket usage. See section 3.1.2 for a description of the available flags and the way in which the local node uses them on outbound data.

For outbound data, the first byte is RU[0] for standard FMI, and TH[0] for the LUA variant of FMI.

All data messages from the local node to an application contain a message key. The local node maintains a unique message key sequence for each outbound data flow to an application. When the local node sends a data message to an application on a particular connection, it places the next message key in the outbound sequence into the message header, sets the application flags (see section 3.1.2), and sends the message to the application. This means that the message key uniquely identifies a data message on a particular connection between the local node and the application. Note that the local node also places message keys on outbound Status-Control Requests.

The acknowledgment protocol enforced by SNA Server reflects the chain response protocol and request mode in use on the SNA session, as follows:

Outbound RQD Requests generate data messages with ACKRQD set in the message header.

Outbound RQE Requests generate data messages without ACKRQD set.

Outbound RQN Requests generate data messages without ACKRQD set.

If the session uses primary immediate request mode, a data message with ACKRQD set must be acknowledged by the application before further data messages will be received.

If the session uses primary delayed request mode, a data message with ACKRQD set need not be immediately acknowledged by the application; data messages will continue to be received.

Note that SNA Server enforces the equivalent of immediate response mode for the outbound data acknowledgment protocol for all connections. That is, the application must send acknowledgments in order.

If the local node sets the ACKRQD field in the message header of a data message to the application, it indicates that an acknowledgment to this data message is required. The application acknowledges an outbound data message by sending a Status-Acknowledge message to the local node on the same connection, which contains the same message key and sequence number fields as the data message.

On receipt of a Status-Acknowledge (Ack), the local node correlates the message key with outstanding outbound messages and generates an SNA positive Response to the appropriate SNA Request.

The application should use the Status-Acknowledge(Nack-1) message as a negative acknowledgment. On receipt of a Status-Acknowledge(Nack-1), the local node correlates the message with outstanding outbound messages and generates an SNA negative Response plus sense data to the appropriate SNA Request. The application supplies the sense data that should accompany the negative Response as part of the Status-Acknowledge(Nack-1) message and must include the same message key, application flags, and sequence number fields as the data message to which this is a negative acknowledgment.

Status-Control messages caused by expedited-flow requests may be sent at any time and do not affect the sending of positive or negative acknowledgment to normal flow outbound data messages. The fact that they can occur between an outbound data message and the matching Status-Acknowledge message is purely coincidental. See section 3.5.2 for details of which Status-Control messages correspond to SNA Requests.

If errors are detected in the format of a normal flow Request from the host or the Request is inappropriate for the state of the session, the local node generates an error data message for the application with the following characteristics:

The SDI and ECI application flags are set.

The sense code associated with the error occupies the first four bytes of the data message (see section 4.7).

ACKRQD is set.

The application should return a Status-Acknowledge(Ack), and the local node generates a negative response carrying the sense code appropriate to the detected error. This mechanism:

Informs the application of the detected error.

Allows the application to respond to any previously received data before the local node sends the negative response to this data message.

On sessions where the application is receiving a series of RQE chains, the local node will be retaining correlation information for each chain (in case the application wishes to send negative responses to any of the chains). If the local node runs out of correlation table entries, it will attempt to allocate more entries and (if this fails) will be forced to terminate sessions. To prevent this, the application should provide Status-Acknowledge(Ack) messages for RQE data that it does not wish to reject in this case; a response after five consecutive RQE chains should be sufficient. Such messages are referred to as ‘courtesy Acks' and do not give rise to a response to the Host but merely free internal correlation data.

Figures 3.4.1 through 3.4.6 below illustrate the data acknowledgment protocol enforced between the local node and the application and show the effects of the application generating positive and negative Status-Acknowledge messages.

The figures show:

The relevant RH flags in SNA Requests/Responses.

The sequence number of SNA Requests/Responses.

Any sense data (shown as "SENSE=...") on SNA Requests/Responses and Status-Acknowledge messages.

The ACKRQD field in data messages.

The message key field in data messages.

For simplicity all messages are assumed to be FM data flowing on the same PLU session.

Figure 3.4.1.    The application accepts a data message corresponding to a definite-response RU.

Figure 3.4.2.    The application accepts a data message corresponding to a multi-RU definite-response chain.

Figure 3.4.3.    The application rejects a data message corresponding to a definite-response chain.

Figure 3.4.4.    The application rejects a data message corresponding to a multi-RU definite-response chain.

Figure 3.4.5.    The local node enforces immediate response mode, that is responses must be sent in sequence. The application rejects the second exception-response chain and accepts the definite-response chain, which implies acceptance of the third exception-response chain.

Figure 3.4.6.    The local node detects a chaining error (RQD but not EC) in data destined for the application (this example requires the receive check X'4007' to be in force — see section 3.2.1).


3.4.2  Inbound Data
The Function Management Interface (FMI)	28 of 37

3.4  Data Flow

3.4.2  Inbound Data

This section describes inbound data flows from the application to the local node. The overall structure of the protocols described applies to the SSCP and PLU connections, but more complex aspects (such as the use of delayed request mode) are only applicable to the PLU connection.

The application can send inbound data on any of the three connections, as follows:

FMD NS(session services) and FMD character-coded data intended for the host SSCP should be sent to the local node on the SSCP connection.

FMD data intended for the host PLU should be sent to the local node on the PLU connection.

The application cannot use data messages to send DFC or Session Control Requests to the host. Instead it must use Status-Control messages (see section 3.5.2 for further details).

For all three connections, the application must fill in certain key fields in the data message's header (see Chapter 4 for full details of the data message format). In particular it must:

Set the message-type to DATAFMI.

Allocate a new message key for inbound data messages on this connection.

Set the ACKRQD field if required (see below).

Set the application flags (see section 3.1.2).

The nxtqptr, hdreptr and numelts fields in the message header, and the elteptr and startd fields in the message elements are set up by SNA Server's buffer management routines (see Chapter 2). The application is responsible for setting the endd field.

Where the application does not have access to these routines (for example, where the operating environment does not support inter-task procedure calls and shared memory), all the fields in the header must be set by the application.

The TH and RH indicators are not available to the application on inbound data messages. The application should set the appropriate application flags in the message header to control chaining, direction etc. — see section 3.1.2 for a description of the available application flags for inbound data and later sections in this chapter for a description of how the flags are used to control inbound data flows.

For inbound data, the first byte is RU[0] for standard FMI.

The message key supplied by the application in the inbound data message header is used by the local node to indicate which data message on this connection an outbound Status-Acknowledge refers to. The application should maintain a unique message key sequence for the inbound data flow on each connection it has with the local node, so that the application can use the message key to correlate inbound data messages and outbound Status-Acknowledge messages on the connection. Note that the application must also provide a message key on Status-Control Requests in order to differentiate between multiple RQE LUSTAT messages.

The inbound data acknowledgment protocol reflects the secondary chain response protocol and request mode in use on the session, as follows:

Inbound data messages with ACKRQD set in the header generate RQD Requests.

Inbound data messages without ACKRQD set in the header generate RQE or RQN Requests depending on the chain response protocol.

The application should only set ACKRQD on data messages that have the ECI (End Chain indicator) application flag set.

If the session specifies that the secondary uses immediate request mode, the application can still send further data messages after sending data with ACKRQD set, even though it has not received a Status-Acknowledge message for that data message. The messages are queued within the local node and are progressively sent as positive Responses are received.

If the session specifies that the secondary uses delayed request mode, then after sending a data message with ACKRQD set the application can continue to send data messages.

If the application sets the ACKRQD field in the message header of a data message, it indicates that it requires an acknowledgment to this data message. The local node acknowledges an inbound data message by sending a Status-Acknowledge message to the application on the same connection and using the same message key as the data message (see Figure 3.4.7).

The local node processes inbound data messages from the application through its internal state machines, assigns the correct SNA sequence number or an identifier for this flow, and sends the data in a Request to the host. The chain-response type of the Request depends on whether ACKRQD was set in the data message and the session parameters.

The local node maps a positive Response from the host to a Status-Acknowledge(Ack) to the application. The application can use the message key in the Status-Acknowledge to correlate the acknowledgment with the original data message. Therefore, receipt of a Status-Acknowledge(Ack) for a particular data message implies that the local node has received a positive SNA Response from the host to the inbound SNA Request
(see Figure 3.4.8).

Note that responses are absorbed on the SSCP-PU session.

Note that outbound Status-Acknowledge(Ack) messages contain application flags and a sequence number. The application flags reflect the RH indicators in the Response. The sequence number is the SNA sequence number from the Response, and provides a mechanism for applications using TS profile 4 to track the SNA secondary sequence number corresponding to a "unit of work."

The local node maps a negative Response from the host to a Status-Acknowledge(Nack-1) message to the application. The application can use the message key in the Status-Acknowledge to correlate the negative acknowledgment with the original data message. The outbound Status-Acknowledge(Nack-1) message contains the SNA sense codes and sequence number from the negative Response (see Figure 3.4.9 and Figure 3.4.10).

If the local node detects an error in the format of an inbound data message, or the data message is not appropriate to the current state of the session, it sends a Status-Acknowledge(Nack-2) to the application containing an error code (see section 5.2 for a list of error codes). The local node does not send a Request to the host corresponding to the data message in error and does not advance the SNA sequence number for the session. The application can use any message key in its next inbound data message (assuming the error does not cause a "critical failure").

An example of a (serious) chaining error, where the application sends a data message with ACKRQD but without ECI in the application flags, is shown in figure 3.4.11. Note that after detecting this particular error, the local node marks the application's connection as "critically failed," closes the connection, and sends a TERM-SELF Request to the SSCP to elicit an UNBIND (see section 3.3.12, "Recovery").

Inbound Status-Control messages, which cause the generation of expedited-flow requests, may be sent at any time and do not affect the sending of a positive or negative acknowledgment to inbound data messages. See section 3.5.2 for details of which Status-Control messages correspond to SNA expedited-flow Requests.

Figures 3.4.7 through 3.4.11 illustrate examples of the inbound data acknowledgment protocols (and the underlying SNA protocols) for different chain-response types and secondary session request modes.

The figures show:

The ACKRQD field on data messages.

The message key on data messages.

Any relevant application flags on data messages.

Error codes (shown as "ERROR=...") on data messages.

Relevant RH flags in SNA Requests/Responses.

Sequence numbers in SNA Requests/Responses.

Sense codes (shown as "SENSE=....") on SNA Requests/Responses.

For simplicity all messages are assumed to be flowing on the same PLU session.

Figure 3.4.7.    The application successfully sends a data message.

Figure 3.4.8.    The application successfully sends a chain of data messages.

Figure 3.4.9.    The host rejects a chain of data messages.

Figure 3.4.10.    The host rejects the first definite-response chain and rejects the third exception-response chain on a delayed request session. Note that the negative response to the third chain implies a positive response to the second chain.

Figure 3.4.11.    The local node detects the application's invalid use of ACKRQD without the ECI application flag on a data message. Note that no data is sent to the host; however, since the error is "critical," the local node will send a TERM-SELF message to the SSCP.


3.4.3  Inbound Data from LUA Applications
The Function Management Interface (FMI)	29 of 37

3.4  Data Flow

3.4.3  Inbound Data from LUA Applications

As shown in the previous section, the local node performs certain checks on data supplied by a client application before sending it to the host and rejects it with a Status-Acknowledge(Nack-2) message if the checks fail; it does not return any acknowledgment to the application if the data passes the checks (although the host may do so later).

Where the client application is providing an LUA API, the design of the API may require that an LUA verb sending data inbound to the application does not complete until the local node has checked the data. Because of this, the local node will always respond to a client application that uses the LUA variant of the FMI, after it has completed its send checking of the inbound message; this allows the client application to complete processing of the LUA verb and return control to the LUA application program.

If the inbound message passed the local node's send checks and will be sent to the host, the local node sends an ACKLUA message to the client application to indicate this; the client application can then complete the LUA verb processing with an OK return code. Note that the ACKLUA message does not imply that the data was successfully sent to the host or that the host received it; it may later be followed by a Nack-1 message indicating that the host rejected the data.

If the inbound message fails the local node's send checking, a Nack-2 message will be returned as for non-LUA client applications. The client application can then report this to the LUA application program by a non-OK return code to the LUA verb that sent the message.

If the client application is providing an LUA API, it should therefore wait for either ACKLUA or Nack-2 to determine whether to return an OK or error return code to the LUA send verb. If this dependence on the local node's send checks is not required, the client application can ignore the ACKLUA message.

Note that there are certain race conditions in which the local node cannot complete its send checks before replying to the client application. In these cases, the local node returns an ACKLUA, but may subsequently send a Nack-2 if it detects an error during the remaining send checks. The client application may therefore receive an ACKLUA followed by a Nack-2 for the same inbound message.

In the TH for the LUA variant of FMI, the expedited flow indicator (EFI), the destination-address field (DAF), and the origin-address field (OAF) are used. Other fields (including the sequence number field) are ignored. In the RH for the LUA variant of FMI, all fields except the queued-response indicator (QRI) and pacing indicator (PI) are used.

For inbound data, the first byte is TH[0] for the LUA variant of FMI.

Figures 3.4.12 through 3.4.14 illustrate the ACKLUA acknowledgment protocol for different messages that the application can send.

Figure 3.4.12.    The application sends a data message that passes the local node's send checks.

Figure 3.4.13.    The application sends a Status-Acknowledge (Ack) message that passes the local node's send checks.

Figure 3.4.14.    The application sends a Status-Acknowledge (Nack-1) message that passes the local node's send checks.


3.5  Status Messages
The Function Management Interface (FMI)	30 of 37

3.5  Status Messages

The local node uses Status messages to provide the application with information about the state of its sessions and to give the application control (in association with the host SSCP and PLU) over the progress of the session. The status messages are designed to allow the application to use all the protocols allowed in the FM and TS Profiles supported by the SNA Server local node.

Most applications only need use a subset of the available Status messages — for example, a 3270 device emulator would not require the Status messages used in quiesce protocols.


3.5.1  Status-Acknowledge
The Function Management Interface (FMI)	31 of 37

3.5  Status Messages

3.5.1  Status-Acknowledge

Status-Acknowledge messages are the basic mechanism used to enforce inbound and outbound data acknowledgment protocols on all three connections. See sections 3.4.1 "Outbound Data"and 3.4.2 "Inbound Data" for details of the use of Status-Acknowledge messages.

For a 3270 emulation application, Status-Acknowledge messages sent from the application to the local node (acknowledging outbound data from the host) can also carry information on host response times. This allows the local node to maintain response time statistics for sending to the host when required. See section 3.3.15, "Response Time Monitor Data," for details.


3.5.2  Status-Control
The Function Management Interface (FMI)	32 of 37

3.5  Status Messages

3.5.2  Status-Control

Status-Control messages provide access to Session Control and Data Flow Control protocols on the PLU session using the PLU connection; they are not used on either of the other connections. Status-Control messages map directly to the equivalent SNA Session Control and Data Flow Control RUs.

All Status-Control messages that correspond to SNA Requests on the normal flow with the exception of LUSTAT sent RQE and Status-Control messages corresponding to CLEAR and STSN Request on the expedited flow have the ACKRQD (Acknowledgment Required) field set. Status-Control messages that correspond to SNA Requests on the expedited flow (with the exception of CLEAR and STSN) do not have the ACKRQD field set by the local node. However, the application may set ACKRQD when sending these Status-Control messages. Figure 3.5.7 summarizes which Status-Control( ) Requests always have ACKRQD set.

If a Status-Control( ) Request has ACKRQD set in the message header, then the recipient must supply a Status-Control( ) response (i.e. Ack, Nack-1 or Nack-2) before the sender sends further data messages or further Status-Control( ) Requests on the flow; the sender can still send Status-Control( ) responses, Status-Acknowledge, Status-Error, and Status-Resource messages on the flow. This applies to both normal and expedited flows and all request modes (including delayed-request mode). The message key received on the Request must be returned on the Response (this is to allow multiple RQE LUSTAT messages to be outstanding). The local node increments the message key on Status-Control Requests and DATAFMI messages that it sends to the application on the PLU connection.

For the LUA variant of the FMI, the message key field is used in a different way, as follows:

For inbound expedited flow requests, the local node sets the SNA sequence number to the value supplied by the application in the message key field. The application must ensure that this field is set to the correct sequence number.

For inbound Status-Control responses, the local node sets the SNA sequence number to the value supplied by the application in the message key field. The application must ensure that this field is set to the sequence number of the request for which a response is being sent.

Except in the case of Status-Control (LUSTAT), if a Status-Control( ) Request does not have ACKRQD set then the application should not reply, since a positive response will have already been sent by the local node.

For example, if the application sends a Status-Control(QC) Request with ACKRQD set (corresponding to an SNA Request on the normal flow), this blocks further data and Status-Control ( ) Requests corresponding to the inbound normal flow until the Status-Control(QC) response is received. It does not block other messages on the normal flow, or messages on the expedited flow; for example, the application could still send Status-Control(SIGNAL).

The receipt of the Status-Control response implies an acknowledgment to all outstanding messages (including data messages) on the flow.

The use of ACKRQD on Status-Control messages effectively enforces definite-response and immediate request mode. This is appropriate for:

Status-Control messages that correspond to the SNA Requests CLEAR and STSN (because the expedited flow is RQD).

Status-Control messages corresponding to all the DFC Requests (which are RQD) except LUSTAT (which can be RQE).

The application may set ACKRQD on Status-Control( ) Requests that correspond to SNA Requests on the expedited flow, even where ACKRQD is not required. For example, when an application is signaling for direction (for example, a 3270 emulator with a terminal operator repeatedly pressing the ATTN key), it may generate multiple Status-Control(SIGNAL) Requests, which would adversely affect the performance of other users. The application can set ACKRQD on the first Status-Control(SIGNAL) Request and ignore events that would cause further Status-Control(SIGNAL) Requests until the Status-Control(SIGNAL) response is received from the local node.

The message flows in figures 3.5.1 through 3.5.6 show outbound and inbound Status-Control sequences with and without ACKRQD and the corresponding SNA RUs:

Figure 3.5.1.    Application sends Status-Control(CHASE).

Figure 3.5.2.    Host sends BID Request.

Figure 3.5.3.    Application sends Status-Control(SHUTC).

Figure 3.5.4.    Host sends SNA SIGNAL Request.

Figure 3.5.5.    Host sends multiple RQE LUSTAT Request, application rejects the first one.

Figure 3.5.6.    Application sends Status-Control(LUSTAT) NOACKRQD.

Figure 3.5.7 below summarizes the Status-Control( ) Requests supported by the local node and SNA Session Control (SC) and Data Flow Control (DFC) Requests. For each Status-Control( ) request, the table gives:

The SNA category of the corresponding SNA Request (SC or DFC).

The flow used by the corresponding SNA Request (normal or expedited).

The TS or FM profiles on which the corresponding SNA Request is supported.

The directions for which it is valid (NODE <--> APPL).

Whether it requires ACKRQD; note that the application may set ACKRQD on a Status-Control( ) Request that does not require it.

The hexadecimal code used in the control-type field of the Status-Control( ) message (see chapter 4).

STATUS- CONTROL	SNA RQ FLOW	TS Profile	FM Profile	DIRECTION Node<>Appl	ACKRQD	CODE
CLEAR	SC,Exp	2,3,4	-	-->	ACKRQD	CCLEAR (X'01')
SDT	SC,Exp	3,4	-	-->	-	CSDT (X'02')
RQR	SC,Exp	4	-	<--	-	CRQR (X'03')
STSN	SC,Exp	4	-	-->	ACKRQD	CSTSN (X'04')
CANCEL	DFC,Norm	-	3,4,7	<-->	ACKRQD	CCANCEL (X'10')
LUSTAT	DFC,Norm	-	3,4,7	<-->	-	CLUSTAT (X'11')
SIGNAL	DFC,Exp	-	3,4,7	<-->	-	CSIGNAL (X'12')
RSHUTD	DFC,Exp	-	3,4,7	<--	-	CRSHUTD (X'13')
BID	DFC,Norm	-	3,4	-->	ACKRQD	CBID (X'14')
CHASE	DFC,Norm	-	3,4	<-->	ACKRQD	CCHASE (X'15')
SHUTC	DFC,Exp	-	3,4	<--	-	CSHUTC (X'16')
SHUTD	DFC,Exp	-	3,4	-->	-	CSHUTD (X'17')
RTR	DFC,Norm	-	3,4	<--	ACKRQD	CRTR (X'18')
QC	DFC,Norm	-	4	<-->	ACKRQD	CQC (X'20')
QEC	DFC,Exp	-	4	<-->	-	CQEC (X'21')
RELQ	DFC,Exp	-	4	<-->	-	CRELQ (X'22')
The following are used only with LUA (see section 3.1).

STATUS- CONTROL	SNA RQ FLOW	TS Profile	FM Profile	DIRECTION Node<>Appl	ACKRQD	CODE
CRV	SC,Exp	3,4	-	-->	ACKRQD	CCRV (X'05')
BIS	DFC,Norm	-	18	<-->	ACKRQD	CBIS (X'19')
SBI	DFC,Exp	-	18	<-->	ACKRQD	CSBI (X'1A')
Figure 3.5.7.    Summary of Status-Control( ) Requests.

The use of particular Status-Control( ) messages is described in later sections of this chapter, in the context of PLU session protocols such as chaining, brackets, recovery, and so on. See also section 4.9 for the formats of Status-Control messages.

Status-Control(...)ACKLUA

When an LUA application sends a Status-Control message inbound to the local node, the LUA verb used to send the message cannot complete until the local node acknowledges the message. Because of this, the local node will always respond to the LUA application after it has completed its send checking of the inbound message. If the inbound message passes the local node's send checks, and the corresponding SNA message will be sent to the host, the local node sends a Status-Control(..)ACKLUA message to the application to indicate this. Note that the ACKLUA message does not imply that the SNA message was successfully sent to the host, or that the host received it.

The format of the Status-Control(..)ACKLUA message is explained in section 4.7.5. Note that the use of the message key field in Status-Control(..)ACKLUA is different from other Status-Control messages; it contains the sequence number from the TH of the Status-Control message sent by the LUA application, not the message key.

If the inbound message fails the local node's send checking, a Nack-2 message will be returned as for non-LUA applications. (This is then reported to the LUA application by a non-OK return code to the LUA verb that sent the message.)

Figures 3.5.8 through 3.5.10 illustrate the ACKLUA acknowledgment protocol for different messages that the application can send.

Figure 3.5.8.    The application sends a Status-Control (..) Request message that passes the local node's send checks.

Figure 3.5.9.    The application sends a Status-Control (..) Ack message that passes the local node's send checks.

Figure 3.5.10.    The application sends a Status-Control (..) Nack-1 message that passes the local node's send checks.


3.5.3  Status-Error
The Function Management Interface (FMI)	33 of 37

3.5  Status Messages

3.5.3  Status-Error

Status-Error messages flow from the local node to the application to report "request reject" and "RH usage" error conditions for:

Errors in outbound expedited Data Flow Control (DFC) Requests.

Errors in outbound Session Control (SC) Requests.

Errors in inbound Responses.

The Status-Error message contains four bytes of error code information that contain the appropriate SNA sense codes for the detected error. See Chapter 4 for a description of the Status-Error message format and section 5.2 for a list of error codes.


3.5.4  Status-Resource
The Function Management Interface (FMI)	34 of 37

3.5  Status Messages

3.5.4  Status-Resource

Status-Resource messages flow between an application and the local node to enable the local node to pace the application's PLU session. They provide the local node with an indication of the buffer resources available at the application to receive outbound messages. With this information, the local node can determine when to send a pacing response (see section 3.3.9).

Note that flow control is an option; inbound pacing is handled by the local node, transparently to the application, and outbound pacing may be handled similarly. This is appropriate when only a limited number of messages flows from end to end of the SNA session between definite responses, such as with a 3270 screen.


3.5.5  Status-Session
The Function Management Interface (FMI)	35 of 37

3.5  Status Messages

3.5.5  Status-Session

Status-Session messages always flow from the local node to the application and provide information about changes in the state of the session. There are separate Status-Session flows for each connection between the application and the local node.

The local node uses only one Status-Session message on the PLU connection; this is the Status-Session(BETB) message, used to report when the PLU session returns to the between-bracket state after the application or the PLU initiated a bracket (see section 3.3.7, "Brackets").

The local node reports the activation and deactivation states of the SSCP session and PU-SSCP session using Status-Session messages. For example, it reports the receipt of an ACTLU request from the host SSCP using a Status-Session(LU-Active) message on the SSCP connection (see section 3.2, "The SSCP Connection").

By providing Status-Session messages rather than requiring the application to interpret the relevant information in the SNA Request, the local node shields the application from decisions affecting conditional state transitions and from the necessity for a detailed understanding of SNA protocols.

A Status-Session message contains a status code, and for some status codes, an additional status code that qualifies the meaning of the primary status code. For example, the Link-Error status code, which occurs on the SSCP connection, is qualified by a status code that reports the link outage code supplied by the Data Link Control layer of the local node. Applications such as 3270 device emulators use the qualifying status codes to display communications check codes (-+z_nnn) on the display's status line.

The Status-Session codes are summarized in section 5.1.


3.5.6  Status-RTM
The Function Management Interface (FMI)	36 of 37

3.5  Status Messages

3.5.6  Status-RTM

The Status-RTM message is used by the local node to inform the application of the RTM (Response Time Monitor) parameters being used by the host. It flows from the local node to the application on the SSCP connection and is sent only for 3270 display LUs (or LUs in a pool of display LUs).

The Status-RTM message is sent at the following times:

After the OK response to the Open(SSCP) message, to inform the application of the initial RTM parameters

When the RTM counters are reset, either due to a request from the host or when the local node sends unsolicited RTM data to the host

When any of the RTM parameters are changed by the host

See section 3.2.4 for more information on the use of the Status-RTM message and section 3.3.15 for more information on how the application supplies RTM data to the local node.


3.6  FMI Message Summary
The Function Management Interface (FMI)	37 of 37

3.6  FMI Message Summary

This section lists each of the messages used at the FMI and gives a reference to a section in the chapter where each message is described. The formats of the messages are given in Chapter 4.

For each message the direction of flow is indicated; IN means from the application to the local node, and OUT means from the local node to the application. The connection on which the message flows is also given.

Message	Direction	Connection	Reference
Open(SSCP) Request	IN	SSCP	3.2.1
Open(SSCP) OK Response	OUT	SSCP	3.2.1
Open(SSCP) Error Response	OUT	SSCP	3.2.1
Open(PLU) Request	OUT	PLU	3.3.1
Open(PLU) OK Response	IN	PLU	3.3.1
Open(PLU) Error Response	IN	PLU	3.3.1
Open(PLU) OK Confirm	OUT	PLU	3.3.1
Open(PLU) Error Confirm	OUT	PLU	3.3.1
Close(SSCP) Request	IN	SSCP	3.2.2
Close(SSCP) OK Response	OUT	SSCP	3.2.2
Close(PLU) Request	IN/OUT	PLU	3.3.2
Close(PLU) OK Response	IN/OUT	PLU	3.3.2
Data-FMI	IN/OUT	SSCP/PLU	3.4
Status-Acknowledge (ACK)	IN/OUT	SSCP/PLU	3.4, 3.3.10
Status-Acknowledge (NACK-1)	IN/OUT	SSCP/PLU	3.4, 3.3.10
Status-Acknowledge (NACK-2)	OUT	SSCP/PLU	3.4.2
Status-Control (CLEAR) Request	OUT	PLU	3.3.12
Status-Control (CLEAR) ACK	IN	PLU	3.3.12
Status-Control (CLEAR) NACK-1	IN	PLU	3.3.12
Status-Control (SDT) Request	OUT	PLU	3.5.2
Status-Control (RQR) Request	IN	PLU	3.3.12
Status-Control (RQR) ACK	OUT	PLU	3.3.12
Status-Control (RQR) NACK-1	OUT	PLU	3.3.12
Status-Control (RQR) NACK-2	OUT	PLU	3.3.12
Status-Control (STSN) Request	OUT	PLU	3.3.12
Status-Control (STSN) ACK	IN	PLU	3.3.12
Status-Control (STSN) NACK-1	IN	PLU	3.3.12
Status-Control (CANCEL) Request	IN/OUT	PLU	3.3.4, 3.3.5
Status-Control (CANCEL) ACK	IN/OUT	PLU	3.3.4, 3.3.5
Status-Control (CANCEL) NACK-1	IN/OUT	PLU	3.3.4, 3.3.5
Status-Control (CANCEL) NACK-2	OUT	PLU	3.3.5
Status-Control (LUSTAT) Request	IN/OUT	PLU	3.3.14
Status-Control (LUSTAT) ACK	IN/OUT	PLU	3.3.14
Status-Control (LUSTAT) NACK-1	IN/OUT	PLU	3.3.14
Status-Control (LUSTAT) NACK-2	OUT	PLU	3.3.14
Status-Control (SIGNAL) Request	IN/OUT	PLU	3.3.8
Status-Control (SIGNAL) ACK	OUT	PLU	3.3.8
Status-Control (SIGNAL) NACK-1	OUT	PLU	3.3.8
Status-Control (SIGNAL) NACK-2	OUT	PLU	3.3.8
Status-Control (RSHUTD) Request	IN	PLU	3.3.13
Status-Control (RSHUTD) ACK	OUT	PLU	3.3.13
Status-Control (RSHUTD) NACK-1	OUT	PLU	3.3.13
Status-Control (RSHUTD) NACK-2	OUT	PLU	3.3.13
Status-Control (BID) Request	OUT	PLU	3.3.7
Status-Control (BID) ACK	IN	PLU	3.3.7
Status-Control (BID) NACK-1	IN	PLU	3.3.7
Status-Control (CHASE) Request	IN/OUT	PLU	3.3.10
Status-Control (CHASE) ACK	IN/OUT	PLU	3.3.10
Status-Control (CHASE) NACK-1	IN/OUT	PLU	3.3.10
Status-Control (CHASE) NACK-2	OUT	PLU	3.3.10
Status-Control (SHUTC) Request	IN	PLU	3.3.11
Status-Control (SHUTC) ACK	OUT	PLU	3.3.11
Status-Control (SHUTC) NACK-1	OUT	PLU	3.3.11
Status-Control (SHUTC) NACK-2	OUT	PLU	3.3.11
Status-Control (SHUTD) Request	OUT	PLU	3.3.11
Status-Control (RTR) Request	IN	PLU	3.3.7
Status-Control (RTR) ACK	OUT	PLU	3.3.7
Status-Control (RTR) NACK-1	OUT	PLU	3.3.7
Status-Control (RTR) NACK-2	OUT	PLU	3.3.7
Status-Control (QC) Request	IN/OUT	PLU	3.3.11
Status-Control (QC) ACK	IN/OUT	PLU	3.3.11
Status-Control (QC) NACK-1	IN/OUT	PLU	3.3.11
Status-Control (QC) NACK-2	OUT	PLU	3.3.11
Status-Control (QEC) Request	IN/OUT	PLU	3.3.11
Status-Control (QEC) ACK	OUT	PLU	3.3.11
Status-Control (QEC) NACK-1	OUT	PLU	3.3.11
Status-Control (QEC) NACK-2	OUT	PLU	3.3.11
Status-Control (RELQ) Request	IN/OUT	PLU	3.3.11
Status-Control (RELQ) ACK	OUT	PLU	3.3.11
Status-Control (RELQ) NACK-1	OUT	PLU	3.3.11
Status-Control (RELQ) NACK-2	OUT	PLU	3.3.11
Status-Error	OUT	SSCP/PLU	3.5.3
Status-Resource	IN	PLU	3.3.9
Status-Session	OUT	SSCP/PLU	3.5.5, 5.1
Status-RTM	OUT	SSCP	3.2.4
The following messages are used for LUA only:

Message	Direction	Connection	Reference
Status-Acknowledge (ACKLUA)	OUT	SSCP/PLU	3.4.3
Status-Control (..) ACKLUA	OUT	PLU	3.4.3
Status-Control (CRV) Request	OUT	PLU	3.5.2
Status-Control (CRV) Ack	IN	PLU	3.5.2
Status-Control (CRV) Nack-1	IN	PLU	3.5.2
Status-Control (BIS) Request	IN/OUT	PLU	3.5.2
Status-Control (BIS) Ack	IN/OUT	PLU	3.5.2
Status-Control (BIS) Nack-1	IN/OUT	PLU	3.5.2
Status-Control (SBI) Request	IN/OUT	PLU	3.5.2
Status-Control (SBI) Ack	IN/OUT	PLU	3.5.2
Status-Control (SBI) Nack-1	IN/OUT	PLU	3.5.2


FMI: Message Formats
Chapter 4	1 of 32

FMI: Message Formats

This section describes the message formats for the Function Management Interface. The message formats are presented in a language-independent notation that is described below.

Details of the message format notation and key assumptions about the contents of the message formats are as follows:

Reserved indicates that the field is set to zero (for a numeric field) or all nulls (for names) by the sender of the message.

Undefined indicates that the value of the field is indeterminate. The field is not set by the sender and should not be examined by the receiver of the message.

Fields that occupy two bytes—such as opresid in Open(PLU) Request (see section 4.2)—are represented with the most arithmetically significant byte in the lowest byte address, irrespective of the normal orientation used by the processor on which the software executes. That is, the 2-byte value X'1234' has the byte X'12' in the lowest byte address. However, the following fields are exceptions:

srci and desti in buffer headers are stored in the local format of the application that assigns them (only the assigning application needs to interpret these values).

startd and endd fields in elements are always stored in lowbyte, highbyte orientation (the normal orientation of an Intel processor).

Messages are composed of buffers, consisting of a buffer header and zero or more buffer elements; see section 1.2 for more information on buffer formats.

Applications must assign unique Index values for every active LPI connection within the node. In particular, the Open(SSCP) request must be different from the source Index it sends in response to the Open(PLU). Additionally, 0 should not be used as an I value. An I value of 0 means that the sender of the message is inviting the recipient of the message to assign an I value.

The startd field in each element gives the offset of the first byte of data in the element after the trpad field.

For non-LUA applications, startd will either be 1 (data starts in the byte after the trpad field), 10 (9 bytes of padding are included between the trpad field and the start of the data), or 13 (12 bytes of padding are included between the trpad field and the start of the data).

For LUA applications, startd is 4 (3 bytes of padding between the trpad field and the start of the data) in the first element of a message and 13 (12 bytes of padding) in subsequent elements.

The extra bytes are used by the local node for additional header information; this avoids having to copy data into a new buffer when adding this information.

Because startd indicates the index into dataru starting from 1, not 0, the first byte of valid data will always be at dataru[startd-1].

If startd is greater than endd, there is no valid data in the message.

All fields within dataru are of type CHAR, except where the notes indicate otherwise.

Note that where a buffer element has a startd of 1, 10, or 13, this only applies to the initial element in the chain of elements, and subsequent elements in the chain have a startd of 1. Messages with two distinct linked element chains in the message formats (for example Open(PLU) Request/Response), have the startd field in the elements at the start of the chains as the value (1, 10, or 13) given in the message format, and the startd fields in all other elements as 1.


4.1  Open(SSCP)
FMI: Message Formats	2 of 32

4.1  Open(SSCP)

Open(SSCP) is used by the application to open the SSCP connection.


4.1.1  Open(SSCP) Request
FMI: Message Formats	3 of 32

4.1  Open(SSCP)

4.1.1  Open(SSCP) Request

Flow: NODE <--  APPL	Usage: SSCP

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to first buffer element
numelts	CHAR	Number of buffer elements - 2
msgtype	CHAR	Message Type - OPENMSG  (X'01')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner (see notes)
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
ophdr.openqual	CHAR	Open Qualifier - REQU (X'01')
ophdr.opentype	CHAR	Open Type - SSCPSEC (X'01')
ophdr.appltype	CHAR	Application Program Interface Type - FMI without chunking  (X'02') - FMI with chunking  (X'82') (see notes)
ophdr.opluno	CHAR	Logical Unit Number (see notes)
ophdr.opresid	INTEGER	Resource Identifier
ophdr.icreditr	INTEGER	reserved
ophdr.icredits	INTEGER	reserved
ophdr.opninfo1	CHAR	reserved
ophdr.opnpad1	CHAR	Open Force Type (see notes) - OPEN_TEST (X'00') - OPEN_FORCE (X'01')
Element 1
hdreptr->elteptr	PTRBFELT	Pointer to next buffer element
hdreptr->startd	INTEGER	Start of data in this buffer element - 1
hdreptr->endd	INTEGER	End of data in this buffer element
hdreptr->trpad	CHAR	reserved (1 byte)
hdreptr->dataru	CHAR[268]	Data RU, as follows:
dataru[0-9]		Source Name. Should be filled with blanks.
dataru[10-19]		Destination Name. Set to the LU you want to communicate with.
dataru[20]		Sense 4003 Flag
dataru[21]		Sense 4004 Flag
dataru[22]		Sense 4006 Flag
dataru[23]		Sense 4007 Flag
dataru[24]		Sense 4009 Flag
dataru[25]		Sense 400A Flag
dataru[26]		Sense 400B Flag
dataru[27]		Sense 400C Flag
dataru[28]		Sense 400D Flag
dataru[29]		Sense 400F Flag
dataru[30]		Sense 4011 Flag
dataru[31]		Sense 4012 Flag
dataru[32]		Sense 4014 Flag
dataru[33]		High Priority Indicator - HIGH (X'01') - LOW (X'02')
dataru[34]		LUA Supported Indicator - Supported (X'01') - Not Supported (X'00')
dataru[35-36]		Chunk size obtained from DMOD (see notes)
dataru[37]		Segment delivery option - Do not deliver RU segments  (X'00') - Deliver RU segments (X'01')
dataru[38]		HLLAPI session ID (see notes)
Element 2
hdreptr->elteptr->elteptr	PTRBFELT	Pointer to next buffer element - NIL
hdreptr->elteptr->startd	INTEGER	Start of data in this buffer element - 1
hdreptr->elteptr->endd	INTEGER	End of data in this buffer element
hdreptr->elteptr->trpad	CHAR	reserved
hdreptr->elteptr->dataru	CHAR[268]	Data RU, as follows:
dataru[0]		An ASCII string identifying the 3270 emulator (see notes)
Notes:

The message consists of a buffer header and two buffer elements.

The source L value, the destination LPI values, and the source name are reserved.

For a 3270 emulator, the source P value must be set to S3PROD (0x12), which identifies the application as a 3270 emulator. The destination name should be set to the LU name or pool name taken from the 3270 user record (right-filled with ASCII spaces if fewer than 10 characters).

An LUA application uses the source P value LUAPROD (0x1D). This is independent of the value of the LUA Supported Indicator (see below), which selects the LUA variant of the FMI.

The SNS4003 to SNS4014 fields together with the high priority indicator are referred to in the text (see section 3.2.1) as the SSCP Connection Information Control Block (CICB). A value of X'00' indicates that the DFC receive check corresponding to the sense code is not supported for this LU. A value of X'01' indicates that it is supported. Note that the corresponding send checks are always performed whatever these values.

The LU number is only used internally in the local node on the Open (SSCP) Request. It is generated from the destination name in the first element.

The Open Force Type field is used when resource-locating across more than one server and for automatic activation of connections when the application wishes to use an LU for which the connection is inactive. The application does not need to set this flag; it is used by the DL-Base. See section 3.2.1 for details.

The Application Program Interface Type field defines whether RU chunking is used from the local node to the application; this may be necessary if large RUs are being used. See section 3.3.9 for more information on FMI chunking; this feature is not yet supported in SNA Server but is described here for completeness because support is planned for a future version.

The Chunk Size field (at dataru[35]) is an integer value.

The Segment Delivery option specifies whether the local node should deliver segments of RUs to the application as soon as they are received or should assemble whole RUs before delivering them to the application. Segment delivery allows the application to update the user's screen as soon as data is received ("window shading"), which may result in a faster perceived response. See section 3.3.6 for more information. This option is required only when chunking is being used; it is included on this message so that the local node can calculate the initial chunk credit values on the corresponding PLU connection. The option must still be set on the Open (PLU) Response; the setting specified on that message will override the one specified here if there is a conflict. If this happens, the initial credit values may not be suitable.

The LUA Supported Indicator specifies whether the application uses the LUA variant of the FMI (see section 3.1).

If the element is shorter than (s+34) bytes, SNA Server assumes no LUA and no chunking. This ensures back-compatibility with previous versions of the local node software in which these options were not available.

The HLLAPI session ID is a single ASCII character that identifies the 3270 display session to which the OPEN(SSCP) applies. HLLAPI uses this to identify a particular 3270 presentation space to which an HLLAPI function refers; it is also referred to by 3270 as the session's short name, or by HLLAPI as the presentation space identifier (PS identifier). If the 3270 emulator does not support session IDs, this field should be set to zero.

The second element contains an ASCII string that you can use to identify the type of 3270 emulator, such as "Select SNA Server OS/2 3270." This string will be logged in the audit log file by the client's DL-Base and may also be seen in traces. The STARTD and ENDD fields must be set up to define the limits of this string.


4.1.2  Open(SSCP) Response
FMI: Message Formats	4 of 32

4.1  Open(SSCP)

4.1.2  Open(SSCP) Response

Flow: NODE  --> APPL	Usage: SSCP

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to first buffer element
numelts	CHAR	Number of buffer elements - 1
msgtype	CHAR	Message Type - OPENMSG  (X'01')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
ophdr.openqual	CHAR	Open Qualifier - RSPOK (X'02') - RSPERR (X'03')
ophdr.opentype	CHAR	Open Type - SSCPSEC (X'01')
ophdr.appltype	CHAR	Application Program Interface Type - X'02' (FMI application)
ophdr.opluno	CHAR	Logical Unit Number
ophdr.opresid	INTEGER	Resource Identifier
ophdr.operr1	INTEGER	Error Code 1
ophdr.operr2	INTEGER	Error Code 2
Element 1
hdreptr->elteptr	PTRBFELT	Pointer to buffer element - NIL
hdreptr->startd	INTEGER	Start of data in this buffer element - 1
hdreptr->endd	INTEGER	End of data in this buffer element
hdreptr->trpad	CHAR	reserved (1 byte)
hdreptr->dataru	CHAR[256]	Data RU, as follows:
dataru[0-9]		Source Name
dataru[10-19]		Destination Name
dataru[20-27]		Name of the local node that accepted the Open
dataru[28-35]		Name of the connection used by the LU
dataru[36-37]		The local node's internal identifier for the connection (see notes)
dataru[38]		The type of link service used by the connection:
		CESLINK	(03) - SDLC
		CESX25	(04) - X.25
		CESDFT	(10) - DFT
		CESTR	(11) - Token Ring
		CESTCPIP	(30) - TCP/IP
		CESRELAY	(31) - Frame Relay
		CESCHANL	(32) - Channel
		CESISDN	(33) - ISDN
		CESETHER	(34) - Ethernet 802.2
Notes:

The message consists of a buffer header and a single buffer element.

If the open qualifier is RSPERR, the error code is valid (see section 5.2), and the LPIs and names are undefined.

The LU number indicates the LU selected by the local node from the configuration data (see section 3.2.1).

When the Open(SSCP) is for an LU Group, the Source Name contains the name of the selected LU.

The connection identifier is an integer value. It uniquely identifies a particular connection on this local node; all sessions using the same connection will return the same identifier. This value is typically used when a link error is received on one session to determine which other sessions will be affected.


4.2  Open(PLU)
FMI: Message Formats	5 of 32

4.2  Open(PLU)

Open(PLU) is used by the local node to open the PLU connection with the application on receipt of a BIND command from the host.


4.2.1  Open(PLU) Request
FMI: Message Formats	6 of 32

4.2  Open(PLU)

4.2.1  Open(PLU) Request

Flow: NODE  --> APPL	Usage: PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to first buffer element
numelts	CHAR	Number of buffer elements - X'02'
msgtype	CHAR	Message Type - OPENMSG (X'01')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
ophdr.openqual	CHAR	Open Qualifier - REQU (X'01')
ophdr.opentype	CHAR	Open Type - LUSEC (X'02')
ophdr.appltype	CHAR	Application Program Interface Type - X'02' (FMI application)
ophdr.opluno	CHAR	Logical Unit Number
ophdr.opresid	INTEGER	Resource Identifier
ophdr.icreditr	INTEGER	Initial Credit for flow from Application to local node: 0 (no flow control)
ophdr.icredits	INTEGER	Recommended Initial Credit for flow from local node to Application:Pacing window + 1
ophdr.opninfo1	CHAR	Negotiable Bind Indicator - Bind is not negotiable (X'00') - Bind is negotiable (X'01')
Element 1
hdreptr->elteptr	PTRBFELT	Pointer to buffer element
hdreptr->startd	INTEGER	Start of data in this buffer element - 1
hdreptr->endd	INTEGER	End of data in this buffer element
hdreptr->trpad	CHAR	reserved
hdreptr->dataru	CHAR[268]	Data RU, as follows:
dataru[0-9]		Source Name
dataru[10-19]		Destination Name
dataru[20]		Secondary pacing send window
dataru[21]		Secondary pacing receive window
dataru[22-23]		Secondary send maximum RU size (see notes)
dataru[24-25]		Primary send maximum RU size (see notes)
dataru[26]		Secondary send chunk size (in units of elements)
dataru[27]		Primary send chunk size (in units of elements)
Element 2
hdreptr->elteptr->elteptr	PTRBFELT	Pointer to buffer element - NIL
hdreptr->elteptr->startd	INTEGER	Start of data in this buffer element - 13
hdreptr->elteptr->endd	INTEGER	End of data in this buffer element
hdreptr->elteptr->trpad	CHAR	reserved
hdreptr->elteptr->dataru	CHAR[ ]	Data RU, as follows:
dataru[13]		The BIND RU received from the host
Notes:

The message consists of a buffer header, an initial element containing the source and destination Names, RU sizes, and so on, followed by a second element containing the BIND RU received from the host.

The source LPI and the L and P parts of the destination LPI are valid, but the I part of the destination LPI is reserved.

The two Send Maximum RU Size fields (in dataru[22-25]) are both integer values.

The BIND RU may be up to 256 bytes in length.

If the application is using the LUA variant of the FMI (see section 3.1), the BIND RU is preceded by its TH and RH; the startd field of the second element points to the TH.

The LU number matches that allocated to the named application on the Open (SSCP) Response.

The resource ID matches the value used by the application on the Open (SSCP) Request.

If chunking was specified on the Open(SSCP) Request, the icredits (initial credit from local node to application) field specifies the number of chunks, rather than RUs, that may be transmitted. The two Send Chunk Size parameters are specified in units of elements (each element contains up to 256 bytes of RU data). A value of 0 indicates that the chunk size is not the limiting factor in determining the size of messages; the limiting factor is the RU size or the segment size, so chunking is not required. In this case, credit will still be used, with the unit of credit being a message.

The icreditr (initial credit from application to local node) field is not used and must be set to zero.


4.2.2  Open(PLU) OK Response
FMI: Message Formats	7 of 32

4.2  Open(PLU)

4.2.2  Open(PLU) OK Response

Flow: NODE <--  APPL	Usage: PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to first buffer element
numelts	CHAR	Number of buffer elements - X'02'
msgtype	CHAR	Message Type - OPENMSG  (X'01')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
ophdr.openqual	CHAR	Open Qualifier - RSPOK (X'02')
ophdr.opentype	CHAR	Open Type - LUSEC (X'02')
ophdr.appltype	CHAR	Application Program Interface Type - X'02' (FMI application)
ophdr.opluno	CHAR	Logical Unit Number
ophdr.opresid	INTEGER	Resource Identifier
ophdr.icreditr	INTEGER	Initial Credit for Flow from Application to local node: 0
ophdr.icredits	INTEGER	Initial Credit for Flow from local node to  Application; only valid if APPLPAC = X'01'
ophdr.opninfo1	CHAR	Negotiable Bind Indicator - Bind is not negotiable (X'00') - Bind is negotiable (X'01')
Element 1
hdreptr->elteptr	PTRBFELT	Pointer to buffer element
hdreptr->startd	INTEGER	Start of data in this buffer element - 1
hdreptr->endd	INTEGER	End of data in this buffer element
hdreptr->trpad	CHAR	reserved
hdreptr->dataru	CHAR[268]	Data RU, as follows:
dataru[0-9]		Source Name
dataru[10-19]		Destination Name
dataru[20]		Segment Delivery Option - Do not deliver RU segments  (X'00') - Deliver RU segments (X'01')
dataru[21]		Application Pacing Option - No application pacing  (X'00') - Application pacing  (X'01')
dataru[22]		Application Cancel Option: Cancel is generated by - local node (X'00') - application (X'01')
dataru[23]		Application Transaction Numbers Option: transaction numbers are - not supported by application  (X'00') - supported by application  (X'01')
dataru[24]		BIND Table Index: - BIND_TABLE_INDEX_PRT (1) (printer session) - BIND_TABLE_INDEX_CRT (2) (display session)
Element 2
hdreptr->elteptr->elteptr	PTRBFELT	Pointer to buffer element - NIL
hdreptr->elteptr->startd	INTEGER	Start of data in this buffer element - 13
hdreptr->elteptr->endd	INTEGER	End of data in this buffer element
hdreptr->elteptr->trpad	CHAR	reserved
hdreptr->elteptr->dataru	CHAR[268]	Data RU, as follows:
dataru[13]		The BIND RU
Notes:

The RSPOK message consists of a buffer header, an initial element containing the source and destination Names and CICB, followed by elements containing the BIND RU received from the host.

The application should reflect the source and destination LPIs and the source and destination names from the Open(PLU) Request and must supply the I part of the source LPI.

The fields from Segment Delivery Option to Bind Table Index (in the first element) are referred to in the text as the PLU Connection Information Control Block (CICB). See section 3.3.1 for further information on the contents of the CICB.

The BIND RU may be up to 256 bytes in length.

For LUA, the BIND RU is not preceded by its TH and RH (contrast with the Open (PLU) Request, where the TH and RH are included).

As for the Open(PLU) Request, the icredits value is in units of chunks if chunking is being used.


4.2.3  Open(PLU) Error Response
FMI: Message Formats	8 of 32

4.2  Open(PLU)

4.2.3  Open(PLU) Error Response

Flow: NODE <--  APPL	Usage: PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to first buffer element - NIL
numelts	CHAR	Number of buffer elements - X'00'
msgtype	CHAR	Message Type - OPENMSG (X'01')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
ophdr.openqual	CHAR	Open Qualifier - RSPERR (X'03')
ophdr.opentype	CHAR	Open Type - LUSEC (X'02')
ophdr.appltype	CHAR	Application Program Interface Type - X'02' (FMI application)
ophdr.opluno	CHAR	Logical Unit Number
ophdr.opresid	INTEGER	Resource Identifier
ophdr.operr1	INTEGER	Error Code 1
ophdr.operr2	INTEGER	Error Code 2
Notes:

The RSPERR message consists of a buffer header only.

The application should reflect the source and destination LPIs.


4.2.4  Open(PLU) OK Confirm
FMI: Message Formats	9 of 32

4.2  Open(PLU)

4.2.4  Open(PLU) OK Confirm

Flow: NODE  --> APPL	Usage: PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to first buffer element
numelts	CHAR	Number of buffer elements - X'01'
msgtype	CHAR	Message Type - OPENMSG (X'01')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
ophdr.openqual	CHAR	Open Qualifier - CONFOK (X'04')
ophdr.opentype	CHAR	Open Type - LUSEC (X'02')
ophdr.appltype	CHAR	Application Program Interface Type - X'02' (FMI application)
ophdr.opluno	CHAR	Logical Unit Number
ophdr.opresid	INTEGER	Resource Identifier
ophdr.icreditr	INTEGER	Reserved
ophdr.icredits	INTEGER	Reserved
ophdr.opninfo1	CHAR	PLU Address
Element
hdreptr->elteptr	PTRBFELT	Pointer to buffer element - NIL
hdreptr->startd	INTEGER	Start of data in this buffer element - 1
hdreptr->endd	INTEGER	End of data in this buffer element
hdreptr->trpad	CHAR	reserved
hdreptr->dataru	CHAR[268]	Data RU, as follows:
dataru[0]		FM Profile
dataru[1]		TS Profile
dataru[2]		Primary Chaining Use
dataru[3]		Primary Request Control Mode
dataru[4]		Primary Chain Rsp Protocol
dataru[5]		Primary 2-Phase Commit
dataru[6]		Primary Compression Indicator
dataru[7]		Primary Send EB Indicator
dataru[8]		Secondary Chaining Use
dataru[9]		Secondary Request Control Mode
dataru[10]		Secondary Chain Rsp Protocol
dataru[11]		Secondary 2-Phase Commit
dataru[12]		Secondary Compression Indicator
dataru[13]		Secondary Send EB Indicator
dataru[14]		FM Header Usage
dataru[15]		Bracket Usage - Brackets not used (X'00') - Brackets used (X'01')
dataru[16]		Bracket Reset State - Bracket Reset State Betb (X'01') - Bracket Reset State Inb (X'02')
dataru[17]		Bracket Termination Rule
dataru[18]		Alternate Code Set Indicator
dataru[19]		Sequence Number Availability
dataru[20]		Normal-Flow Send/Receive Mode
dataru[21]		Half-Duplex Flip-Flop Reset
dataru[22]		Secondary Pacing Send Window
dataru[23]		Secondary Pacing Receive Window
dataru[24-25]		Secondary Send Maximum RU Size (INTEGER value)
dataru[26-27]		Primary Send Maximum RU Size (INTEGER value)
dataru[28]		LU-LU Session Type
dataru[29]		PLU Name Size
dataru[30-37]		PLU Name (EBCDIC)
dataru[38]		Session Type 1: PS FMH Type
dataru[39]		PS Data Stream Profile
dataru[40]		Number of Outstanding Destinations
dataru[41]		Compacted Data Indicator
dataru[42]		PDIR Allowed Indicator
dataru[43]		Session Type 2 or 3: Query Support
dataru[44]		Dynamic screen Size
dataru[45]		Basic Row Size
dataru[46]		Basic Column Size
dataru[47]		Alternate Row Size
dataru[48]		Alternate Column Size
Notes:

The Open (PLU) OK Confirm message consists of a buffer header and one element.

The Open(PLU) Confirm message does not carry source and destination names; both LPIs are valid.

The contents of dataru are referred to in the text as the PLU Bind Information Control Block (BICB). The BICB is only valid for an open-qualifier of CONFOK. See section 3.3.1 for further information on the contents of the BICB.


4.2.5  Open(PLU) Error Confirm
FMI: Message Formats	10 of 32

4.2  Open(PLU)

4.2.5  Open(PLU) Error Confirm

Flow: NODE  --> APPL	Usage: PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to first buffer element - NIL
numelts	CHAR	Number of buffer elements - X'00'
msgtype	CHAR	Message Type - OPENMSG (X'01')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
ophdr.openqual	CHAR	Open Qualifier - CONFERR (X'05')
ophdr.opentype	CHAR	Open Type - LUSEC (X'02')
ophdr.appltype	CHAR	Application Program Interface Type - X'02' (FMI application)
ophdr.opluno	CHAR	Logical Unit Number
ophdr.opresid	INTEGER	Resource Identifier
ophdr.operr1	INTEGER	Error Code 1
ophdr.operr2	INTEGER	Error Code 2
Notes:

The Open (PLU) Error Confirm message consists of a buffer header only.

The error codes are valid (see section 5.2). An Open(PLU) Error Confirm closes the connection.


4.3  Close(SSCP)
FMI: Message Formats	11 of 32

4.3  Close(SSCP)

Close(SSCP) closes an open SSCP connection.


4.3.1  Close(SSCP) Request
FMI: Message Formats	12 of 32

4.3  Close(SSCP)

4.3.1  Close(SSCP) Request

Flow: NODE <--  APPL	Usage: SSCP

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to buffer element - NIL
numelts	CHAR	Number of buffer elements - X'00'
msgtype	CHAR	Message Type - CLOSEMSG (X'02')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
clhdr.closqual	CHAR	Close Qualifier - REQU (X'01')
clhdr.clstype	CHAR	Close Subtype - SSCPSEC (X'01')
Notes:

The message consists of a buffer header only; there is no buffer element.


4.3.2  Close(SSCP) Response
FMI: Message Formats	13 of 32

4.3  Close(SSCP)

4.3.2  Close(SSCP) Response

Flow: NODE  --> APPL	Usage: SSCP

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to buffer element - NIL
numelts	CHAR	Number of buffer elements - X'00'
msgtype	CHAR	Message Type - CLOSEMSG (X'02')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
clhdr.closqual	CHAR	Close Qualifier - RSPOK (X'02')
clhdr.clstype	CHAR	Close Subtype - SSCPSEC (X'01')
Notes:

The message consists of a buffer header only; there is no buffer element.

The Close(SSCP) protocol is unconditional. It is not possible for the local node to keep the SSCP connection open after the application sends Close(SSCP).


4.4  Close(PLU)
FMI: Message Formats	14 of 32

4.4  Close(PLU)

Close(PLU) closes an open PLU connection.


4.4.1  Close (PLU) Request
FMI: Message Formats	15 of 32

4.4  Close(PLU)

4.4.1  Close (PLU) Request

Flow: NODE <--> APPL	Usage: PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to buffer element - NIL if not using LUA
numelts	CHAR	Number of buffer elements - X'00' if not using LUA
msgtype	CHAR	Message Type - CLOSEMSG (X'02')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
clhdr.closqual	CHAR	Close Qualifier - REQU (X'01')
clhdr.clstype	CHAR	Close Subtype - LUSEC (X'02')
clhdr.clsctl	CHAR	Close Control - CLNORMAL (X'01') - Normal - CLBIND (X'02') - Bind Forthcoming - CLCFAERR (X'03') - CFA Error - CLPUINAC (X'04') - PU Inactive - CLLUINAC (X'05') - LU Inactive - CLLNKERR (X'06') - Link Error - CLBFSHRT (X'07') - Node Buffer  Shortage - CLRCVCHK (X'08') - DFC Receive  Check - CLSLUTRM (X'09') - SLU Termination
clhdr.clspad1	CHAR	Reserved
clhdr.clspad2	INTEGER	Reserved
clhdr.clserr1	INTEGER	Error Code (only valid for Close Control = LINK ERROR)
LUA only (see notes):
Element
hdreptr->elteptr	PTRBFELT	Pointer to buffer element - NIL
hdreptr->startd	INTEGER	Start of data in this buffer element - 13
hdreptr->endd	INTEGER	End of data in this buffer element
hdreptr->trpad	CHAR	reserved
hdreptr->dataru	CHAR[268]	The UNBIND RU received from the host, with its TH and RH
Notes:

If the application is using the LUA variant of the FMI (see section 3.1), and the Close (PLU) Request was generated by receipt of an UNBIND from the host, then the element is included and startd points to the TH of the UNBIND message.

In all other cases (for example, if the Close (PLU) Request was generated by the local node as a result of a link outage), the message consists of a buffer header only; there is no buffer element.

The Close Control field is only valid on messages from the local node to the application.

If the Close Control field specifies LINK ERROR, then the Error code field gives the link outage code.


4.4.2  Close(PLU) Response
FMI: Message Formats	16 of 32

4.4  Close(PLU)

4.4.2  Close(PLU) Response

Flow: NODE <--> APPL	Usage: PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to buffer element - NIL
numelts	CHAR	Number of buffer elements - X'00'
msgtype	CHAR	Message Type - CLOSEMSG (X'02')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
clhdr.closqual	CHAR	Close Qualifier - RSPOK (X'02')
clhdr.clstype	CHAR	Close Subtype - LUSEC (X'02')
Notes:

The message consists of a buffer header only; there is no buffer element.

The Close(PLU) protocol is unconditional. It is not possible for the recipient of a Close(PLU) Request (either the local node or an application) to keep the PLU connection open; the only valid response is Close(PLU) Response with the close qualifier as RSPOK.


4.5  Data
FMI: Message Formats	17 of 32

4.5  Data

Data messages carry both inbound and outbound data between the application and the local node on all three connections. See section 3.4 for a detailed description of outbound and inbound data flows.

Flow: NODE <--> APPL	Usage: SSCP, PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to buffer element
numelts	CHAR	Number of buffer elements
msgtype	CHAR	Message Type - DATAFMI (X'20')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
dfhdr.fhackrqd	CHAR	Acknowledgment Required Indicator - NOACKREQ (X'00') - ACKREQ (X'01')
dfhdr.fhpad1	CHAR	Reserved
dfhdr.fhmsgkey	INTEGER	Message Key
dfhdr.fhflags1	CHAR	Application Flag 1
dfhdr.fhflags2	CHAR	Application Flag 2
dfhdr.fhpad2	INTEGER	Reserved
dfhdr.fhpad3	INTEGER	Reserved
dfhdr.fhseqno	INTEGER	Sequence Number
Element
hdreptr->elteptr	PTRBFELT	Pointer to buffer element
hdreptr->startd	INTEGER	Start of data in this buffer elementNon-LUA: 13, or 10 for 2nd and subsequent segments of outbound segmented RUs LUA, inbound data: 4 in first element, 13 in subsequent elements
hdreptr->endd	INTEGER	End of data in this buffer element
hdreptr->trpad	CHAR	reserved
hdreptr->dataru	CHAR[268]	Data RU
Notes:

The use of the acknowledgment required indicator in both inbound and outbound data acknowledgment protocols is described in section 3.4.

The use of the application flag fields is described in section 3.1.2 (but see note below for LUA).

The sequence number is undefined for inbound data but contains the corresponding SNA sequence number for outbound data.

If the application is using the LUA variant of the FMI (see section 3.1), the TH and (if appropriate) RH are included in the data, and the startd field points to the TH. The fhmsgkey, fhflags1, fhflags2, and fhseqno fields are undefined and should not be used; the corresponding data from the element should be used instead.


4.6  Status-Acknowledge
FMI: Message Formats	18 of 32

4.6  Status-Acknowledge

Status-Acknowledge messages flow between the application and the local node as part of the outbound and inbound data acknowledgment protocols. See section 3.4 for a detailed description of outbound and inbound acknowledgment protocols.

Note that the format of this message is slightly different for messages from the application to the local node on the PLU connection, as explained below.


4.6.1  Status-Acknowledge(Ack)
FMI: Message Formats	19 of 32

4.6  Status-Acknowledge

4.6.1  Status-Acknowledge(Ack)

Flow: NODE <--> APPL	Usage: SSCP

Flow: NODE  --> APPL	Usage: PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to buffer element - NIL if not using LUA
numelts	CHAR	Number of buffer elements - X'00' if not using LUA
msgtype	CHAR	Message Type - STATFMI (X'21')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
sfhdr.stackhdr.akstat	CHAR	Status Type - ACK (X'01')
sfhdr.stackhdr.akqual	CHAR	Acknowledgment Type - ACKPOS (X'02')
sfhdr.stackhdr.akmsgkey	INTEGER	Message Key
sfhdr.stackhdr.akflags1	CHAR	Application Flags 1
sfhdr.stackhdr.akflags2	CHAR	Application Flags 2
sfhdr.stackhdr.aknumb1	INTEGER	Undefined
sfhdr.stackhdr.aknumb2	INTEGER	Reserved
sfhdr.stackhdr.akseqno	INTEGER	SNA Sequence Number
LUA only (see notes):
Element
hdreptr->elteptr	PTRBFELT	Pointer to buffer element - NIL
hdreptr->startd	INTEGER	Start of data in this buffer element - 13 or - 10 for 2nd and subsequent segments of outbound segmented RUs
hdreptr->endd	INTEGER	End of data in this buffer element
hdreptr->trpad	CHAR	reserved
hdreptr->dataru	CHAR[268]	Data RU
Flow: NODE <--  APPL	Usage: PLU

As above, except that the Application Flag 1 and Application Flag 2 fields are not used. They are replaced by the following field:

sfhdr.stackhdr.akmsgtim	INTEGER	Last host response time X'FFFF' - no response time measured X'hhhh' - last response time measured, in units of 0.1 second
Notes:

The message key and application flags reflect the message key and application flags of the data message to which this is an acknowledgment (but see note on LUA below).

For outbound Status-Acknowledge (Ack) messages from the local node to the application, the SNA Sequence Number gives the Sequence Number of the inbound data message to which this is an acknowledgment (but see note on LUA below); it is normally only used by TS Profile 4 applications.

For inbound Status-Acknowledge (Ack) messages from the application to the local node, the SNA Sequence Number should reflect the Sequence Number of the outbound data message to which this is an acknowledgment.

If the host specified that response time statistics are to be maintained (see section 3.2.4 and section 3.3.15 for details), the application is responsible for measuring and reporting response times to the local node, using the akmsgtim field of this message.

If the application is using the LUA variant of the FMI (see section 3.1), the TH and (if appropriate) RH are included in the data, and the startd field points to the TH. The akmsgkey, akflags1, and akflags2 fields are undefined and should not be used; the corresponding data from the element should be used instead. The akseqno field is similarly undefined on messages from the local node to the application; it must be set on messages from the application to the local node. The akseqno field is used to hold the sequence number of the request being acknowledged.

If the application is not using the LUA variant of the FMI, the message consists of a buffer header only; there is no buffer element.


4.6.2  Status-Acknowledge(Nack-1)
FMI: Message Formats	20 of 32

4.6  Status-Acknowledge

4.6.2  Status-Acknowledge(Nack-1)

Flow: NODE <--> APPL	Usage: SSCP, PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to buffer element - NIL if not using LUA
numelts	CHAR	Number of buffer elements - X'00' if not using LUA
msgtype	CHAR	Message Type - STATFMI (X'21')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
sfhdr.stackhdr.akstat	CHAR	Status Type - ACK (X'01')
sfhdr.stackhdr.akqual	CHAR	Acknowledgment Type - ACKNEG1 (X'03')
sfhdr.stackhdr.akmsgkey	INTEGER	Message Key
sfhdr.stackhdr.akflags1	CHAR	Application Flag 1
sfhdr.stackhdr.akflags2	CHAR	Application Flag 2
sfhdr.stackhdr.aknumb1	INTEGER	Sense Data 1
sfhdr.stackhdr.aknumb2	INTEGER	Sense Data 2
sfhdr.stackhdr.akseqno	INTEGER	SNA Sequence Number of Data
LUA only (see notes):
Element
hdreptr->elteptr	PTRBFELT	Pointer to buffer element - NIL
hdreptr->startd	INTEGER	Start of data in this buffer element - 13 or - 10 for 2nd and subsequent segments of outbound segmented RUs
hdreptr->endd	INTEGER	End of data in this buffer element
hdreptr->trpad	CHAR	Reserved
hdreptr->dataru	CHAR[268]	Data RU
Notes:

The message key and application flags reflect the message key and application flags of the data message to which this is a negative acknowledgment (but see note on LUA below).

For Status-Acknowledgment(Nack-1) messages from the local node to the application, the sense data reflects the sense data in the SNA negative response.

For Status-Acknowledgment(Nack-1) messages from the application to the local node, the sense data fields are those intended for the SNA negative response to the host.

For outbound Status-Acknowledge (Nack-1) messages from the local node to the application, the SNA Sequence Number gives the Sequence Number of the inbound data message to which this is a negative acknowledgment (but see note on LUA below).

For inbound Status-Acknowledge (Nack-1) messages from the application to the local node, the SNA Sequence Number should reflect the Sequence Number of the outbound data message to which this is a negative acknowledgment.

If the application is using the LUA variant of the FMI (see section 3.1), the TH and (if appropriate) RH are included in the data, and the startd field points to the TH. The akmsgkey, akflags1, and akflags2 fields are undefined and should not be used; the corresponding data from the element should be used instead. The akseqno field is similarly undefined on messages from the local node to the application; it must be set on messages from the application to the local node.

If the application is not using the LUA variant of the FMI, the message consists of a buffer header only; there is no buffer element.


4.6.3  Status-Acknowledge(Nack-2)
FMI: Message Formats	21 of 32

4.6  Status-Acknowledge

4.6.3  Status-Acknowledge(Nack-2)

Flow: NODE  --> APPL	Usage: SSCP, PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to buffer element - NIL
numelts	CHAR	Number of buffer elements - X'00'
msgtype	CHAR	Message Type - STATFMI (X'21')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
sfhdr.stackhdr.akstat	CHAR	Status Type - ACK (X'01')
sfhdr.stackhdr.akqual	CHAR	Acknowledgment Type - ACKNEG2 (X'04')
sfhdr.stackhdr.akmsgkey	INTEGER	Message Key
sfhdr.stackhdr.akflags1	CHAR	Reserved
sfhdr.stackhdr.akflags2	CHAR	Critical Failure Indicator - Noncritical Failure (X'00') - Critical failure (X'01')
sfhdr.stackhdr.aknumb1	INTEGER	Error Code 1
sfhdr.stackhdr.aknumb2	INTEGER	Error Code 2
Notes:

The message consists of a buffer header only; there is no buffer element.

The message key refers to the message key in the inbound data message to which this is a negative acknowledgment.

See section 5.2 for error codes.


4.6.4  Status-Acknowledge(ACKLUA)
FMI: Message Formats	22 of 32

4.6  Status-Acknowledge

4.6.4  Status-Acknowledge(ACKLUA)

LUA Only

Flow: NODE  --> APPL	Usage: SSCP, PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to buffer element - NIL
numelts	CHAR	Number of buffer elements - X'00'
msgtype	CHAR	Message Type - STATFMI (X'21')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
sfhdr.stackhdr.akstat	CHAR	Status Type - ACK (X'01')
sfhdr.stackhdr.akqual	CHAR	Acknowledgment Type
sfhdr.stackhdr.akmsgkey	INTEGER	Message Key
sfhdr.stackhdr.akflags1	CHAR	Application Flags 1
sfhdr.stackhdr.akflags2	CHAR	Application Flags 2
sfhdr.stackhdr.aknumb1	INTEGER	Number of Replies
sfhdr.stackhdr.aknumb2	INTEGER	Reserved
sfhdr.stackhdr.akseqno	INTEGER	SNA Sequence Number
Notes:

The message key and application flags are undefined and should not be checked.

The SNA Sequence Number gives the Sequence Number of the inbound data message to which this is an acknowledgment.


4.7  Status-Control
FMI: Message Formats	23 of 32

4.7  Status-Control

See section 3.5.2 for details of Status-Control( ) message usage, and figure 3.5.7 (in the same section) for a summary of Control Type Codes.


4.7.1  Status-Control(...) Request
FMI: Message Formats	24 of 32

4.7  Status-Control

4.7.1  Status-Control(...) Request

Flow: NODE <--> APPL	Usage: PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to buffer element - NIL if not using LUA
numelts	CHAR	Number of buffer elements - X'00' if not using LUA
msgtype	CHAR	Message Type - STATFMI (X'21')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
sfhdr.stctlhdr.ctlstat	CHAR	Status Type - STCNTRL (X'02')
sfhdr.stctlhdr.ctlqual	CHAR	Control Qualifier - CTLREQU (X'01')
sfhdr.stctlhdr.ctltype	CHAR	Control Type
sfhdr.stctlhdr.ctlack	CHAR	Acknowledgment Required Indicator - No Ack Required (X'00') - Ack Required (X'01')
sfhdr.stctlhdr.ctlflag1	CHAR	Application Flags 1
sfhdr.stctlhdr.ctlflag2	CHAR	Application Flags 2 (see note for STSN)
sfhdr.stctlhdr.ctlnumb1	INTEGER	Code 1
sfhdr.stctlhdr.ctlnumb2	INTEGER	Code 2
sfhdr.stctlhdr.ctlmsgk	INTEGER	Message Key
LUA only (see notes):
Element
hdreptr->elteptr	PTRBFELT	Pointer to buffer element - NIL
hdreptr->startd	INTEGER	Start of data in this buffer element - 13 or - 10 for 2nd and subsequent segments of outbound segmented RUs
hdreptr->endd	INTEGER	End of data in this buffer element
hdreptr->trpad	CHAR	Reserved
hdreptr->dataru	CHAR[268]	Data RU
Notes:

If the application is using the LUA variant of the FMI (see section 3.1), the TH, RH, and RU are included in the data element, and the startd field points to the TH. The ctlflag1 and ctlflag2 bytes are not defined and should not be used; the appropriate values from the data should be used instead.

If the application is not using the LUA variant of the FMI, the message consists of a buffer header only; there is no buffer element.

See section 3.5.2, figure 3.5.7 for a summary of Status-Control( ) Control Type Codes.

The Code 1 and Code 2 fields apply only for Status-Control LUSTAT, SIGNAL, and STSN messages.

The Application flag byte 2 is used for the Status-Control (STSN) control byte (see section 3.3.12).


4.7.2  Status-Control(..) Acknowledge
FMI: Message Formats	25 of 32

4.7  Status-Control

4.7.2  Status-Control(..) Acknowledge

Flow: NODE <--> APPL	Usage: PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to buffer element - NIL if not using LUA
numelts	CHAR	Number of buffer elements - X'00' if not using LUA
msgtype	CHAR	Message Type - STATFMI (X'21')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
sfhdr.stctlhdr.ctlstat	CHAR	Status Type - STCNTRL (X'02')
sfhdr.stctlhdr.ctlqual	CHAR	Control Qualifier - ACKPOS (X'02')
sfhdr.stctlhdr.ctltype	CHAR	Control Type
sfhdr.stctlhdr.ctlack	CHAR	Reserved
sfhdr.stctlhdr.ctlflag1	CHAR	Application Flags 1
sfhdr.stctlhdr.ctlflag2	CHAR	Application Flags 2
sfhdr.stctlhdr.ctlnumb1	INTEGER	Code 1
sfhdr.stctlhdr.ctlnumb2	INTEGER	Code 2
sfhdr.stctlhdr.ctlmsgk	INTEGER	Message Key
LUA only (see notes):
Element
hdreptr->elteptr	PTRBFELT	Pointer to buffer element - NIL
hdreptr->startd	INTEGER	Start of data in this buffer element - 13 or - 10 for 2nd and subsequent segments of outbound segmented RUs
hdreptr->endd	INTEGER	End of data in this buffer element
hdreptr->trpad	CHAR	Reserved
hdreptr->dataru	CHAR[268]	Data RU
Notes:

If the application is using the LUA variant of the FMI (see section 3.1), the TH, RH, and RU are included in the data element, and the startd field points to the TH. The ctlflag1 and ctlflag2 bytes are not defined and should not be used; the appropriate values from the data should be used instead.

If the application is not using the LUA variant of the FMI, the message consists of a buffer header only; there is no buffer element.

See section 3.5.2, figure 3.5.7 for a summary of Status-Control( ) Control Type Codes.

The Code 1 and Code 2 fields apply only for Status-Control (STSN) Ack messages, where they are the application's secondary-to-primary and primary-to-secondary sequence numbers respectively.

For messages from the application to the local node, the message key field must match the message key in the corresponding Status-Control ( ) Request.


4.7.3  Status-Control(..) Negative-Acknowledge-1
FMI: Message Formats	26 of 32

4.7  Status-Control

4.7.3  Status-Control(..) Negative-Acknowledge-1

Flow: NODE <--> APPL	Usage: PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to buffer element - NIL if not using LUA
numelts	CHAR	Number of buffer elements - X'00' if not using LUA
msgtype	CHAR	Message Type - STATFMI (X'21')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
sfhdr.stctlhdr.ctlstat	CHAR	Status Type - STCNTRL (X'02')
sfhdr.stctlhdr.ctlqual	CHAR	Control Qualifier - ACKNEG1 (X'03')
sfhdr.stctlhdr.ctltype	CHAR	Control Type
sfhdr.stctlhdr.ctlack	CHAR	Reserved
sfhdr.stctlhdr.ctlflag1	CHAR	Application Flags 1
sfhdr.stctlhdr.ctlflag2	CHAR	Application Flags 2
sfhdr.stctlhdr.ctlnumb1	INTEGER	Sense Code 1
sfhdr.stctlhdr.ctlnumb2	INTEGER	Sense Code 2
sfhdr.stctlhdr.ctlmsgk	INTEGER	Message Key
LUA only (see notes):
Element
hdreptr->elteptr	PTRBFELT	Pointer to buffer element - NIL
hdreptr->startd	INTEGER	Start of data in this buffer element - 13 or- 10 for 2nd and subsequent segments of outbound segmented RUs
hdreptr->endd	INTEGER	End of data in this buffer element
hdreptr->trpad	CHAR	Reserved
hdreptr->dataru	CHAR[268]	Data RU
Notes:

If the application is using the LUA variant of the FMI (see section 3.1), the TH, RH, and RU are included in the data element, and the startd field points to the TH. The ctlflag1 and ctlflag2 bytes are not defined and should not be used; the appropriate values from the data should be used instead.

If the application is not using the LUA variant of the FMI, the message consists of a buffer header only; there is no buffer element.

See section 3.5.2, figure 3.5.7 for a summary of Status-Control( ) Control Type Codes.

For messages from the application to the local node, the message key field must match the message key in the corresponding Status-Control ( ) Request.


4.7.4  Status-Control(..) Negative-Acknowledge-2
FMI: Message Formats	27 of 32

4.7  Status-Control

4.7.4  Status-Control(..) Negative-Acknowledge-2

Flow: NODE  --> APPL	Usage: PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to buffer element - NIL
numelts	CHAR	Number of buffer elements - X'00'
msgtype	CHAR	Message Type - STATFMI (X'21')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
sfhdr.stctlhdr.ctlstat	CHAR	Status Type - STCNTRL (X'02')
sfhdr.stctlhdr.ctlqual	CHAR	Control Qualifier - ACKNEG2 (X'04')
sfhdr.stctlhdr.ctltype	CHAR	Control Type
sfhdr.stctlhdr.ctlack	CHAR	Reserved
sfhdr.stctlhdr.ctlflag1	CHAR	Reserved
sfhdr.stctlhdr.ctlflag2	CHAR	Reserved
sfhdr.stctlhdr.ctlnumb1	INTEGER	Error Code 1
sfhdr.stctlhdr.ctlnumb2	INTEGER	Error Code 2
sfhdr.stctlhdr.ctlmsgk	INTEGER	Message Key
Notes:

The message consists of a buffer header only; there is no buffer element.

See section 3.5.2, figure 3.5.7 for a summary of Status-Control( ) Control Type Codes.

See section 5.2 for a list of error codes.

The message key field matches the message key in the corresponding Status-Control( ) Request.


4.7.5  Status-Control(..) ACKLUA
FMI: Message Formats	28 of 32

4.7  Status-Control

4.7.5  Status-Control(..) ACKLUA

LUA Only:

Flow: NODE  --> APPL	Usage: PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to buffer element - NIL
numelts	CHAR	Number of buffer elements - X'00'
msgtype	CHAR	Message Type - STATFMI (X'21')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
sfhdr.stctlhdr.ctlstat	CHAR	Status Type - STCNTRL (X'02')
sfhdr.stctlhdr.ctlqual	CHAR	Control Qualifier - ACKLUA (X'05')
sfhdr.stctlhdr.ctltype	CHAR	Control Type
sfhdr.stctlhdr.ctlack	CHAR	Reserved
sfhdr.stctlhdr.ctlflag1	CHAR	Application Flags 1
sfhdr.stctlhdr.ctlflag2	CHAR	Application Flags 2
sfhdr.stctlhdr.ctlnumb1	INTEGER	Code 1
sfhdr.stctlhdr.ctlnumb2	INTEGER	Code 2
sfhdr.stctlhdr.ctlmsgk	INTEGER	Message Key (used for the SNA sequence number; see notes)
Notes:

The message consists of a buffer header only; there is no buffer element.

See section 3.5.2, figure 3.5.7 for a summary of Status-Control( ) Control Type Codes.

The application flags and the Code 1 and Code 2 fields are undefined and should not be used.

The message key field gives the sequence number from the TH of the inbound data message to which this is an acknowledgment.


4.8  Status-Error
FMI: Message Formats	29 of 32

4.8  Status-Error

The Status-Error message is used to report "request reject" and "RH usage" error conditions in outbound SNA RUs to the application. See section 3.5.3 for further information.

Flow: NODE  --> APPL	Usage: SSCP, PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to buffer element - NIL
numelts	CHAR	Number of buffer elements - X'00'
msgtype	CHAR	Message Type - STATFMI (X'21')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
sfhdr.sterrhdr.errstat	CHAR	Status Type - STERROR (X'03')
sfhdr.sterrhdr.errpad1	CHAR	Reserved
sfhdr.sterrhdr.errpad2	INTEGER	Reserved
sfhdr.sterrhdr.errpad3	INTEGER	Reserved
sfhdr.sterrhdr.errcode1	INTEGER	Error Code 1
sfhdr.sterrhdr.errcode2	INTEGER	Error Code 2
Notes:

The message consists of a buffer header only; there is no buffer element.

The error codes are listed in section 5.2.


4.9  Status-Resource
FMI: Message Formats	30 of 32

4.9  Status-Resource

The Status-Resource message is used to provide a simple flow control mechanism between the local node and the application to prevent the application from exhausting its resources. It is only used on the PLU connection where the application specifies in the PLU CICB that pacing requires application participation. See section 3.3.9 for further details.

Flow: NODE <--  APPL	Usage: PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to buffer element - NIL
numelts	CHAR	Number of buffer elements - X'00'
msgtype	CHAR	Message Type - STATFMI (X'21')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
sfhdr.streshdr.resstat	CHAR	Status Type - STRESRCE (X'04')
sfhdr.streshdr.respad	CHAR	Reserved
sfhdr.streshdr.rescred	INTEGER	Application Credit
Notes:

The message consists of a buffer header only; there is no buffer element.

The rescred (Application Credit) field indicates that the application can receive a further "credit" RUs of the maximum RU size, or a further "credit" chunks if chunking is being used.


4.10  Status-Session
FMI: Message Formats	31 of 32

4.10  Status-Session

The Status-Session message provides the application with information on changes in the state of a session between the local node and the host. See section 3.5.5 for further details.

Flow: NODE  --> APPL	Usage: SSCP, PLU

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to buffer element - NIL
numelts	CHAR	Number of buffer elements - X'00'
msgtype	CHAR	Message Type - STATFMI (X'21')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
sfhdr.stseshdr.sessstat	CHAR	Status Type - STSESSN (X'05')
sfhdr.stseshdr.sesspad	CHAR	Reserved
sfhdr.stseshdr.sesscode	INTEGER	Session Code
sfhdr.stseshdr.sessqual	INTEGER	Session Code Qualifier
Notes:

The message consists of a buffer header only; there is no buffer element.

The session codes are listed in section 5.1.

The SNA Server OS/2 and MS-DOS – based 3270 emulators display a session status identifier (-+z_nnn), where nnn is obtained by adding 484 to the value of sessqual from this message.


4.11  Status-RTM
FMI: Message Formats	32 of 32

4.11  Status-RTM

The Status-RTM message provides the application with information on the RTM measurement parameters used by the host. This allows the application to match its local display of RTM statistics, if it provides such a display, with the statistics used by the host. See section 3.3.15 for further details.

Flow: NODE  --> APPL	Usage: SSCP

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header
hdreptr	PTRBFELT	Pointer to buffer element
numelts	CHAR	Number of buffer elements
msgtype	CHAR	Message Type - STATFMI (X'21')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
sfhdr.strtmhdr.rtmstat	CHAR	Status Type - STRTM (X'06')
sfhdr.strtmhdr.strbndry	CHAR	RTM boundaries - X'00' - No RTM boundaries follow in element - X'01' - RTM boundaries follow in element
sfhdr.strtmhdr.strcount	CHAR	RTM counters - X'00' - No RTM counters follow in element - X'01' - RTM counters follow in element
sfhdr.strtmhdr.strtmdef	CHAR	RTM definition - X'00' - No change: use last received definition - X'01' - Timers run until first data is written to screen - X'02' - Timers run until keyboard is unlocked - X'03' - Timers run until application can send (CD or EB received)
sfhdr.strtmhdr.strtmact	CHAR	RTM measurement - X'00' - not active - X'01' - active
sfhdr.strtmhdr.strtmdsp	CHAR	Local RTM display - X'00' - disabled - X'01' - enabled
Element:
hdreptr->elteptr	PTRBFELT	Pointer to buffer element - NIL
hdreptr->startd	INTEGER	Start of data in this element
hdreptr->endd	INTEGER	End of data in this element
hdreptr->trpad	CHAR	Reserved
hdreptr->dataru	CHAR[268]	Data RU, as follows:
dataru[0-1]		Number of boundaries in element - X'0000' - no boundaries included - m-m boundaries included
dataru[2-3]		Number of counters in element - X'0000' - no counters included - n-n counters included
dataru[4-(2m+3)]		m boundary values
dataru[(2m+4)-(2m+2n+3)]			n counter values
dataru[(2m+2n+4)		RTM total time
Notes:

A Status-RTM message is sent after the Open(SSCP) OK Response to give the initial RTM parameters. It is sent again when the RTM counters are reset (either on request from the host or when the local node sends unsolicited RTM data to the host), or when the host changes any of the RTM parameters.

The message is sent only for applications that use LUs with type VDU (or LUs in a VDU pool), since the RTM feature applies only to 3270 display sessions.

All the values in the data RU are integer values.

The RTM counter values in this message may be nonzero at startup, since RTM statistics are maintained for a specific LU and not for a specific application's use of that LU. If zero counter values are included, this indicates that the counters are to be reset.

The "RTM total time" field is present only if the number of counters in the element is nonzero.


FMI: Status, Error, and Sense Codes
Chapter 5	1 of 7

FMI: Status, Error, and Sense Codes

This chapter lists the status codes, error codes, and sense codes used on Open messages, Status messages, and data messages with the System Detected Error Indicator set.


5.1  Status-Session Codes
FMI: Status, Error, and Sense Codes	2 of 7

5.1  Status-Session Codes

This section lists the status codes used on Status-Session messages. Figure 5.1.1 below lists:

The value for the status code.

The valid qualifying codes (if any) and their values.

On which sessions the combinations of primary and qualifying status codes can occur.

See section 3.5.5 for an overall description of the role of the Status-Session message and section 4.10 for a description of the Status-Session message format. The individual codes are discussed in section 3.2 and section 3.3.

Status Code	Value	Qualifying Code	Value	Usage
STNOSESS (No Session)	X'01'	STPUINAC STPUACT STPUREAC STLUINAC	X'10' X'03' X'04' X'11'	SSCP SSCP SSCP SSCP
STLINERR (Link Error)	X'02'	DLC ERROR	(See [1])	SSCP
STLUACT (LU Active)	X'05'	-	-	SSCP
STLUREAC (LU Reactivated)	X'06'	-	-	SSCP
STBETB (Between Brackets)	X'07'	-	-	PLU
Figure 5.1.1.    Status-Session Codes and usage.

Note:

1.	The qualifying status code supplied on a Status-Session (Link-Error) is the error code supplied by the Data Link Control Layer of the local node.

Status-Session Link Error Code 20 is generated, not by the link service, but by the node. It indicates that the link service is not yet available, but is being activated. Ignore this error code during session activation. Otherwise, all Status-Session Link Errors (including 20) will cause the emulator to send a Close SSCP. When the emulator receives the Close SSCP response, it will start again and send a new Open SSCP.

2.	The session status identifier displayed by the SNA Server OS/2 and MS-DOS – based 3270 emulators is obtained by adding 484 (decimal) to the qualifying status code shown above.


5.2  Error and Sense Codes
FMI: Status, Error, and Sense Codes	3 of 7

5.2  Error and Sense Codes

This section describes the error and sense codes that are reported to the application in the following messages:

Open(SSCP) Response

Open(PLU) Confirm

Status-Acknowledge (Nack-2)

Status-Control( ) Nack-2

Status-Error

Appl-Data messages with SDI set.

Where the reported codes are SNA sense codes, a fuller description is given in Chapter 8 of the IBM document Systems Network Architecture: Reference Summary (GA27-3136).

In addition, the local node delivers negative responses from the Host as Status-Acknowledge (Nack-1) and Status-Control ( ) Nack-1, which may have any SNA sense codes.

Application designers should note that error codes listed here that are specific to SNA Server always have an initial byte of value X'00' and therefore can be easily distinguished from SNA sense codes, which have nonzero initial bytes.

The error codes are listed in sections for the different messages with an indication of the reason for the error.


5.2.1  Error Codes for Open Messages
FMI: Status, Error, and Sense Codes	4 of 7

5.2  Error and Sense Codes

5.2.1  Error Codes for Open Messages

The possible error codes for Open (SSCP) Error Response and Open (PLU) Confirm Error are tabulated below.

Open (SSCP) Error Response

The table below gives the values for error code 1 and error code 2 that can be returned on the Open (SSCP) Error Response.

Error Code 1	Description		Error Code 2	Description
0	No servers found		CSRENOSR (0)	No servers found
X'0053'	LU not verified		CSRECBSH (3)	LU not verified
X'0055'	SSCP connection already open		CSRECBSH (3)	Control block / resource shortage
X'0057'	No LU in Group free
X'0812'	No free Session Control Block available
X'1001'	A connection activation failed recently
X'1002'	The connection is inactive
X'1010'	The connection is active, but an ACTPU has not yet been received
X'1011'	The connection is active, but an ACTLU has not yet been received
X'0063'	Unrecognized Open Request		CSRESERV (1)	Service not present
X'0A0E'	LU / LU Group not found in configuration
Figure 5.2.2.    Error codes for Open (SSCP) Error Response.

Note that the error code 1 values X'1001' to X'1011' are returned when the Open (SSCP) Request specified a nonforced Open. They do not indicate errors, but indicate that the LU-SSCP session is not active. The application may retry the Open (SSCP) Request specifying a forced Open, in which case the local node will attempt to activate the connection.

Open (PLU) Confirm Error

The table below gives the values for error code 1 that can be returned on the Open (PLU) Confirm Error message. Error code 2 is zero, except when error code 1 is X'0821'; in this case it contains the byte offset in the BIND where the BIND failed to match the BIND Check Table.

Error Code	Description

X'0051'	Fewer than two buffer elements were present on Open (PLU) Response

X'0052'	SSCP connection no longer active

X'0821'	BIND checking failed: error code 2 gives byte offset in BIND at which the error occurred

Figure 5.2.3.    Error codes for Open (PLU) Error Confirm.


5.2.2  Error Codes for Nack-2 Messages
FMI: Status, Error, and Sense Codes	5 of 7

5.2  Error and Sense Codes

5.2.2  Error Codes for Nack-2 Messages

The possible error codes delivered to the FMI application on Status-Acknowledge (Nack-2) and Status-Control ( ) Nack-2 messages are tabulated below. A Nack-2 is delivered to the application in response to data that is sent in error (or a Status-Control ( ) Request that is in error). The data has not been sent to the Host. The table indicates whether the error is critical or not (applying to the PLU connection only); if the error is critical, the critical failure indicator will be set in the message, and the application will receive a Close (PLU) Request as the next message.

All Nack-2 messages have the second word of information as X'0000'.

Error / Sense Code	Critical YES/NO	Description
X'0040'	YES	No buffer element on DATAFMI message
X'0042'	YES	DATAFMI message sent when no credit
X'0043'	YES	Invalid Status-Control( ) for TS profile
X'0044'	YES	Invalid Status-Control( ) from application
X'004A'	YES	HDX contention and -QR,-BB,EB or BKTFSM in pending-term-session
X'0809'	YES	Mode Inconsistency
X'1002'	YES	RU length error
X'1003'	YES	Function not supported, invalid FM profile
X'2002'	NO	Chaining error
X'2003'	NO	Bracket error
X'2004'	NO	Direction error
X'2005'	YES	Data Traffic Reset
X'2006'	YES	Data Traffic Quiesced
X'200D'	YES	Response Owed Before Sending Request (half-duplex)
X'4003'	YES	BB not allowed
X'4004'	YES	EB not allowed
X'4006'	YES	Exception response not allowed
X'4007'	YES	Definite Response not allowed
X'4009'	YES	CD not allowed
X'400A'	YES	No-Response not allowed
X'400B'	YES	Chaining not supported
X'400C'	YES	Brackets not supported
X'400D'	YES	CD not supported
X'400F'	YES	Incorrect use of FI
X'4014'	YES	Incorrect use of DR1, DR2, ER
X'8005'	NO	SSCP data sent when LU inactive
Figure 5.2.4.    Error Codes for Nack-2 messages.


5.2.3  Error Codes for Status-Error Messages
FMI: Status, Error, and Sense Codes	6 of 7

5.2  Error and Sense Codes

5.2.3  Error Codes for Status-Error Messages

The possible error codes delivered to the FMI application on Status-Error messages are tabulated below. A Status-Error message is delivered to the application in one of several cases:

The local node detects an error in a response sent from the application (as a Status-Acknowledge or Status-Control ( ) Ack/Nack-1 message).

The local node detects an error in some data from the Host that will not be delivered to the application as an SDI message (such as an expedited flow request).

The application sends an invalid Status message.

For inbound responses, the Status-Error codes have first byte X'00'. When the application is in error, the table indicates whether the error is critical or not (applying to the PLU connection only); if the error is critical, the application will receive a Close (PLU) Request as the next message.

The sense codes X'40..' will only be delivered if the corresponding receive check has been enabled in the CICB on the Open (SSCP) Request from the application.

Where the sense code is marked with the * symbol, the second word of sense information carries the request code of the expedited flow request that was in error (for example X'00C9' for SIGNAL).

Error / Sense Code	Critical YES/NO	Description
X'0008'	NO	Negative response already sent to this chain
X'0040'	YES	Invalid Status message from application
X'0046'	YES	Session failure due to Correlation Table shortage
X'0050'	YES	Invalid Sequence Number on Status-Ack( )
X'0053'	YES	Application may not send status control (STSN) negative acknowledge if it supports transaction numbers
X'0056'	YES	Status-Ack( ) sent when previous RQD chains are outstanding (see section 3.4.1)
X'0801'	NO	Message received when pacing count is zero
X'0805'	NO	BIND from another PLU when already bound
X'0809' *	NO	Mode Inconsistency (QEC or SHUTD)
X'0815'	NO	BIND from same PLU when already bound
X'0821'	NO	Incorrect ACTLU type (SSCP connection)
X'1003' *	NO	Wrong profile / Network Control request / invalid Session Control message
X'2005'	NO	Data Traffic Reset
X'2007'	NO	Data Traffic not Reset (STSN after SDT)
X'4009' *	NO	CD not allowed
X'400B' *	NO	Chaining not supported
X'400C' *	NO	Brackets not supported
X'400F' *	NO	Incorrect use of FI
X'4011' *	NO	Incorrect use of RU category
X'4014' *	NO	Incorrect use of DR1, DR2, ER
Figure 5.2.5.    Error Codes for Status-Error messages.


5.2.4  Sense Codes for System Detected Error Indicator(SDI) Messages
FMI: Status, Error, and Sense Codes	7 of 7

5.2  Error and Sense Codes

5.2.4  Sense Codes for System Detected Error Indicator(SDI) Messages

When the local node detects an error in a normal flow request from the Host, the message is converted into a DATAFMI message with SDI set in order to inform the application and to allow data to be processed serially. The application must convert the message to a Status-Acknowledge (Ack) in order to allow the local node to send the required negative response to the Host. The possible error codes delivered to the FMI application on such SDI messages are tabulated below.

The sense codes X'40..' will only be delivered if the corresponding receive check has been enabled in the CICB on the Open (SSCP) Request from the application. If a receive check has been disabled, the message may still be converted to an SDI message; for example, a message with BB, -BC would fail as 2002 or 2003 if 4003 were disabled.

When the application uses a Status-Control (LUSTAT) Request to reject outbound data (see section 3.3.14), the sense codes supplied by the application will be present on the SDI message generated by the local node.

Sense Code	Description
X'0809'	Mode Inconsistency
X'080B'	Bracket race error
X'081B'	Contention race condition
X'1003'	Incorrect FM Profile for request
X'2001'	Sequence number error
X'2002'	Chaining error
X'2003'	Bracket error
X'2004'	Direction error
X'2006'	Data Traffic Quiesced
X'4003'	BB not allowed
X'4004'	EB not allowed
X'4006'	Exception response not allowed
X'4007'	Definite Response not allowed
X'4009'	CD not allowed
X'400B'	Chaining not supported
X'400C'	Brackets not supported
X'400D'	CD not supported
X'400F'	Incorrect use of FI
X'4011'	Incorrect use of RU category
X'4014'	Incorrect use of DR1, DR2, ER
Figure 5.2.6.    Sense Codes for SDI messages.


Configuration Information
Chapter 6	1 of 6

Configuration Information

This chapter explains how a client accesses information in the SNA Server configuration file.


6.1  Accessing the Configuration File
Configuration Information	2 of 6

6.1  Accessing the Configuration File

To obtain information about the SNA Server 3270 configuration, the application uses the following calls:

SEPDCREC	This call returns a data structure that contains the 3270 user record for this user and the diagnostics record from the running configuration file.

SEPDGETINFO	This call returns general information on the version of SNA Server currently running, such as the release level, the network operating system, and the directory of the running configuration file.

These entry points are discussed in Chapter 2.

If the return code from SEPDCREC indicates that no 3270 user record was found for this user, the emulation program should terminate and not allow the user to use 3270 emulation. The SNA Server error message COM0438 is provided to log this error; see Chapter 7 for more information on error logging.


6.2  Formats of Configuration Records
Configuration Information	3 of 6

6.2  Formats of Configuration Records

This section explains the format of 3270 user records and the diagnostics record in the configuration file.


6.2.1  3270 User Records
Configuration Information	4 of 6

6.2  Formats of Configuration Records

6.2.1  3270 User Records

The format of the 3270 User record is shown below. The first structure definition is an LU/session information record, which includes details of a 3270 LU; the second is the 3270 user record, which includes a number of LU/session information records.

Note that the user record is not a fixed length, because the number of LU/session information records in the remap list is variable. The structures used below are provided simply as a template to allow you to map to the correct offset in the record.

typedef struct tecwrksd

{

UCHAR	cwshost[9];	/* LU/Pool name accessed	*/
USHORT	cwsestyp;	/* Session type (M2, M3, M4, M5, printer)	*/
USHORT	cwsmodov;	/* Has the user got override permission?	*/
USHORT	cwspad;	/* 2 bytes of padding	*/
} TECWRKSD;

typedef struct tecwrkus

{

USHORT	cwlen;	/* Length of record	*/
USHORT	cwtype;	/* Type of record	*/
UCHAR	cwname[21];	/* User name	*/
UCHAR	cwremark[26];	/* Comment field	*/
UCHAR	cwstylef[9];	/* Initial style file name	*/
USHORT	cwvewrtm;	/* Can user view RTM info ?	*/
USHORT	cwalert;	/* Has user got ALERT permission ?	*/
USHORT	cwchghan;	/* Can change LU/Pool name accessed ?	*/
USHORT	cwmaxses;	/* Maximum number of active sessions 1-10	*/
USHORT	cwnumrec;	/* Number of sessions for user	*/
TECWRKSD	cwsesdat[10];	/* Session information records	*/
USHORT	cwmodisf;	/* Permission to modify initial style	*/
UCHAR	cwstatus;	/* Status byte: user or group ?	*/
UCHAR	cwpad;	/* 1 byte of padding	*/
USHORT	cwnumrmp;	/* Number of LUs/Pools in remap list	*/
TECWRKSD	cwremap[1];	/* LU/Pool Remap list	*/
} TECWRKUS;

The SNA Server for Windows NT product permits configuration of more than 10 sessions per user. If this is done, the first 10 sessions will be placed in the cwsesdat array with cwnumrec set to 10 and the remainder placed in the location of the remap list. cwnumrmp will indicate the number of TECWRKSD structures in the remap list. Note that this permits cwmaxses to be greater than cwnumrec.

The following paragraphs explain the meaning of each field in the structures, and indicate how the application should use it. The sections on configuring 3270 users and LUs in the Microsoft SNA Server Administration Guide should also be used as a cross-reference.

Field	Usage
cwshost	The name (up to eight characters) of the LU or LU pool that this session is configured to use. The application specifies this name on the Open (SSCP) Request (see section 4.1).
cwsestyp	The LU type (display or printer) of the LU used by this session and (if it is a display LU or a pool of display LUs) the screen model. The possible values are:
	CERTMOD2 (0)	Model 2 display (24 by 80)
	CERTMOD3 (1)	Model 3 display (32 by 80)
	CERTMOD4 (2)	Model 4 display (43 by 80)
	CERTMOD5 (3)	Model 5 display (27 by 132)
	CERTPRNT (4)	Host printer
	The application should use this value to distinguish between display and printer sessions and to set the appropriate screen model for display sessions.
cwsmodov	TRUE if the user has permission to override the screen model for display sessions — that is, to change the session to use a different screen model from the one configured. If this value is FALSE, the user should not be permitted to change the screen model. This field is not used for printer sessions and should not be checked.
cwlen	The length of the 3270 user record (this is variable because it contains a variable number of LU/session records in the remap list). The application should use this value to locate the start of the next 3270 user record when searching for the correct record..
cwtype	Identifies this as a 3270 user record.
cwname	The LAN Manager user name, or other identifying name, of the 3270 user (up to 20 characters). The application uses this to search for the correct 3270 user record.
cwremark	An optional comment field (up to 25 characters), used in the configuration program to give more information about the user (for example the user’s full name).
cwstylef	The name (up to eight characters) of the default style file used by this user (a file containing the user’s 3270 customization settings, used by the SNA Server 3270 emulation programs). This field may be used to identify the equivalent file for your 3270 emulator, if appropriate.
	If this field is blank, no style file is used and the 3270 emulator should revert to its default settings (unless overridden by a style file specified by the user).
cwvewrtm	TRUE if this user is permitted to view a display of Response Time Monitor (RTM) statistics for his or her 3270 sessions. If this field is FALSE, the application should not display RTM statistics and should not display a Last Transaction Time Indicator (LTTI) on the status line of display sessions. See section 6.2.2 for more information on the use of RTM.
cwalert	TRUE if the user is permitted to send NetView user alerts. If this field is FALSE, the user should not be permitted to send alerts. See section 6.2.2 for more information on the use of alerts.
cwchghan	TRUE if the user is permitted to remap a 3270 session to use a different LU (in which case it can be changed to use any LU in the remap list — see cwremap below). If this field is FALSE, the application should not allow the user to remap sessions.
cwmaxses	The maximum number of active sessions permitted to this user. If the number of sessions configured (see cwnumrec below) is greater than this, the user must not be allowed to activate more sessions at a time than this field specifies.
cwnumrec	The total number of sessions configured for this user. The user record always contains 10 LU/session records (see cwsesdat below), but only this number of the records will be used — the remainder will be filled with zeros.
cwsesdat	Ten LU/session records. Some of these records may be filled with zeros, indicating that they are unused (cwnumrec gives the number of sessions that are used — see above). The application should list, and allow the user to use, only the sessions that have valid session records here.
cwmodisf	TRUE if the user is permitted to modify the initial 3270 customization. If this field is FALSE, the application should use the customization defined by cwstylef above (if specified); the user should not be allowed to make changes to this style, or to override it by loading a different style file.
cwstatus	Indicates whether the user name in this record is to a LAN Manager user name or group name. The least significant bit of this byte is CERTGRUP (1) for a group, and zero for a user. Other bits are not used.
cwpad	Pad byte — not used by the application.
cwnumrmp	The number of LU/session records in the remap list (see cwremap below).
cwremap	The list of LU/session records, which indicates the LUs to which the user may remap sessions (if any). If the user is not permitted to remap sessions (see cwchghan above), this list is not used and should not be checked by the application.


6.2.2  Diagnostics Record
Configuration Information	5 of 6

6.2  Formats of Configuration Records

6.2.2  Diagnostics Record

The format of the Diagnostics record is shown below. The first structure definition is an Alert information record, which includes details of a 3270 NetView user alert; the second is the Diagnostics record, which includes a number of Alert information records.

typedef struct tedalert

{

UCHAR	dalrtnam[53];	/* Description of the ALERT number	*/
UCHAR	daparam1[33];	/* Description of parameter 1	*/
UCHAR	daparam2[33];	/* Description of parameter 2	*/
UCHAR	daparam3[33];	/* Description of parameter 3	*/
} TEDALERT;

typedef struct tediagns

{

USHORT	dilen;	/* Length of record	*/
USHORT	ditype;	/* Type of record	*/
UCHAR	dinetmgt[9];	/* Network Management Connection name	*/
USHORT	disrtmco;	/* Send RTM data at counter overflow	*/
USHORT	disrtmub;	/* Send RTM data at UNBIND	*/
USHORT	diwruldr;	/* RTM timers run until:	*/
USHORT	dirtmth1;	/* RTM threshold #1	*/
USHORT	dirtmth2;	/* RTM threshold #2	*/
USHORT	dirtmth3;	/* RTM threshold #3	*/
USHORT	dirtmth4;	/* RTM threshold #4	*/
TEDALERT	dialerts[20];	/* ALERT description records	*/
UCHAR	diaudit[128];	/* Audit log filename	*/
UCHAR	dierror[128];	/* Error log filename	*/
USHORT	diaudlev;	/* Default audit level	*/
UCHAR	dipad[16];	/* 16 bytes of padding	*/
} TEDIAGNS;

The following paragraphs explain the meaning of each field in the structures that is relevant to the application and indicate how the application should use it. Fields that are not included in the list below are used by other SNA Server components and need not concern the application; in particular, the Network Management Connection name and the times at which RTM data is sent to the host are handled by the local node on behalf of the application.

Note that the application should determine whether the user is permitted to send NetView user alerts and/or view RTM data (see section 6.2.1); it should not display the appropriate information, as described below, if the user does not have permission to use it. The host may also override whether the application is permitted to send and/or to display RTM data (see section 3.2.4 for more information).

For more information on how the application uses the RTM parameters, see section 3.2.4, section 3.3.15, and section 4.11 of this manual.

Field	Usage
dalrtnam	The description (up to 52 characters) of the alert corresponding to a particular alert number. The application should display this information to help the user determine which alert to send.
daparam1,	The descriptions (each up to 32 characters) of up to three parameters
daparam2,	Required for the alert; depending on the specific alert,
daparam3	One or more of these descriptions may be blank, indicating that the parameter is not used. For each of these descriptions that is not blank, the application should display this string to prompt the user for the appropriate parameter.
diwruldr	The definition by which response times are to be measured. The application should measure the response time from the time the user presses ENTER or an AID key to send data to the host, until one of the following events as defined by this field:
	CERTWRIT (0)	The first host data reaches the 3270 display
	CERTUNLK (1)	The host unlocks the user’s keyboard
	CERTDIRE (2)	The host gives the application direction so that the user can send further data
	Note that the host may override these definitions; see section 3.2.4 for more information.
dirtmth1, dirtmth2, dirtmth3, dirtmth4	The thresholds that define the bands into which response times are to be classified. Note that the host may override these definitions; see section 3.2.4 for more information.
dialerts	Up to 20 alert records that define the alerts SNA Server users can send to a host. There are always 20 records, but some of these may be blank, indicating that they are not used; the application should display the descriptions of any nonblank alerts together with the alert number (from 1 to 20) defined by the position of the alert record in this array.


6.2.3  Creating Specific NetView User Alerts
Configuration Information	6 of 6

6.2  Formats of Configuration Records

6.2.3  Creating Specific NetView User Alerts

You can create NetView user alerts for users to send. Users identify the alerts by number; each number corresponds to a specific collection of information or requests that the user wants to send via NetView to a host operator.

SNA Server leaves blank fields for the user alert information in the structure that is returned from SEPDCREC. To create specific user alerts, create appropriate data structures, and call the TRANSFER_MS_DATA verb to send the user alert to NetView.

For information about TRANSFER_MS_DATA, see the Microsoft SNA Server APPC Programmer’s Guide.


Diagnostics
Chapter 7	1 of 9

Diagnostics

This chapter describes the following diagnostics mechanisms available to SNA Server applications:

Error and audit log messages

Internal tracing in the emulator

HLLAPI parameter tracing

FMI tracing


7.1  Error and Audit Log Messages
Diagnostics	2 of 9

7.1  Error and Audit Log Messages

7.1.1  Options for Logging

There are two ways in which an application can write messages to the SNA Server log files:

1.	Use the SNA Server DMOD logging macros presented in section 7.1.2.

2.	Use the LOG_MESSAGE Common Service Verb.

Both these options use log message files formatted with the OS/2 utility MKMSGF. A log message file contains a set of messages that are referenced by a message number. If a component wishes to log an error, it specifies the appropriate message number to extract the text from the message file, rather than including the message text within the component.

SNA Server has one message file that is used for all its error and audit logging. The messages in this file are available for both of the above options. See the Reference manual for a list of all the SNA Server error and audit log messages and their meanings.

If extra messages are required, there are two options:

a.	The messages COM0393 and COM0394 are provided as generic log messages for use by emulators. Each takes two parameters, both of which are text strings: the first is an identifier for the specific emulator that logged the message, and the second can contain any data or parameters to be logged. The difference between these messages is the level at which they are logged; COM0393 is a level 10 information message, while COM0394 is a warning message that should be used to report error conditions. See section 7.1.2 for more information on message severity levels.

b.	A second message file can be created, which is then specified as one of the parameters on the LOG_MESSAGE verb. This cannot be used with the logging macros.

You are recommended to use the SNA Server logging macros (with the SNA Server emulator log messages if a suitable message is available, or with the generic messages COM0393 and COM0394) rather than the LOG_MESSAGE verb. LOG_MESSAGE does not provide control over the severity level at which messages are logged (all messages are logged at level 12 in the error log file); it is primarily intended for user applications such as APPC TPs.

The following sections (7.1.2 and 7.1.3) explain the use of the SNA Server logging macros and of the LOG_MESSAGE Common Service Verb.


7.1.2  SNA Server DMOD Logging Macros
Diagnostics	3 of 9

7.1  Error and Audit Log Messages

7.1.2  SNA Server DMOD Logging Macros

The logging macros provided with SNA Server are relatively easy to use because each log call is a single line of code. In the simplest case, only a message number is required; the text of the logged message is taken from the message file. Parameters can also be supplied as required.

For the text and meaning of each of the log messages included in the SNA Server message file, see the Microsoft SNA Server Reference. Examples of messages logged by an SNA Server 3270 emulation program are given in Examples below.

Message Severities

The following severities are used in SNA Server:

6	Detailed problem analysis data

8	General information messages

10	Significant system events

12	Warnings/recoverable errors

16	Fatal errors

Messages at levels 6, 8, 10, 12, and 16 in the Windows NT Event log (Event log). The default level of Event logs can be specified when configuring SNA Server, so that all or some of the Event logs can be suppressed; in addition, the system administrator can change the Event log level for a particular component using the Manage program or can filter out lower-level messages when viewing log files using the Browse program.

Note that level 16 errors are always taken to be fatal errors; an application that logs a level 16 error will be terminated automatically. In particular, the call to the logging routine will not return; the application should perform all required 'clean-up" processing, including any lower-level logs, before logging the fatal error.

Logging Macros

The following macros can be used to log messages at levels 6, 8, 10, 12, and 16:

COM_LOG6

COM_LOG8

COM_LOG10

COM_LOG12

COM_LOG16

The syntax of the macros is:

COM_LOGa ( b ) "" ))

(for a message with no parameters)

COM_LOGa ( b ) " %c " , e ))

(for a message with one parameter)

COM_LOGa ( b ) " %c | %d | . . ." , e , f , . . ))

(for a message with more than one parameter)

where:

a	Is the severity and is 6, 8, 10, 12, or 16.

b	Is the message number.

c	Is the format of the variable parameter e.

d	Is the format of the variable parameter f.

Up to nine parameters can be supplied, according to the number of "%n" placeholders in the text of the message being logged. The first parameter will replace %1, the second will replace %2, and so on.

The formats c and d must be valid formats for the C function sprintf, since the logging macro uses this function to generate the complete text string to be logged.

Note that the unmatched left and right parentheses on the macro call are deliberate; the expansion of the macro supplies the remaining parentheses so that the resulting code is correct.

Examples

This syntax is illustrated in the following examples. The two messages below are taken from the SNA Server message file; the first is a warning message with no parameters, and the second is a level 16 error message that includes two parameters.

COM0392W: Warning — User Alert was not accepted by the host

COM0429E: Error trying to read from %1 (rc = %2)

The following call:

COM_LOG12(392)""));

would give the following message in the Event log:

Warning — User Alert was not accepted by the host

The following call:

COM_LOG16(429)"%s|%d", cfgfilename, rc));

where cfgfilename = "COM.CFG", and rc = 17, would give the following message in the Event log:

Error trying to read from COM.CFG, rc = 17

The complete message log entry contains the following information about the error or event and the service that logged it:

Message Number

Date/Time

COM name	the name of the service

COM type	the type of the service

Severity

Message with optional parameters

The COM name is the name in the service table when the DMOD initializes; this name is the name with which the user logged on to the network operating system and is set by calling SEPDCREC. The COM type is set on the call to SBPUINIT. See Chapter 2 of this document for more information on these functions.


7.1.3  LOG_MESSAGE Common Service Verb
Diagnostics	4 of 9

7.1  Error and Audit Log Messages

7.1.3  LOG_MESSAGE Common Service Verb

This verb is fully documented in the DCA/Microsoft Select Common Service Verbs Programmer’s Guide.

The main advantage of using this verb to log messages is that a user-defined message file can be specified, containing messages specific to your application. This means that you are not restricted to the messages defined in the SNA Server message file.

Note that all messages logged using this verb are logged at level 12 in the error log file; it is not possible to log messages to the audit log file or to log at different severity levels.


7.2  Internal Tracing
Diagnostics	5 of 9

7.2  Internal Tracing

SNA Server provides internal tracing macros, which can be built into an application. These can be used to check the operation of the application during development. Compile-time options determine whether or not this tracing is included in object code; it should be compiled out when producing end-user products. Internal tracing must be initialized before any TRACEnn macro calls are issued. This initialization is performed by initializing the DMOD via the SBPUINIT call. The following sections (7.2.1 and 7.2.2) describe the use of the tracing macros within application source code, and the methods of controlling trace output using compile-time and run-time options.


7.2.1  Internal Tracing Macros
Diagnostics	6 of 9

7.2  Internal Tracing

7.2.1  Internal Tracing Macros

The following macros are used for internal tracing:

COM_ENTRY

The COM_ENTRY macro is used at the start of any procedure in which internal tracing is required. It provides an identifier that is then used in the trace file to identify all trace calls made from this procedure.

The format of the COM_ENTRY call is as follows:

COM_ENTRY("str");

where str is a string of up to five characters that uniquely identifies this procedure.

TRACEn

The TRACEn macro is used to specify data to be traced; this data may include variable parameters. The format of the TRACEn call is one of the following, depending on whether parameters are included:

TRACEn()"string in sprintf format"));

TRACEn()"string in sprintf format containing parameters", parameters));

Note that the unmatched parentheses are deliberate; they are resolved by the expansion of the macro.

The value n identifies the severity level of the trace. It can take the values 2, 4, 6, 8, 10, 12, or 16, where levels 6 to 16 correspond to the audit and error log levels (see section 7.1), and 2 and 4 are used for very low-level detail tracing. This allows run-time filtering of trace information so that only information above a specified level is logged; see the following section for more information.

The following examples illustrate the use of the tracing macros:

COM_ENTRY("proc1");

TRACE4()"Start of error-handling routine"));

TRACE8()"Supplied parameters are %s, %d", parm1, parm2));


7.2.2  Controlling Internal Tracing
Diagnostics	7 of 9

7.2  Internal Tracing

7.2.2  Controlling Internal Tracing

The compiler option NOTRC defines whether internal tracing is included in object code. Compiling with /DNOTRC does not include internal tracing (the TRACEn macros expand to a no-op); compiling without /DNOTRC includes internal tracing.

Under Windows NT, the registry entries used to control tracing are now inserted by the SETUP program. The SNATRACE.EXE program may be used to enable/disable internal tracing dynamically at runtime (assuming binaries have been compiled with internal tracing enabled).

When running an executable program that was compiled with internal tracing, tracing is enabled by generating the following entries in the Windows NT Registry:

InternalTraceLevel=n

InternalTraceFile1=file1

InternalTraceFile2=file2

The entries should be stored under:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Nap\Parameters

When running an executable program that was compiled with internal tracing, the COMINT environment variable is used to define the level of tracing required and the file or files to which it is traced. Set this variable as follows:

SET COMINT=n/file1[/file2]

n is the severity level of the tracing required. All trace calls at this level or higher are included in the trace output; trace calls at lower levels are ignored. For example, setting level 10 includes all trace calls at levels 10, 12, and 16, but excludes tracing at levels 2, 4, 6, and 8. Use 0 to include all tracing at whatever level, or 20 to disable tracing entirely.

file1 and file2 are the names of files to which trace output is written. If two filenames are specified, trace output is sent to the first file until it reaches 250K (or 500K for Windows NT) and then to the second file; when the second file also reaches 250K (or 500K for Windows NT), the first file is cleared and tracing continues to the first file. This process continues, changing to the other file every time the current file reaches 250K (or 500K for Windows NT), so that only the most recent 250-500K (or 500-1000K for Windows NT) of trace information is retained. If only one filename is specified, tracing continues to this file regardless of file size.


7.3  HLLAPI Parameter Tracing
Diagnostics	8 of 9

7.3  HLLAPI Parameter Tracing

The COM_TRC_HLLAPI macro can be used within an HLLAPI library to trace the parameters supplied to an HLLAPI function and the returned values. It should be used at the following times:

1.	At the start of the HLLAPI library routine, to trace the four parameters supplied by the HLLAPI application before beginning to process them.

2.	At the end of the HLLAPI library routine, to trace the values to be returned in each of the four parameters before control is returned to the application.

The format of the COM_TRC_HLLAPI call is as follows:

COM_TRC_HLLAPI (type, func, data, len, retc);

type (USHORT) is either REQUEST or RESPONSE; use REQUEST when tracing the parameters supplied by the user application at the start of the library routine and RESPONSE when tracing the parameters to be returned to the user application.

func, len, and retc (USHORT) are the values of the parameters func_number, data_length, and return_code that were supplied to HLLAPI by the user application, or the values to be returned to the application. Note that the user application supplies pointers to these values, but the actual values are required for the COM_TRC_HLLAPI call.

data (UCHAR FAR *) is the data_string parameter supplied to HLLAPI by the user application, or the string to be returned to the application in this parameter.

To turn on tracing for an HLLAPI application, the environment variable COMTRC is used; see the Administrator’s Guide for more information on the use of COMTRC. Tracing may also be turned on and off from within the HLLAPI user application using the trace control parameters of the Set Session Parameters function; see the HLLAPI Specification for more information.

The trace output lists the following:

The name of the HLLAPI function being called (this is determined from the function number, the first of the four parameters to the HLLAPI call)

Whether the trace refers to a request or a response (determined from the type parameter to the COM_TRC_HLLAPI call)

The data_length and return_code/ps_position parameters to the HLLAPI call

If the data_string parameter is used for this HLLAPI function, the address of the data as supplied to HLLAPI, followed by a listing of the data in both hexadecimal and ASCII characters.

Note that SNA Server’s HLLAPI tracing is designed for use with the SNA Server implementation of HLLAPI on OS/2, which is compatible with the implementation provided by OS/2 Extended Edition version 1.2. If your HLLAPI implementation differs from this (for example, by including function numbers that are not supported by the SNA Server implementation, by using a different name for a given function number, or in the usage of the data_string parameter for different verbs), the tracing output obtained may not be correct.

For Windows NT, you can use SNATRACE.EXE to dynamically control HLLAPI and FMI tracing.


7.4  FMI Tracing
Diagnostics	9 of 9

7.4  FMI Tracing

SNA Server provides the facility for tracing message flows at the FMI, both at the local node and at the application’s DL-Base. This allows you to track the messages being sent and received by the local node and/or the application.

Message tracing at the application’s DL-BASE is controlled by entries in the Windows NT Registry under:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Nap\Parameters

Message tracing at the local node is controlled by placing similar entries under:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Node\Parameters

The entries required in both cases are as follows:

MessageTraceFile1=file1

MessageTraceFile2=file2

DLCTraceState=on	(or off)

SNATRACE.EXE can be used to dynamically control HLLAPI and FMI tracing.

Message tracing is controlled by the COMSNA environment variable. You set this variable before starting the local node using the COMM START command, or before starting the client application; the application must be started in the screen group in which COMSNA was set.

The syntax of COMSNA is described in the Microsoft SNA Server Administration Guide. To activate FMI tracing, you need to use one of the options /A (all messages are traced) or /F (FMI messages only).

For the local node, you can leave tracing initially inactive by not specifying any of the final options on COMSNA, and then activate it when required using the Manage program; in this case you need to use the 'Internal message tracing" option in Manage, which is the equivalent of the /A option on COMSNA. For the application, you need to specify either /A or /F to activate tracing at start of day, because it cannot be activated from the Manage program.

You can also use the Manage program to start the local node with tracing, instead of setting COMSNA and then starting the local node. Again, you need to use the 'Internal message tracing" option, which is the equivalent of COMSNA with the /A option.


Compiling and Linking with SNA Server
Chapter 8	1 of 5

Compiling and Linking with SNA Server

This chapter lists and explains the header files and libraries for use with SNA Server client applications, and provides information on compiling and linking the ISV application.


8.1  SNA Server Client Files
Compiling and Linking with SNA Server	2 of 5

8.1  SNA Server Client Files

The following files are required to build the SNA Server client application:

FMI.H	Main header file containing the definitions of buffer and message formats, function prototypes for the DL-BASE/DMOD interface calls, and constant definitions.

TRACE.H	Definitions of the logging and tracing macros (see Chapter 7 of this manual for more information).

COMCLI.LIB	Main library for the OS/2 Client interface

DOSACS.LIB	Main library for the MS-DOS – based Client interface

WINCLI.LIB	Main library for the Windows-based Client interface

WLOGTR.LIB	Additional library containing diagnostics routines for the Windows-based Client interface

SNACLI.LIB	Main library for the Win32-based Client interface


8.2  Included Files
Compiling and Linking with SNA Server	3 of 5

8.2  Included Files

To compile the application, the header files FMI.H and TRACE.H are required.  In addition, one of the standard operating system header files may be required.  To include the required files, the following lines should be used in your application:

#include <os2.h>

#include <fmi.h>

#include <trace.h>

#include <fmi.h>#

include <trace.h>


8.3  Compiler Options
Compiling and Linking with SNA Server	4 of 5

8.3  Compiler Options

When compiling the application, the following compiler options are required:

Option	Explanation
/c	Compile only, without linking.  Linking is done as a separate phase, in order to include the required SNA Server libraries.
/D NOTRC	The NOTRC macro specifies that internal tracing should not be compiled into the application. See Chapter 7 of this manual for more information on the use of internal tracing.The /D NOTRC option should be used for building a final system (internal tracing should not be included because it will degrade performance and occupancy). For a development system, you may want to compile with internal tracing; if so, remove the /D NOTRC option.
/D OS2_SUPPORT, /D MSWIN_SUPPORT, /D DOS_SUPPORT, /D WIN32_SUPPORT	These macros are used in the header files fmi.h and trace.h, to support variants of the client interface for the operating systems OS/2, Windows version 3.x, MS-DOS, and the Win32 subsystem of the Windows NT operating system respectively. One of these options must be defined, depending on the operating system for which the application is intended.
/G2cs	2:	use 286 instructions
	c:	use Pascal calling conventions
	s:	remove stack check calls
/Zp	Structures must be packed.
/Gcs	c:	use Pascal calling conventions
	s:	remove stack check calls
	z:	use stdcall conventions — only on i386/i486 processors, not MIPS or Alpha
/J	Default character type is unsigned. Not valid under Win32.

The following compiler flags are required, but any of the valid options for each flag may be used, as appropriate to your application:

/A	Compiler model

/O	Optimization

/W	Warning level


8.4  Linking
Compiling and Linking with SNA Server	5 of 5

8.4  Linking

The library COMCLI.LIB must be linked with the application.

The DMOD is implemented as a Dynamic Link Library (DLL).  COMCLI.LIB contains import definitions for the APIs in the DLL, and some global variables required for the logging and tracing macros.

The libraries WINCLI.LIB and WLOGTR.LIB must be linked with the application.

The DMOD is implemented as a Dynamic Link Library (DLL).  WINCLI.LIB contains import definitions for the APIs in the DLL, and some global variables required for the logging and tracing macros.  WLOGTR.LIB contains import definitions for log and trace routines.

The following library must be linked with the application:

DOSACS.LIB	DL-BASE, DMOD, and diagnostics code

The library SNACLI.LIB must be linked with the application.

The DMOD is implemented as a Dynamic Link Library (DLL). SNACLI.LIB contains import definitions for the APIs in the DLL, and some global variables required for the logging and tracing macros.

It is possible to create a different DLL for each connection type, which is dynamically loaded when the user starts a session for an LU using that connection type.  In this case, in order to make the log and trace macros available, the application structure needs to be as shown below:


A
Appendix A	1 of 3

Appendix

This appendix describes the API extension to the Windows 3270 Emulator Interface that converts link status and error codes to a printable string.


FMI Extensions for the Windows Environment
Appendix A	2 of 3

FMI Extensions for the Windows Environment

Below is a definition of the function, syntax, returns, and remarks for using the extension. Refer to Chapter 5, "FMI: Status, Error, and Sense Codes" for more information.


GetFmiReturnCode( )
Appendix A	3 of 3

FMI Extensions for the Windows Environment

GetFmiReturnCode( )

Converts link status and error codes to a printable string. This function provides a standard set of error strings for use by FMI applications.

Syntax

int WINAPI GetFmiReturnCode (UINT errcode1, UINT errcode2, UINT buffer_length, unsigned char FAR * buffer_addr)

Parameter	Description

errcode1	Supplied parameter; see "Remarks."

errcode2	Supplied parameter; see "Remarks."

buffer_length	Supplied parameter; specifies the length of the buffer pointed to by buffer_addr. The recommended length is 256.

buffer_addr	Supplied/returned parameter; specifies the address of the buffer that will hold the formatted, null-terminated string.

Returns

0x20000001

The parameters are invalid; the function could not read the specified error codes or could not write to the specified buffer.

0x20000002

The specified buffer is too small.

Remarks

The errcode1 and errcode2 parameters are set according to the way that GetFmiReturnCode is used:

Codes to be translated		Value for errcode1	Value for errcode2
The errcode1 and errcode2 values specified in section 5.2 "Error and Sense Codes" which includes messages for:Open(SSCP) Response, Open(PLU) Confirm, Status-Acknowledge(Nack-2), Status-Control() Nack2, Status-Error, and Appl-Data messages with SDI set		Unchanged from message	Unchanged from message
The status and qualifier codes returned from a Status-Session message		status*256 + qualifier	0xffff
The return code from WinLUAGetLastInitStatus		The return code	0xffff