Copyright: SNA Device Interface Specification
Citation: SNA Device 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


SNA Device Interface Specification Contents
Microsoft SNA Server

SNA Device Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

Chapter 2	The BASE/DMOD Interface

Chapter 3	The Data Link Control Interface (DLC)

Chapter 4	SNA Device Interface Specification: Message Formats

Chapter 5	Configuration Information

Chapter 6	Setup Information

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix


SNA Device Interface Specification Contents
Microsoft SNA Server

SNA Device Interface Specification

Contents

Before You Begin

About This Manual

Network Operating Systems

Chapter 1	Introduction

Chapter 2	The BASE/DMOD Interface

Chapter 3	The Data Link Control Interface (DLC)

Chapter 4	SNA Device Interface Specification: Message Formats

Chapter 5	Configuration Information

Chapter 6	Setup Information

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix


SNA Device Interface Specification Contents
Microsoft SNA Server

SNA Device Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

1.1  Overview

1.2  SNA Server SNALink Environment

1.2.1  Administrators Model

Configuration

SNALink Management

1.3  Structure of SNA Server Components

1.3.1  The Role of the BASE

1.3.2  Localities and DMODs

1.3.3  Component Localities

1.3.4  Partners

1.3.5  SNALink Structure

1.4  Messages

1.4.1  Overview of Message Formats

1.4.2  Buffer Header Format

1.4.3  Buffer Element Format

1.5  LPI Connections

1.5.1  Paths and DMODs

1.5.2  LPI Addresses

1.5.3  Making Connections

1.6  How DMODs Communicate

1.7  Internal Data Structures

Chapter 2	The BASE/DMOD Interface

Chapter 3	The Data Link Control Interface (DLC)

Chapter 4	SNA Device Interface Specification: Message Formats

Chapter 5	Configuration Information

Chapter 6	Setup Information

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix


SNA Device Interface Specification Contents
Microsoft SNA Server

SNA Device Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

Chapter 2	The BASE/DMOD Interface

2.1  Introduction

2.2  Process Structure/Scheduling

2.3  Initialization

2.4  Termination

2.5  Sending Messages

2.6  The Dispatcher

2.7  Receiving Messages

2.8  The Work Manager

2.9  BASE/SNALink Entry Points

2.9.1  SNALink Entry Points

SNALinkInitialize  Initialize SNALink

2.9.2  Buffer Management Entry Points

SNAGetElement  Get Buffer Element

SNAReleaseElement  Release Buffer Element

SNAGetBuffer  Get Buffer

SNAReleaseBuffer  Release Buffer

2.9.3  Other Base Entry Points

SNASendMessage  Send a Message

SNAGetLinkName  Get the SNALink Name

SNASendAlert  Send a Preformatted NMVT Alert to NetView

2.10  Sample Code

Chapter 3	The Data Link Control Interface (DLC)

Chapter 4	SNA Device Interface Specification: Message Formats

Chapter 5	Configuration Information

Chapter 6	Setup Information

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix


SNA Device Interface Specification Contents
Microsoft SNA Server

SNA Device Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

Chapter 2	The BASE/DMOD Interface

Chapter 3	The Data Link Control Interface (DLC)

3.1  Introduction

3.1.1  Supported Configurations

3.2  Opening a Connection

3.2.1  Opening the LINK LPI Connection

3.2.2  Activating a Host Connection

Leased SDLC Line (No XIDs Exchanged), Channel Adapter

X.25, 802.2 or SDLC Switched Line (XIDs Exchanged)

3.2.3  Activating a Peer Connection

Fixed Link Roles

Negotiable Link Roles

3.2.4  Opening the STATION LPI Connection

3.2.5  Node Identification and Signaling Information

3.2.6  XID Retries

3.2.7  Multiple Connections

3.3  DLC Information Transfer

3.3.1  DLC Flow Control

3.4  Closing a Connection

3.4.1  Outages

SDLC

802.2

X.25

DFT

3.4.2  Connection Retries

3.5  Incoming Call Support

3.6  SDLC Multipoint Connections

Chapter 4	SNA Device Interface Specification: Message Formats

Chapter 5	Configuration Information

Chapter 6	Setup Information

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix


SNA Device Interface Specification Contents
Microsoft SNA Server

SNA Device Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

Chapter 2	The BASE/DMOD Interface

Chapter 3	The Data Link Control Interface (DLC)

Chapter 4	SNA Device Interface Specification: Message Formats

4.1  Open(LINK)

4.1.1  Open(LINK) Request

Expanded Information About Message Formats for Open(LINK) Request with SDLC

Optional Second Element (Only Used by X.25 SVC)

4.1.2  Open(LINK) Response

4.2  Close(LINK)

4.2.1  Close(LINK) Request

4.2.2  Close(LINK) Response

4.3  Open(STATION)

4.3.1  Open(STATION) Request

4.3.2  Open(STATION) OK Response

4.3.3  Open(STATION) Error Response

4.4  Close(STATION)

4.4.1  Close(STATION) Request

4.4.2  Close(STATION) Response

4.5  Request-Open-Station

4.6  Station-Contacted

4.7  Outage

4.8  Status-Resource

4.9  Send-XID

4.10  DLCDATA

Chapter 5	Configuration Information

Chapter 6	Setup Information

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix


SNA Device Interface Specification Contents
Microsoft SNA Server

SNA Device Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

Chapter 2	The BASE/DMOD Interface

Chapter 3	The Data Link Control Interface (DLC)

Chapter 4	SNA Device Interface Specification: Message Formats

Chapter 5	Configuration Information

5.1  Format of SNALink Configuration Information

5.2  Accessing Configuration Information

5.3  Configuration Entry Points

SNAGETCONFIGVALUE  Get Value of Configuration Parameter

SNAGETSYSTEMINFO  Get System Information

Chapter 6	Setup Information

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix


SNA Device Interface Specification Contents
Microsoft SNA Server

SNA Device Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

Chapter 2	The BASE/DMOD Interface

Chapter 3	The Data Link Control Interface (DLC)

Chapter 4	SNA Device Interface Specification: Message Formats

Chapter 5	Configuration Information

Chapter 6	Setup Information

6.1  Introduction

6.2  Setup File Structure

6.2.1  Link Service Setup Interface

6.2.2 Floppy Disk Layout

6.2.3 The Setup Resource Library

6.2.4  Replaceable Text in Setup Resource Libraries

6.2.5  The On-line Help File

6.3  Setup Registry Architecture

6.3.1  Product Entries

6.3.2  Service Entries

6.4  Creating Your Setup

6.4.1  Initialization Section

6.4.2  Define the Parameters

6.4.3  Complete the Basic Code

6.4.4  Design Dialogs

6.4.5  Fill In the Code

6.5  Setup Template Description

6.5.1  Initialization Section

Source Media Descriptions

Option Type

Languages Supported

Option List

Options Text List

SNA Option List

SNA Option Additionals

Installation Steps

6.5.2  Dialog Constants

Progress Copy Variables

Help Context IDs

6.5.3  File Constants

File Names and Initialization Constants

Product Information

6.5.3  General Constants

6.5.4  Language Dependent Dialog Constants

6.5.5  Language Dependent File Constants

6.5.6  Date Section

6.5.7  Input Dialogs Information

6.5.8  Input Dialogs Scripts

6.5.9  Identification Functions

Identify

Return Options

Return SNA Options

Return SNA Additionals

6.5.10  SNA Invocation Section

6.5.11  NCPA Invocation Section

6.5.12  Common Code Section

Main Entry Section

Set Defaults (set_defaults)

Install Component (install_component)

Configure Component (config_component)

Modify Parameters (modify_params)

Adjust Parameters (adjust_params)

Create Registry Entries (create_regvals)

Write Out Variables (write_params)

Get Bindings From Component (getbind_component)

Remove Component (remove_component)

Escape Hatches

6.5.13  Installation Control Section

Install Section

File List Section

6.6  Global Variables

6.7  Utility Functions

6.7.1  Product Functions

CreateSNARegEntry

FindSNARegEntry

FindSNAProductServices

FindNextAvailableIndex

GrepUniqueServiceInfo

EnterServiceName

6.7.2  Service Entry Functions

CreateSNAService

FindSNAService

DeleteSNAService

SetupMessage

SNAServiceType Values

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix


SNA Device Interface Specification Contents
Microsoft SNA Server

SNA Device Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

Chapter 2	The BASE/DMOD Interface

Chapter 3	The Data Link Control Interface (DLC)

Chapter 4	SNA Device Interface Specification: Message Formats

Chapter 5	Configuration Information

Chapter 6	Setup 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

7.2  Internal Tracing

7.2.1  Internal Tracing Macros

7.2.2  Controlling Internal Tracing

7.3  DLC Tracing

7.4  Connection Tracing

COM_TRC_IHV

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix


SNA Device Interface Specification Contents
Microsoft SNA Server

SNA Device Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

Chapter 2	The BASE/DMOD Interface

Chapter 3	The Data Link Control Interface (DLC)

Chapter 4	SNA Device Interface Specification: Message Formats

Chapter 5	Configuration Information

Chapter 6	Setup Information

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

8.1  SNA Server DLC Header Files

8.2  Included Files

8.3  Required Exports

8.4  Compiler Options

8.5  Linking

Appendix A	Appendix


SNA Device Interface Specification Contents
Microsoft SNA Server

SNA Device Interface Specification

Contents

Before You Begin

Chapter 1	Introduction

Chapter 2	The BASE/DMOD Interface

Chapter 3	The Data Link Control Interface (DLC)

Chapter 4	SNA Device Interface Specification: Message Formats

Chapter 5	Configuration Information

Chapter 6	Setup Information

Chapter 7	Diagnostics

Chapter 8	Compiling and Linking with SNA Server

Appendix A	Appendix

A.1  Synchronous Dumb Card Interface

A.2  The Driver Interface

A.2.1  Architecture Overview

The Interface Record

Event Signaling

Link Characteristics

A.3  I/O Request Packets

A.3.1  INITIALIZATION

A.3.2  OPEN

A.3.3  CLOSE

A.3.4  IOCTL Commands

Function 0x41: Set Event/Semaphore Handle

Function 0x42: Set Link Characteristics

Function 0x43: Set V.24 Output Status

Function 0x44: Transmit Frame

Function 0x45: Abort Transmitter

Function 0x46: Abort Receiver

Function 0x47: Off-Board Load

Function 0x61: Get/Set Interface Record

Function 0x62: Get V.24 Status

Function 0x63: Receive Frame

A.4  Equates and Structure Layouts


Before You Begin
1 of 3

Before You Begin

This manual is intended for OEMs and adapter vendors who are developing their own SNALink software to work with SNA Server for Windows NT [image] (referred to in this manual as SNA Server). It provides the following information:

Internal concepts of SNA Server that are required to integrate new communications adapters into the server environment

Definitions of the interfaces used by SNA Server to communicate with SNALinks

Information on using SNA Server's configuration and diagnostics features

Instructions for compiling and linking the SNAlink support software

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


About This Manual
Before You Begin	2 of 3

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 new communications adapters.

Chapter 2, "The BASE/DMOD Interface"

Explains scheduling within an SNA Server SNALink, the interface that SNALinks use to communicate with the BASE, and the entry points available.

Chapter 3, "The Data Link Control Interface"

Explains the messages and message sequences used for communications between an SNALink and the local 2.1 node  —  the Data Link Control Interface (DLC).

Chapter 4, "SNA Device Interface Specification: Message Formats"

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

Chapter 5, "Configuration Information"

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

Chapter 6, "Setup Information"

Describes the mechanism provided to allow IHV setup utilities to configure SNA Server SNALinks.

Chapter 7, "Diagnostics"

Describes the interfaces to the SNA Server message logging and tracing facilities and explains how SNALinks 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 SNALink and provides information on compiler flags to be used.

Appendix

Provides details of the interface used by the SNA Server synchronous dumb card device driver.


Network Operating Systems
Before You Begin	3 of 3

Network Operating Systems

Microsoft [image] LAN Manager (as implemented in Windows NT), Novell [image] NetWare [image], and Banyan [image] VINES [image] are the network operating systems (NOS) currently supported by SNA Server. Future versions of SNA Server are planned to support other network operating systems. You are advised to develop link support that is independent of the network operating system in order to take advantage of this support in future versions.


Introduction
Chapter 1	1 of 19

Introduction

This chapter describes some key concepts used in SNA Server. Since the purpose of this document is to enable OEMs and adapter vendors to develop link support software (an SNALink) to integrate their hardware adapters into an SNA Server system, only the relevant parts of the SNA Server architecture are described.


1.1  Overview
Introduction	2 of 19

1.1  Overview

An SNA Server SNALink must implement an SNA-compatible data transport mechanism capable of connecting the local 2.1 node to remote host (PU4/5) and/or peer (PU2.1) systems.

The local node provides the SNA layers of Path Control (PC), Transmission Control (TC), Data Flow Control (DFC), and Logical Unit (LU) Services — see Figure 1.1.

The local node uses the Data Link Control interface (DLC) to communicate with an SNALink. This interface is defined in Chapter 3, "The Data Link Control Interface (DLC)." The SNALink and the DLC driver are responsible for transferring data between the Path Control layer of the node and the DLC adapter.

The routing of messages that flow between SNA Server components is handled by the SNABASE and DMOD components. Refer to Chapter 2, "The BASE/DMOD Interface," for details of how to send and receive messages.

Figure 1.1    Example SNA Server system


1.2.1  Administrator’s Model
Introduction	3 of 19

1.2  SNA Server SNALink Environment

1.2.1  Administrator's Model

Configuration

The configuration information for an SNA Server system is stored in two forms:

A centralized configuration file containing details of Logical Units, Physical Units, and Connections.

Entries in the Windows NT Registry containing configuration information for the SNALinks supported on that machine. This information contains a few parameters required by SNA Server and any other parameters that IHV code may require.

An SNA Server SNALink is defined when an SNA Server system is installed. An SNALink may support only one physical connection from the server. If a single adapter is capable of supporting multiple physical connections, SNA Server requires multiple SNALinks to be configured.

To reconfigure a server's SNALink support (perhaps after installing a new adapter), the Administrator uses either the Windows NT Network Control Panel or the SNA Server Setup program. For further details of how this operates, refer to Chapter 6, "Setup Information."

All other configuration of an SNA Server system is performed using either the SNA Server Admin utility. Please refer to the Microsoft SNA Server Reference for further details. As part of this configuration process, logical connections to remote PUs are associated with one or more SNALinks.

SNALink Management

All configured SNALinks are automatically started when the SNA Server system is started. At this stage, the SNALink performs any initialization required and then waits for instructions from local nodes.

When a connection is activated, either from the Admin program or automatically in response to (for example) a session with a remote host being requested by a 3270 user, the SNALink will receive an OPEN(LINK) message from the local node (see Chapter 3 and Chapter 4). The SNALink should then perform whatever action is required to initiate that connection. This may involve dialing a telephone number for a switched SDLC connection or bringing up level 2 on an X.25 link and sending a CALL packet.

If the IHV wishes the same physical adapter to be available for use by multiple SNALinks (for example, a dumb SDLC card may be used to communicate using SDLC or X.25 protocols), the SNALink should not attempt to access the hardware until it has received an OPEN(LINK) message from the local node.


1.3  Structure of SNA Server Components
Introduction	4 of 19

1.3  Structure of SNA Server Components

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


1.3.1  The Role of the BASE
Introduction	5 of 19

1.3  Structure of SNA Server Components

1.3.1  The Role of the BASE

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

This document is concerned with the Link Base, which is the type of base used by SNA Server SNALinks. The Base has entry points for initialization, sending messages, receiving messages, and termination.


1.3.2  Localities and DMODs
Introduction	6 of 19

1.3  Structure of SNA Server Components

1.3.2  Localities and DMODs

An SNA Server component, including its BASE, 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 central configuration file. In addition, configuration information is maintained on each Server machine about the SNALinks it supports (see Chapter 7).

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.2.

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


1.3.3  Component Localities
Introduction	7 of 19

1.3  Structure of SNA Server Components

1.3.3  Component Localities

SNALinks may enter dynamically into an SNA Server system. The SNALink, 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 SNALink (or any other CS component) to participate in an SNA Server system.


1.3.4  Partners
Introduction	8 of 19

1.3  Structure of SNA Server Components

1.3.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 an SNALink 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.3.5  SNALink Structure
Introduction	9 of 19

1.3  Structure of SNA Server Components

1.3.5  SNALink Structure

An SNA Server SNALink consists of:

The link-specific protocol code provided by the IHV

A BASE

A DMOD

The DMOD, BASE, and the IHV-link-specific component of an SNA Server SNALink are implemented as Dynamic Link Libraries (DLLs). The executable component SNALINK.EXE is used to start an SNALink. This component determines from the SNA Server configuration information which links support DLL (for example. IHVLINK.DLL) is required for the SNALink and dynamically loads it before entering the Base scheduler.

The executable structure of an SNALink is shown in Figure 1.3.

Figure 1.3    SNALink structure


1.4  Messages
Introduction	10 of 19

1.4  Messages

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


1.4.1  Overview of Message Formats
Introduction	11 of 19

1.4  Messages

1.4.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.4 illustrates a typical message with two elements. The individual fields in the header and elements are explained in the following sections.

Figure 1.4    Typical message format

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


1.4.2  Buffer Header Format
Introduction	12 of 19

1.4  Messages

1.4.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 on the Open(LINK) request (see section 4.1)— 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 that assigns them (only the assigning application needs to interpret these values).

startd and endd fields in elements are always stored in low-byte, high-byte orientation (the normal orientation of an Intel processor).


1.4.3  Buffer Element Format
Introduction	13 of 19

1.4  Messages

1.4.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[SNANBEDA]	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 constant SNANBEDA is defined in SNA_DLC.H as 268.
The following information will help you to interpret the message formats:

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 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.

In the example message format illustrated in Figure 1.4, 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.5  LPI Connections
Introduction	14 of 19

1.5  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.5.2; note that this is not related to the SNA Server concept of a connection between the local node and a remote system.


1.5.1  Paths and DMODs
Introduction	15 of 19

1.5  LPI Connections

1.5.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.

In SNA Server, a path is implemented using reliable LAN connections (named pipes, SPX, TCP, AppleTalk [image], VINES IP) — one LAN connection for each path. 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 a pipe to 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.5 illustrates the paths and connections between an SNA Server local node and two SNALinks. X.25 service "A" has two connections to the local node (one for each of two virtual circuits); SDLC service "B" has one connection to the local node.

Figure 1.5    Paths, DMODs, and connections


1.5.2  LPI Addresses
Introduction	16 of 19

1.5  LPI Connections

1.5.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, SNALink, 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 virtual circuits available from an X.25 SNALink).
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 an SNALink, the L and P values identify the message as being DLC data for that local node, and the I value indicates which connection 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.5.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 SNALink locality and Locality 6 to a second SNALink 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.6 shows an example of the L values that could be used between the components shown in Figure 1.5. Figures 1.7 and 1.8 show examples of the LPI values that would be used by the local node on messages flowing between the components.

Figure 1.6    Example L values

Figure 1.7    L values specified on messages between the local node and SNALink "A"

Figure 1.8    LPI values specified on messages flowing on two different connections between the local node and SNALink "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.5.3  Making Connections
Introduction	17 of 19

1.5  LPI Connections

1.5.3  Making Connections

Before messages can flow across connections, the connection must be established, or "opened." This is necessary since a partner 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.

When a local node wishes to communicate with an SNALink, it will attempt to open a connection by sending an OPEN LINK(Request) to the SNALink. This message will have LPI values already set up by the Base, which the SNALink should save for referencing the connection in the future.

The DLC interface does not permit the SNALink to issue an OPEN(Request).


1.6  How DMODs Communicate
Introduction	18 of 19

1.6  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 and 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 LAN connection for every path that is open to another locality.

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

The SNA Workstation Process (SNABASE) 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 SNA Workstation Process (SNABASE) 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. Note that the SNA Workstation Process (SNABASE) mentioned here is not the same as the BASE that the IHV code is linked with and uses for scheduling.

Figure 1.9    How DMODs communicate


1.7  Internal Data Structures
Introduction	19 of 19

1.7  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.10 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 LAN connection for a specific locality on the network.

Figure 1.10    Main DMOD data structures


The BASE/DMOD Interface
Chapter 2	1 of 13

The BASE/DMOD Interface

2.1  Introduction

This chapter describes the interface to the SNA Server BASE. It includes a listing of the entry points that an SNALink can call and those it must provide to the BASE. These entry points allow messages to be sent to and received from the local 2.1 node.

Note

The SNA Server BASE is not the same as the SNA Workstation Process (SNABASE).


2.2  Process Structure/Scheduling
The BASE/DMOD Interface	2 of 13

2.2  Process Structure/Scheduling

The primary thread of execution within an SNA Server SNALink is under the complete control of the Base. The Base schedules the SNALink by calling pre-defined entry points, which the IHV link support code must provide.

The IHV link support code may spawn extra threads of execution. However, the Base is not re-entrant. The IHV code must ensure that only a single thread is executing within the Base at any moment in time.

The recommended SNALink structure is that the dispatcher should be used to action messages received from the local node and the work manager used to process data received from the link. These routines and the way in which they are scheduled are described in sections 2.6 and 2.8 respectively.


2.3  Initialization
The BASE/DMOD Interface	3 of 13

2.3  Initialization

When the SNALink is loaded into memory, the Base/DMOD will perform all Initialization required by the SNA Server system (including announcing availability of the new SNALink to other SNA Server components).

Once this has been completed, it will call the routine SNALinkInitialize, which must be provided by the IHV's link support code.

SNALinkInitialize is called with a parameter that is a handle to the global Base event. This handle should be saved by the SNALink and used to signal the Base when an event occurs (e.g. data received from the link).

The routine SNALinkInitialize should also:

Read in the SNA Server configuration information for the SNALink (see Chapter 5 for details).

Set up any required data structures.

Register with the driver that provides the support for the hardware adapter, initializing this if necessary.

Should Initialization fail for any reason (e.g. an associated driver is not installed), the routine should report the failure to the administrator by calling SNAReportStatus.


2.4  Termination
The BASE/DMOD Interface	4 of 13

2.4  Termination

When a critical error occurs, forcing abnormal termination of the SNALink, the IHV code must ensure that all active connections are cleanly terminated, using whatever protocols are appropriate for the link type in use. (For example, an X.25 SNALink would send a CLEAR packet on all active VCs and possibly take down level 2).

This should be performed using the process detach facility of the DLLEntryPoint function.


2.5  Sending Messages
The BASE/DMOD Interface	5 of 13

2.5  Sending Messages

The SNALink should build the message in a buffer and then call the 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 SNALink may either obtain a new buffer to contain the message to be sent (using SNAGetBuffer) or reuse one in which it has previously received a message. The application is responsible for any buffer that 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 SNAReleaseBuffer). If a 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 SNAGetElement) or release existing ones (using SNAReleaseElement). It is the application's responsibility to maintain the numelts field in the message header.

The routine used to send the message to the node is SNASendMessage.


2.6  The Dispatcher
The BASE/DMOD Interface	6 of 13

2.6  The Dispatcher

Whenever a base event occurs, the Base will call the link support code dispatcher routine SNALinkDispatchProc to handle the event. The term base event in this context means:

A message arriving from a local 2.1 node.

A base timer tick occurring — this relatively slow event happens approximately every five seconds.

Contact lost with a local 2.1 node (e.g. the machine being powered down).

The routine SNALinkDispatchProc should examine parameters passed to it by the Base to determine why it has been called (see sample code) and call an appropriate function to handle the event. When the event has been processed, control returns to the Base scheduler.


2.7  Receiving Messages
The BASE/DMOD Interface	7 of 13

2.7  Receiving Messages

The base will call the SNALink dispatcher routine SNALinkDispatchProc when a message is available for it.

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 SNASendMessage) or release it (using SNAReleaseBuffer). 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 SNAGetElement) or release existing ones (using SNAReleaseElement).


2.8  The Work Manager
The BASE/DMOD Interface	8 of 13

2.8  The Work Manager

When no work is currently outstanding, the Base thread of execution sleeps, waiting for events (or a maximum period of five seconds). SNALinks should signal the Base when an event occurs (such as data arriving on the link) by setting the Base global event. A handle to this event is passed on the SNALinkInitialize call.

When the Base is rescheduled, it will call the SNALink work manager routine SNALinkWorkProc. This routine should handle any link events that have occurred.

A common use of this routine is in an SNALink where there is a single thread that handles the protocol of the link but multiple threads suspended on synchronous calls to a driver read routine. When data is received from the link, it is placed on an internal queue, and the driver sets the global base event. This causes the Base to be scheduled, and SNALinkWorkProc is called. SNALinkWorkProc then dequeues messages and passes them to the base to be sent to the local node.


2.9  BASE/SNALink Entry Points
The BASE/DMOD Interface	9 of 13

2.9  BASE/SNALink Entry Points

This section gives definitions for the entry points to the BASE and DMOD and the entry points that must be supplied in an SNALink. They are divided into the categories SNALink, Buffer Management, and BASE.

In summary the entry points are:

SNALink

SNALinkInitialize	Initialize SNALink

SNALinkDispatchProc	Dispatcher

SNALinkWorkProc	Work manager

Buffer Management

SNAGetElement	Get buffer element

SNAReleaseElement	Release buffer element

SNAGetBuffer	Get buffer

SNAReleaseBuffer	Release buffer

Other BASE entry points

SNASendMessage	Send a message to the node

SNAGetLinkName	Get the name of the SNALink

SNASendAlert	Send a preformatted NMVT Alert to Netview

The following routines are defined in Chapter 5:

SNAGetConfigValue	Get a named item of configuration information

SNAGetSystemInfo	Get SNA Server system information

Note

Standard calling conventions [WINAPI] are used for all entry points including those provided by the IHV SNALink.

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


2.9.1  SNALink Entry Points
The BASE/DMOD Interface	10 of 13

2.9  BASE/SNALink Entry Points

2.9.1  SNALink Entry Points

The Base requires the following entry points to be exported by the IHV SNALink .DLL.

SNALinkInitialize — Initialize SNALink

The BASE will call this routine when the SNALink is loaded into memory.

C Declaration

VOID SNALinkInitialize (event)

HANDLE event;

Parameter		Description
event		A handle to the global Base event
Usage Notes

This function should:

Read in required configuration information.

Perform any required initialization of the hardware or device driver.

Set up control blocks, data structures required internally by SNALink.

SNALinkDispatchProc — Link Dispatcher

The Base will call this routine whenever one of the following events occurs:

A message arrives for the link

The Base timer expires

Contact is lost with the local node

C Declaration

VOID SNALinkDispatchProc (msgptr, function, index)

PTRBFHDR msgptr;

INTEGER function;

INTEGER index;

Parameter		Description
msgptr		The message to be processed, or NULL if some other event is being notified
function		The reason for SNALinkDispatchProc being called
locality		l-value (only valid for function SBLOST)
Usage Notes

The function code may take one of three values:

0		Message received
SBLOST		Contact lost with local node, l-value of locality
SBTICK		Base timer has expired — occurs every five seconds.
See example code for suggested usage of this routine.

SNALinkWorkProc — Work manager

The Base will call this routine whenever the global Base event is triggered by the SNALink,
or at least once every five seconds.

C Declaration

VOID SNALinkWorkProc ()

Usage Notes

This routine may be used to perform any general processing required by the SNALink, in particular to process messages received from the link.


2.9.2  Buffer Management Entry Points
The BASE/DMOD Interface	11 of 13

2.9  BASE/SNALink Entry Points

2.9.2  Buffer Management Entry Points

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

SNAGetElement — Get Buffer Element

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

C Declaration

VOID SNAGetElement (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. SNAGetBuffer 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.

SNAReleaseElement — Release Buffer Element

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

C Declaration

VOID SNAReleaseElement
(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. SNAReleaseBuffer 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.

SNAGetBuffer — Get Buffer

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

C Declaration

PTRBFHDR SNAGetBuffer (numelts)
INTEGER numelts;

Function Return Value

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

Parameter		Description
numelts		Number of elements required
Usage Notes

Each element has a size of 268 — the constant SNANBEDA in the header file SNA_DLC.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 SNAGetElement 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.

SNAReleaseBuffer — Release Buffer

The application calls this routine to release a buffer.

C Declaration

VOID SNAReleaseBuffer (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 SNAReleaseElement.


2.9.3  Other Base Entry Points
The BASE/DMOD Interface	12 of 13

2.9  BASE/SNALink Entry Points

2.9.3  Other Base Entry Points

SNASendMessage — Send a Message

The application calls this routine to send messages to other localities (in the case of an SNALink, the local 2.1 node).

C Declaration

VOID SNASendMessage (msgptr)

PTRBFHDR * msgptr;

Parameter		Description
msgptr		Pointer to message to be sent
Usage Notes

The LPI values on the message should be set up to reference the correct connection for the data to be passed.

SNAGetLinkName — Get the SNALink Name

The SNALink may call this routine to obtain its configured name.

C Declaration

VOID SNAGetLinkName(linkname)

UCHAR * linkname;

Parameter		Description
linkname		A pointer to a buffer where the NULL terminated SNALink namewill be stored
Usage Notes

The buffer should be at least 9 bytes in length.

SNASendAlert — Send a Preformatted NMVT Alert to NetView

The SNALink calls this routine to send a complete formatted NMVT alert to NetView.

C Declaration

VOID SNASendAlert (msgptr, severity)

PTRBFHDR msgptr;

INTEGER  severity;

Parameter		Description
msgptr		Pointer to the NMVT alert to be sent
severity		The severity of the problem which caused the alert (rangesfrom 0 to 16)
Usage Notes

The complete NMVT to be sent must be generated by the SNALink and inserted into a buffer. Only the elements are used — the buffer header need not be set up before sending. The fields startd and endd should be set to reflect the location of the NMVT within the element. Multiple elements may be used to store the NMVT, up to a maximum length of 512 bytes. The buffer will be freed by the Base once the NMVT has been sent.

Any NMVT sent refers to a particular SNA Server connection. It is recommended that the NMVT include at least a hierarchy resource list, giving the name of the remote PU the connection is associated with. This name is supplied to the SNALink on the OPEN(STATION) message.

For complete details of the format of an NMVT, see the IBM [image] manual SNA Formats (GA27-3136).


2.10  Sample Code
The BASE/DMOD Interface	13 of 13

2.10  Sample Code

This section contains outline source code for the link dispatcher routine SNALinkDispatchProc.

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

/* Firstly, include the SNA Server header files	*/

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

#include <sna_dlc.h>

#include <sna_cnst.h>

#include <trace.h>

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

/* The link dispatcher routine - SNALinkDispatchProc	*/

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

VOID SNALinkDispatchProc (msgptr, function, locality)

PTRBFHDR msgptr;

INTEGER  function;

INTEGER  locality;

{

INTEGER     discard_buff;

COM_ENTRY("Ldisp");

if (msgptr != NULL)

{

  TRACE4()"received message from local node"));

  discard_buff = FALSE;

  switch (msgptr->msgtype)

  {

    case OPENMSG:

           /* process the OPEN message */

           break;

    case CLOSEMSG:

           /* process the CLOSE message */

           break;

    case DLCDATA:

           /* Data to be sent on link */

           break;

    case DLCSTAT:

           /* Switch on the sub-type of the message */

           switch (msgptr->dshdr.dstype)

           {

             case STRESRCE :

                    /* call flow control processor */

                    break;

             case DLCSDXID:

                    /* call XID processor */

                    break;

             default:

                    discard_buff = TRUE;

                    break;

           }

           break;

    default:

           discard_buff = TRUE;

           break;

  }

  if (discard_buff)

  {

    /* message has not been processed by us, so simply discard */

    SNAReleaseBuffer(msgptr);

    msgptr = NULL;

  }

}

else if (function == SBLOST)

{

  /* Lost contact with local node 'locality'  */

  /* Terminate all connections on this node (matching destl-value) */

}

else if (function == SBTICK)

{

  /* 5 second timer tick */

}

COM_EXIT;

}

**


The Data Link Control Interface (DLC)
Chapter 3	1 of 17

The Data Link Control Interface (DLC)

3.1  Introduction

The Data Link Control Interface defines the interface between the local 2.1 node and an SNALink. The DLC interface is defined in terms of the messages that are sent across the interface. Note that this is logically distinct from the definition of the BASE/DMOD interface, which defines the API used to send messages between two components in SNA Server (for example, between the local node and an SNALink).

DLC messages are exchanged between the local node and an SNALink across LPI connections (see section 1.3).

The local node uses the DLC interface to:

Activate DLC connections.

Exchange Format 0 or Format 3 XIDs for station activation.

Exchange DLC information frames.

Handle DLC error notification.


3.1.1  Supported Configurations
The Data Link Control Interface (DLC)	2 of 17

3.1  Introduction

3.1.1  Supported Configurations

The 2.1 node supports the following configuration options:

Full range of station roles:

Primary DLC stations

Secondary DLC stations

DLC station role negotiation

For SDLC connections, the node allows:

Leased lines configured as:

Secondary point-to-point

Primary point-to-point or multipoint

Negotiable point-to-point

Switched lines (point-to-point only) with:

Remote PU identification via XID exchange

Auto Dial (with suitable hardware support)

Incoming Call support

For X.25 and 802.2, the node also supports:

Multiple connections over one physical link.

Incoming calls with validation of caller's address.

In addition, for X.25, the node supports:

Permanent and Switched Virtual Circuits (PVCs and SVCs).


3.2  Opening a Connection
The Data Link Control Interface (DLC)	3 of 17

3.2  Opening a Connection

The node is capable of supporting multiple connections through one or more SNALinks. For each connection, the node opens two LPI connections to the SNALink:

LINK LPI connection to handle activation and deactivation of the connection

STATION LPI connection to transfer data to and from the remote station

The one exception to this rule is the case of primary multipoint connections where there is a single link LPI connection and multiple station LPI connections. This special case is described in Section 3.6.

The following messages flow over the DLC interface and are used to activate a connection to a remote station.

Open (LINK) Request	(NODE > DLC, LINK)
Opens the LINK LPI connection between the node and the SNALink

Provides configuration data for the SNALink

Provides link connection data such as Token-Ring Address for the remote station

Open (LINK) Response	(DLC > NODE, LINK)
Reports whether the SNALink has accepted the Open (LINK) Request

Returns certain link-specific configuration parameters to the local node

Can be an OK-Response or Error-Response

Request-Open-Station	(DLC > NODE, LINK)
Passes an XID received from the SNALink up to the node

Indicates that the SNALink has received a mode setting command, such as SNRM over SDLC, or SABME over 802.2

Send-XID	(NODE > DLC, LINK)
Passes an XID from the node to the SNALink to be sent out over the link to the remote station

Open (STATION) Request	(NODE > DLC, STATION)
Opens the STATION LPI connection between the node and the SNALink

Specifies certain station-specific configuration information

Open (STATION) Response	(DLC > NODE, STATION)
Acknowledges Open (STATION) Request

Station-Contacted	(DLC > NODE, STATION)
Informs the local node that the link is now ready for data transfer

The use of these messages in activating various types of connections is described throughout the rest of this section. The format of the messages is given in Section 4.

The name of the Request-Open-Station message is historical. In earlier versions of the DLC interface, the Higher Level Software (such as the local node) always sent an Open (STATION) Request in response to this message — hence the name Request-Open-Station. However, now that multiple XIDs can be exchanged before the link is activated, the Open (STATION) Request is only sent at the end of the XID exchange.

The Request-Open-Station message now has two distinct semantic meanings:

as a "Receive-XID"

as a "Receive-Set-Mode"


3.2.1  Opening the LINK LPI Connection
The Data Link Control Interface (DLC)	4 of 17

3.2  Opening a Connection

3.2.1  Opening the LINK LPI Connection

The local node attempts to activate a connection:

During system initialization if the connection is configured as initially active.

If the System Administrator manually activates the connection.

If a 3270 or LU6.2 session is requested when there is no active connection to support the LU, and the connection is configured to be activated on demand.

For each connection to be activated, the local node opens a link LPI connection by sending an Open (LINK) Request to the SNALink. This message contains configuration data such as:

SDLC line type: Leased, Switched.

Operational role: Primary, Secondary or Negotiable.

Timeout values.

Retry limit values.

Line speed.

Half-duplex/full-duplex.

802.2 remote SAP address.

X-25 Facility data.

For incoming calls, the local node primes the SNALink by opening the link LPI connection, but does not perform an activation sequence at this stage (see Section 3.5).

The local node also inserts the first XID frame to be used (where applicable) and Link Connection Data to be used on a switched link. The Link Connection Data can be:

A telephone number for a manual or auto-dial modem (in this case, the SNALink software could dial the required number or send a message to the operator specifying the number to be dialed).

The MAC address of the remote station.

The X.25 remote DTE address.

Finally, the Open (LINK) contains various timeout values that should be used by the SNALink when setting up protocol timers.

The format of the Open (LINK) Request is given in section 4.1.

The SNALink should return an Open (LINK) OK Response if:

Its internal control blocks are successfully initialized.

Its device driver has installed correctly.

Its link hardware is successfully initialized.

The SNALink should not wait for an end-to-end connection before giving an Open (LINK) Response.

If the SNALink has successfully initialized, it should return an Open (LINK) OK-Response immediately, supplying the required link-specific configuration information to the node (such as the maximum BTU size it can support). The local node will use this information during XID negotiation with the remote station.

If the SNALink cannot initialize successfully, it responds with an Open (LINK) Error-Response containing an error code. The error is logged and the local node notifies the system operator before retrying the link activation.

If an XID is supplied on the Open (LINK) Request, this should be sent when the end-to-end connection is established for a primary or negotiable link. Note that the supplied XID can be a NULL XID, which has a zero length. Hence, it is important that the OPINIXID field is examined rather than checking for a zero XID length. An XID will be supplied for all connections except primary leased connections (which could be multipoint).

When an SNALink receives an XID frame from the remote station, it is passed to the local node in a Request-Open-Station message on the LINK LPI connection.

Figure 3.2.1 shows the Open (LINK) Request and Response, followed by an exchange of XIDs.

If the SNALink fails to receive any frames from the remote station, it generates an OUTAGE message as described in Section 3.4.

Figure 3.2.1    Message sequence when XID frame supplied in Open (Link) Request for a primary connection


3.2.2  Activating a Host Connection
The Data Link Control Interface (DLC)	5 of 17

3.2  Opening a Connection

3.2.2  Activating a Host Connection

Leased SDLC Line (No XIDs Exchanged), Channel Adapter

For a connection to a host computer using a leased SDLC line, the SNALink receives an SNRM once the end-to-end connection is established. The SNALink responds with a UA and informs the local node that the connection is ready for data transfer. This is done with the Request-Open-Station message with the Rcv-Set-Mode flag set.

The node then opens the Station LPI connection with the Open (Station) message. If the SNALink has an available control block, it responds with an Open (Station) OK-Response. This is followed by a Station-Contacted message.

A Channel connection is treated the same way as a leased secondary SDLC connection. Each Channel connection is associated with a channel subaddress in the range X'00' to X'FF'. The SNA Server Node will send the Channel link service an Open(LINK) Request for each configured Channel connection when the connection is activated. The link service should expect to receive multiple Open(LINK) Requests, one for each supported subchannel address. Separate link services will be installed for each Channel adapter on an SNA server.

Note that the Request-Open-Station message flows on the Link LPI connection, whereas the Station-Contacted message flows on the Station LPI connection.

The message flow for a leased line is shown in Figure 3.2.2.

Figure 3.2.2    Host connection using leased SDLC line

X.25, 802.2 or SDLC Switched Line (XIDs Exchanged)

The initial sequence for a host connection over X.25, 802.2 or a switched SDLC line is similar to the sequence over a leased line. The only difference is that XIDs are exchanged before the host (or Front End Processor) sends a mode-setting command such as QSM on an X25 QLLC link.

When the SNALink receives an XID, it is passed to the local node on a Request-Open-Station message (on the LINK LPI connection). The local node then passes DLC a Send-XID message (also on the LINK LPI connection) containing the XID to be sent to the host. The host typically checks the Node ID in this XID and, if it is valid, sends the mode-setting command.

The sequence is shown in Figure 3.2.3.

Figure 3.2.3    Host connection using X.25 switched virtual circuit

At the link level, a mode-setting command is required to enter information transfer state. For an SDLC link, this is an SNRM; for an X.25 QLLC link, this is a QSM; for a 802.2 link, an SABME. If the SNALink acknowledges the command (with a UA/QUA) immediately, it needs to buffer up any data that arrives on the link in the short window before the Open (STATION) Request arrives from the local node. The alternative is to wait for the Open (STATION) Request before sending the UA/QUA response.

For switched connections using SDLC modems, the Open (LINK) Request contains Dial Digits for manual or auto-dial modems. It is the responsibility of the SNALink to handle the management of these devices. For X.25 and 802.2 connections, the Open (LINK) contains the address of the remote station.

The SNALink should initiate the dialing procedure when it receives the Open (LINK) Request.


3.2.3  Activating a Peer Connection
The Data Link Control Interface (DLC)	6 of 17

3.2  Opening a Connection

3.2.3  Activating a Peer Connection

For a peer connection, there is an activation sequence that involves the two stations exchanging Format 3 XID frames. As part of this sequence, the two stations agree on their link roles. They also exchange information relating to the link level connection, such as the maximum frame size supported.

The node passes XIDs to the SNALink over the Link LPI connection using the Send-XID message. The SNALink returns received XIDs to the local node over the Link LPI connection using the Request-Open-Station message.

Figures 3.2.4 and 3.2.5 show examples of XID exchange for the two cases:

The link roles are explicitly configured for the two stations.

The link roles of both stations are negotiable.

Points to note are:

The Open (LINK) Request is supplied with a NULL XID that is sent once the end-to-end connection is established.

After the first NULL XID, all XIDs are Format 3.

If both stations are set up to be negotiable, the station with the higher Node ID becomes the primary.

If both stations are negotiable and have the same Node ID, both stations produce randomized Node IDs that are compared as before.

Fixed Link Roles

Figure 3.2.4 shows the sequence of messages for a peer connection where the local end is configured as the primary station and the remote end is configured as the secondary.

Figure 3.2.4    Peer connection with primary local and secondary remote

Negotiable Link Roles

Figure 3.2.5 shows the sequence of messages for a peer connection where both the local and remote ends are configured as negotiable. Since the remote Node ID is larger (numerically) than the local Node ID, the remote station will become primary.

local  Node ID	= X'05D11111'
remote Node ID	= X'05D22222'
Figure 3.2.5    Peer connection with negotiable local and negotiable remote

In summary, here are the rules that the SNALink must follow when supporting XID exchange, and in particular XID role negotiation:

1.	If an XID is supplied in the Open (LINK) Request, it must be transmitted as soon as the end-to-end connection is established for primary or negotiable links.

2.	All XIDs received from the remote station must be passed to the local node in a Request-Open-Station message.

3.	An XID received from the local node in a SEND-XID message must be transmitted immediately.

4.	XID transmissions must be retried until an XID is received from the remote station. For half-duplex links, the retry timeout should be randomized to prevent repeated XID clashes.

5.	When a mode-setting command (SNRM, QSM, SABME) is received before the station has been opened, a Request-Open-Station must be sent to the local node with the Rcv-Set-Mode flag on.

6.	When the local node sends an Open (STATION) message, the link should examine it to determine its link-role (i.e. Primary or Secondary).

7.	A secondary station should send a Station Contacted message after receiving and responding to the Open (STATION) message.

8.	For a primary station, the mode-setting command should be sent when the Open Station is received. The Station Contacted message should be sent to the local node when this command has been acknowledged by the secondary station (for instance, a UA received on an SDLC link).

If the local node detects an error during role negotiation, such as both PUs configured as primary, it sends out an XID containing an error vector. The vector is appended to the end of the normal XID data. The vector number specified is X'22' and the vector data specifies that the DLC role field is in error. Refer to the IBM publication SNA Formats for details of the XID formats and Error vectors.

After sending the error XID, the local node sends a Close (LINK) message to terminate the connection (see Section 3.4).

Figure 3.2.6 is a matrix of the possible combinations of station link roles and shows the eventual role of the local station.

The role of the local station is shown for different combinations of configured roles.

*The station with the higher Node ID becomes the primary

Figure 3.2.6    Matrix of link roles


3.2.4  Opening the STATION LPI Connection
The Data Link Control Interface (DLC)	7 of 17

3.2  Opening a Connection

3.2.4  Opening the STATION LPI Connection

After receiving a Request-Open-Station (RQOS) message, the local node sends an Open-Station message to the SNALink when:

The station is configured as secondary (or has negotiated to secondary), and the RQOS message has the Rcv-Set-Mode flag on, indicating that the SNALink has received a mode-setting command such as SNRM.

The station is configured as primary (or has negotiated to primary), the RQOS message contains a secondary XID, and the local station has sent at least one negotiation-proceeding XID.

The Open (STATION) Request contains the link index that was on the Open (LINK) Request. This allows the SNALink to correlate the Link and Station LPI connections for the case where the SNALink can support multiple connections to remote stations (such as X.25 and 802.2).

This Open (STATION) Request contains configuration data for the link station, such as:

SDLC address of the adjacent link station (X'00' for secondary station's, X'01' to X'FE' for primary stations)

The SNALink should use this address field for determining the local station's role. If it is set to X'00', the local station is a secondary. Otherwise, it is primary. This field has this meaning even when the address is not used because of the link type (such as 802.2).

The format of the Open (STATION) Request is given in section 4.3.

If the station cannot be initialized (perhaps due to a lack of resources), the SNALink responds with an Open (STATION) Error-Response containing the appropriate error code.


3.2.5  Node Identification and Signaling Information
The Data Link Control Interface (DLC)	8 of 17

3.2  Opening a Connection

3.2.5  Node Identification and Signaling Information

Refer to section 3.5 for details of the role an SNALink plays in node identification.

When XIDs are exchanged, there are two mechanisms for identifying the remote station:

The Node ID on received XIDs.

The DLC defined address (for example, the MAC Address). This is known as signaling information.

The presence of signaling information depends on the type of the SNALink. For instance, there is no signaling information over an SDLC link, but there is over X.25 and 802.2. The SNALink passes signaling information to the local node on the Request-Open-Station message by appending it after the XID. See Section 4.5 for the exact format of this message.

If signaling information is present, the local node checks it against the configured value in the Dial-Digits record of the SNA Server configuration file. For incoming call support, this allows the local node to determine the connection that is to be activated. See Section 3.5 for a fuller description of incoming calls.

If there is no signaling information, the local node compares control point name on the received XID with the "remote CP name" in the configuration.

If the remote station is identified correctly, XID exchange proceeds as detailed in the previous section. However, if there is a mismatch, the local node sends an XID (in the SEND-XID message) containing an error vector followed by a Close (LINK) Request, as shown in Figure 3.2.7.

Figure 3.2.7    XID exchange failure


3.2.6  XID Retries
The Data Link Control Interface (DLC)	9 of 17

3.2  Opening a Connection

3.2.6  XID Retries

When the local node specifies that the SNALink is to send an XID, either by supplying it on the Open (LINK) Request or by sending it on a SEND-XID message, it is the responsibility of the SNALink to perform any retries.

XIDs need to be retried because:

The remote station has not been started yet.

Frames may be lost on the line due to noise.

SDLC SNALinks should implement a contact timeout and a retry limit — values for these are provided on the OPEN(LINK) message. The timeout specifies how often the XID should be retried, and the retry limit specifies how many XIDs should be sent before abandoning the connection activation and sending an Outage to the local node. The Outage message is described in Section 4.4. The SNALink should stop retrying the XID when it receives an XID from the remote station, when an Open(STATION) message is received from the node or when a mode-setting command is received on the link.


3.2.7  Multiple Connections
The Data Link Control Interface (DLC)	10 of 17

3.2  Opening a Connection

3.2.7  Multiple Connections

For 802.2 and X.25 links, multiple connections may use the same physical link supported by a single instance of the SNALink software.

For each connection to a remote station, there is a link LPI connection and a station LPI connection (this is different from SDLC multipoint as described in Section 3.6). Hence, there can be multiple pairs of LPI connections between a local node and an SNALink. For each connection, the local node issues an Open (LINK) Request and after XID exchange, an Open (STATION) Request.

The local node is configured with a maximum number of connections that can be active at any one time. In addition, each potential connection is configured with the address of the remote station. This information is required when activating a connection, and is included in the Open (LINK) Request for an outgoing connection.


3.3  DLC Information Transfer
The Data Link Control Interface (DLC)	11 of 17

3.3  DLC Information Transfer

Once the local node has opened the link and station LPI connections and received a Station-Contacted message from the SNALink for a remote station, it can exchange data (using the DLC interface) with the PU and associated LUs at the remote station.

Data messages are contained within buffers. The Transmission Header (TH) of the SNA Path Information Unit is contained within the buffer header. The Request/Response Header (RH), if present, and Request/Response Unit (RU) are contained within one or more buffer elements. The TH is contained in the buffer header for historical reasons. Typically this will be copied by the SNALink into the element before startd, to keep the entire frame in contiguous memory locations. See section 4.10 for a description of the DLC data message format.

Note that all data messages to a specified remote station flow on the associated DLC STATION LPI connection, and not on the controlling DLC LINK LPI connection.


3.3.1  DLC Flow Control
The Data Link Control Interface (DLC)	12 of 17

3.3  DLC Information Transfer

3.3.1  DLC Flow Control

The flow of data messages at the DLC interface for each link station is flow controlled. For each direction of flow there is an initial "credit" of messages that may be transmitted.

Flow control is maintained by initial specification on the Open (STATION) Request and OK-Response messages, and by the sending of DLC Status Resource messages to give more credit from time to time.

The sender maintains a count of credit (starting at the initial value set on the OPEN(STATION) ) which is decremented for each DLC Data message sent. When the credit count reaches zero, no more DLC Data messages may be sent until more credit is received.

For flow in a given direction the amount of credit is specified by the recipient of the data, since it has to do any queueing. The initial credit values are passed on the Open (STATION) message (on the Request for the flow from the SNALink to the local node and on the Response for flow from the local node to the SNALink).

The initial credit for the flow from the SNALink to the local node is determined by the node. The initial credit for the flow from the local node to the SNALink is set by the SNALink software -a suggested value is 16.

If the SNALink runs out of credit to send to the local node, it should either queue the data or discard it and send no acknowledge. It should also start sending RNR (for example) when polled by a primary station. An example message flow with an SDLC SNALink is shown in Figure 3.3.1 with an initial credit of 3. When the SNALink runs out of credit, it does not acknowledge any further frames and starts sending RNR.

Figure 3.3.1    Flow control for the flow from an SDLC SNALink to the local node

For flow control from the local node to the SNALink, when the node runs out of credit it queues the data and applies back pressure on sessions using that station. There is thus end-to-end flow control in this direction, independent of any SNA pacing that may be in force.

The SNALink gives credit to the local node for the messages that have been transmitted, not for the messages for which acknowledgements have been sent. The amount of data queueing in the SNALink is kept down most of the time since frames will usually be acknowledged.

Flow control of the flow of data from the local node to the SNALink is shown in Figure 3.3.2, where the initial credit is assumed to be 2.

Figure 3.3.2    Flow control of the flow of data from the local node to the SNALink


3.4  Closing a Connection
The Data Link Control Interface (DLC)	13 of 17

3.4  Closing a Connection

The local node closes a connection to a remote station:

If the System Administrator manually deactivates the connection.

If the connection is configured as "on demand" and no 3270 or LU6.2 sessions are active.

If an outage has been reported by the SNALink.

The local node closes a connection by sending a Close (LINK) message. The SNALink then takes some action, such as lowering DTR on an SDLC link or issuing a DLC_CLOSE_STATION on a 802.2 connection. It then replies with a Close (LINK) OK Response as shown in Figure 3.4.1.

The case of multipoint connections is slightly different and is considered in section 3.6. The rest of this section is concerned with point-to-point connections.

Figure 3.4.1    Closing a connection


3.4.1  Outages
The Data Link Control Interface (DLC)	14 of 17

3.4  Closing a Connection

3.4.1  Outages

If the SNALink detects a link or station failure, it reports the failure by sending an Outage message to the node on either the Link or Station LPI connection depending on whether it is a link or station outage. Generally, a station outage indicates a problem at the remote station, and a link outage indicates a local or line problem.

When the local node receives an Outage message, it:

Logs an error containing the outage code.

Tidies up each session using the connection and informs applications of the failure (for instance, with a Comm Check code on a 3270 emulator).

Sends a Close (LINK) Request to the SNALink.

On receipt of the Close (LINK) Request, the SNALink should clear up its internal resources for the connection and send back a Close (LINK) Response.

Figure 3.4.2    Closing a connection after an outage

There is a special case when the node loses contact with the SNALink software. In this case the node is notified of this event (a "lost locality") and performs outage processing apart from sending messages to the SNALink.

The outage codes are not distinguished by the node, but they are logged. For the sake of consistency across SNALink implementations, the values listed below should be used.

SDLC

X'0D'	Internally generated for SNALink Lost Locality

X'11'	DSR failure

X'12'	CTS failure

X'14'	DCD failure

X'24'	Nonproductive receive retry limit exceeded

X'25'	Idle timeout retry limit exceeded

X'29'	Connection problem
subqual = X'00'	I-frame retransmission
subqual nonzero	XID retransmission

X'2D'	Abnormal modem response

X'2E'	Write timeout retry exceeded

X'A0'	XID exchange failed on multidrop line
subqual is address of secondary station

X'15'	DISC received

X'23'	Receive Buffer overrun

X'2C'	Invalid command received
subqual = X'03'	invalid N(R)
subqual = X'04'	invalid or unsupported command/response
subqual = X'05'	excess I-field

X'80'	DM received in Information Transfer State

X'81'	Discontact retry limit exceeded

X'82'	Contact retry limit exceeded

X'83'	Poll retry limit exceeded

X'84'	No Response retry limit exceeded

X'85'	Remote busy retry limit exceeded

X'86'	FRMR received
subqual = X'00'	no reason given
subqual = X'03'	invalid N(R)
subqual = X'04'	invalid or unsupported command/response
subqual = X'05'	excess I-field

X'87'	Invalid frame received
subqual = X'03'	invalid N(R)
subqual = X'04'	invalid or unsupported command/response
subqual = X'05'	excess I-field

X'88'	RIM received

X'89'	RD received

802.2

X'29'	Remote node not active

X'AB'	SABME received while connection active

X'AC'	FRMR sent

X'AD'	FRMR received

X'AE'	DISC/DM received

X'AF'	Link lost

X.25

X'37'	Loss of a virtual circuit

X'60'	SVC cleared down by remote station or network

X'61'	PVC has been reset by remote station or network

X'62'	Attempt to connect to remote station through SVC has failed

DFT

X'11'	DSR Failure

X'14'	DCD Failure

X'15'	Connection terminated by host


3.4.2  Connection Retries
The Data Link Control Interface (DLC)	15 of 17

3.4  Closing a Connection

3.4.2  Connection Retries

If an "initially active" or "operator started" connection is closed because of an outage, the node tries to reopen the connection periodically. This can be stopped by manually deactivating the connection. This retry mechanism is also used when the node attempts to open a connection but the SNALink software has not yet been started. On-demand connections are not retried automatically by the node, but will be retried if the user attempts to reactivate a session using the connection.

Note that this connection retry timer is totally separate from the timers specified on the Open (LINK) Request.


3.5  Incoming Call Support
The Data Link Control Interface (DLC)	16 of 17

3.5  Incoming Call Support

The local node allows an SNALink to be set up to support incoming calls. In this mode of operation, the node primes the SNALink by sending an Open (LINK) Request, but the SNALink does not attempt to activate the link until it receives an XID from a remote station.

The SNALink recognizes an Open (LINK) Request for an incoming call by the absence of a connection name in the DESTNAME field (this field is filled with ASCII blanks).

The incoming calls Open (LINK) Request requires an immediate response from the SNALink, just as in the case of an Open (LINK) Request for an outgoing call.

For an SDLC SNALink there can only ever be one OPEN(LINK) outstanding. However, 802.2 and X.25 allow the possibility of multiple connections being handled through a single SNALink. In these cases, for each configured connection that is primed to await incoming calls, the local node will send an OPEN(LINK) with a blank connection name to the SNALink.

When an incoming call is received by the SNALink, the received XID should be passed to the local node on any LPI connection that is primed for incoming calls. The LPI connection selected must then be used for all future messages relating to that incoming call.

It is not necessary for the SNALink to perform validation of incoming calls — this will be performed by the local node. However, if required, the SNALink may choose to validate calls before passing them to the node. A common example of this would be to ensure that only X.25 calls with a specific local address are passed through to the local node.

Figure 3.5.1    Incoming call support with an SNALink that supports two connections. A remote station calls in and uses connection A. The node sets up Connection B for incoming calls but then needs to open connection C. Since the SNALink only supports two connections, connection B is closed.


3.6  SDLC Multipoint Connections
The Data Link Control Interface (DLC)	17 of 17

3.6  SDLC Multipoint Connections

The node can support primary multipoint (also known as multidropped) links, both at the primary and secondary end. Multipoint is a special configuration for an SDLC leased link where a single SDLC line at the primary station can be used to communicate with up to 16 secondary stations. Special hardware is required to "fan out" the primary line so that there is a physical connection to each secondary station. Figure 3.6.1 shows an example with 3 secondary stations.

Figure 3.6.1    Example of SDLC multipoint system

The SDLC address of the secondary station is used to route frames to and from the individual secondary stations. Hence, the SNALink at the secondary station needs to check the SDLC address as the primary sends all frames to all secondary stations. The SNALink at the secondary station should only accept frames with its SDLC address — the other frames should be ignored.

From the viewpoint of the node at a secondary station, the message flow at the DLC interface is as for a point-to-point connection (described in Section 3.2). Indeed, the node need have no knowledge that this is a multipoint connection.

It is the primary end that has to handle the special processing required for multipoint connections. The remainder of this section concentrates on the primary station.

At the primary end, there are the following LPI connections:

One link LPI connection

A station LPI connection for each active secondary station

Since the XID exchange is carried out using the single link LPI connection, the Request-Open-Station and SEND-XID messages always specify the station address of the secondary station that the XID has arrived from or is going to. Note that no XID is supplied on the Open (LINK) Request.

Each station LPI connection has different values of I, the index. After the station has been activated, data messages flow on the station LPI connection rather than the link LPI connection.

Figure 3.6.2 shows the activation of two stations on a multipoint link, from the viewpoint of the primary end. The full exchange of Format 3 XIDs for each station is not shown but is the same as in Section 3.2. In addition, the figure shows the stations being activated one after the other. In fact, the stations can be activated simultaneously.

If the XID exchange fails because the secondary is failing to reply to the XID, the SNALink generates a special variant of link outage. Ideally, the SNALink would like to give a Station Outage, but this is not possible because the station LPI connection is not yet open. Instead, the SNALink generates a link outage with code X'A0' and a subqualifier that is the SDLC address of the station.

Once the stations are activated on a multipoint link, the majority of messages flow across the station LPI connections. If a connection to a particular secondary station is to be closed (because the operator deactivates it, for instance), the node issues a Close (STATION) Request. The SNALink replies with a Close (STATION) Response to the node and sends a DISC frame to the secondary station.

The SNALink can generate station outages and link outages. If the problem only affects a particular station, such as not responding to polls, the link generates a station outage and the node closes the station with a Close (STATION) Request. The SNALink responds with a Close (STATION) Response.

If the problem affects the link as a whole, such as the line being disconnected from the primary SDLC adapter, the SNALink generates a link outage and the node sends a Close (LINK) Request. The SNALink responds with a Close (LINK) Request.

Whenever the node receives a Close (STATION) Response, it checks to see if any stations are still active on the multipoint link. If not, a Close (LINK) Request is sent. The SNALink responds with a Close (LINK) Response. Figure 3.6.3 shows the message flows for outage processing.

Figure 3.6.2    Multipoint connection with two secondary stations (the full XID exchange is not shown)

Figure 3.6.3    Close processing for multipoint configuration with two secondary stations. Outage conditions are detected on both stations.

Note that the station messages are labeled in the figure with station addresses. In fact, the node and SNALink use the LPI addresses to identify the two stations.


SNA Device Interface Specification: Message Formats
Chapter 4	1 of 17

SNA Device Interface Specification: Message Formats

This section describes the SNA Device Interface Specification interface in terms of message formats. These are presented in a language-independent notation that is described below.

The messages used between the node and SNALinks are shown in the table below:

Message Type		Direction	LPI Connection
Open (LINK)Request		NODE ------> DLC	Link
Close(LINK)Request		NODE ------> DLC	Link
Send-XID		NODE ------> DLC	Link
Open (STATION) Request		NODE ------> DLC	Station
Close (STATION) Request		NODE ------> DLC	Station
Open (LINK) Response		NODE <------ DLC	Link
Close (LINK) Response		NODE <------ DLC	Link
Request-Open-Station		NODE <------ DLC	Link
Open (STATION) Response		NODE <------ DLC	Station
Close (STATION) Response		NODE <------ DLC	Station
Station-Contacted		NODE <------ DLC	Station
Outage		NODE <------ DLC	Link/Station
DLC-Data		NODE <-----> DLC	Station
Status-Resource		NODE <-----> DLC	Station
Details of the message format notation and key assumptions about the contents of the message formats are as follows:

Reserved indicates that the field must be 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 — the srci field in all messages, and fields such as opresid in Open(LINK) Request (see section 4.2) — 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 exception to this is the startd and endd fields in all elements, which are always stored in the processor's normal orientation.

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.

The startd field in each element gives the offset of the first byte of data in the element after the trpad field. Its value 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). (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].

All fields within dataru are of type unsigned character (UCHAR), except where the notes indicate otherwise.


4.1  Open(LINK)
SNA Device Interface Specification: Message Formats	2 of 17

4.1  Open(LINK)

Open(LINK) is used by the node to open the LINK LPI connection.


4.1.1  Open(LINK) Request
SNA Device Interface Specification: Message Formats	3 of 17

4.1.1  Open(LINK) Request

Flow : NODE ------> DLC

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header in a queue
hdreptr	PTRBFELT	Pointer to first buffer element
numelts	CHAR	Number of buffer elements - 1 (Number of elements can be 2 if the connection is for an X.25 SVC)
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 - LINK (X'10')
ophdr.opresid	INTEGER	Resource Identifier
Element 1
hdreptr->elteptr	PTRBFELT	Pointer to optional second buffer element (NULL if only one element)
hdreptr->startd	INTEGER	Index to start of data in this buffer element's data array
hdreptr->endd	INTEGER	Index to last byte of data in this buffer element's data array
hdreptr->dataru	CHAR[SNANBEDA]	Defined as follows, where s = startd - 1
dataru[s..s+9]		Source Name - Name of local node
dataru[s+10..s+19]		Destination Name - Name of Remote PU (blank for incoming calls)
dataru[s+20..s+21]		Link index
LINK DATA (depends on DLC type)
Unless otherwise stated, these fields are valid for outgoing calls only
SDLC LINK DATA
dataru[s+22]		XID supplied X'00' Don't send initial XID X'01' Send initial XID from this message (may be a NULL XID)
dataru[s+23]		Link Operational Role X'00' Primary X'01' Secondary X'02' Negotiable
dataru[s+24]		Use Reject_Command Indicator X'00' Do use it X'01' Do not use it
dataru[s+25]		Address match byte X'00' Primary/Negotiable SDLC X'01' to X'FE' Secondary SDLC
dataru[s+26]		Second SDLC address match byte X'00' Primary SDLC X'FF' Secondary/Negotiable SDLC
dataru[s+27]		Reserved
CHANNEL ADAPTER LINKDATA
dataru[s+22]		XID supplied X'00' Don't send initial XID X'01' Send initial XID from this message (may be a NULL XID)
dataru[s+23..s+24]		Reserved (may not be zero)
dataru[s+25]		Channel subaddress
dataru[s+26..s+67]		Reserved (may not be zero)
STATION TIMERS
dataru[s+28..s+29]		Contact timeout
dataru[s+30..s+31]		Contact Retry Limit
dataru[s+32..s+33]		Discontact timeout
dataru[s+34..s+35]		Discontact retry limit
dataru[s+36..s+37]		Negative poll timeout
dataru[s+38..s+39]		Negative poll retry limit
dataru[s+40..s+41]		T1 (no acknowledgment) timeout
dataru[s+42..s+43]		T2 (acknowledgment) timeout
dataru[s+44..s+45]		Remote station busy timeout
dataru[s+46..s+47]		Remote station busy retry limit
LINK TIMERS
dataru[s+48..s+49]		Idle timeout
dataru[s+50..s+51]		Idle retry limit
dataru[s+52..s+53]		Nonproductive Receive timeout
dataru[s+54..s+55]		Nonproductive Receive retry limit
dataru[s+56..s+57]		Write timeout
dataru[s+58..s+59]		Write retry limit
dataru[s+60..s+61]		Link Connection timeout
dataru[s+62..s+63]		Link Connection retry limit X'FFFF' for infinite retry
dataru[s+64..s+65]		Reserved
dataru[s+66]		Configuration Options Bit 0 : 1 = Constant Carrier selected Bit 1 : 1 = NRZI 0 = NRZ Bit 2 : = Reserved Bit 3 : 1 = Full Duplex 0 = Half Duplex Bit 4 : 0 = External clocking Bit 5 : 1 = Data Signal Rate Select  high 0 = Data Signal Rate Select low Bit 6 : 1 = Select Standby On 0 = Select Standby Off Bit 7 : = Reserved
dataru[s+67]		Configuration Options- line type X'00' leased X'01' switched manual dial X'02' switched auto-dial
Note For Configuration Options, Bit 0 is the most significant option and Bit 7 is the least significant. Reserved bits are not always zero, so always use a bitwise & operation when testing these bits. The Configuration Options byte is also valid for incoming calls.
Expanded Information About Message Formats for Open(LINK) Request with SDLC

The following list supplements the information found in the preceding table. The timers described in the lists are used by an SDLC link service to determine when to retry communication and when to generate outages. Generally, after the time interval specified by the timeout (usually 1000 milliseconds), the communication is retried. The cycle of timeout and retry is repeated until the retry limit is reached. Then an outage is sent by the SDLC link service.

With some timers, there are no communication retries. Such timers simply cycle through the timeout as many times as allowed in the "retry limit" (without actually retrying), then generate an outage.

Each description indicates whether you can configure the field through an SNA Server interface (such as SNA Server Admin). If the field is not configurable, the built-in setting for the field is shown.

For information about configuring with SNA Server Admin, see Chapter 3 of the Microsoft SNA Server Administration Guide, or the SNA Server Admin Help.

SDLC LINK DATA

dataru[s+22]	XID supplied

This field controls whether an initial XID is sent on this connection. The value used is determined by the leased/switched setting for the line:

Leased line: X'00'  Don't send an initial XID
Switched line: X'01'  Send an initial XID (may be a NULL XID)

A line is configured as leased or switched in SNA Server Setup.

dataru[s+24]	Use Reject_Command Indicator

This field determines that the link service will not send a Reject command (an SDLC command, not often used, value X'19') if a frame is received with an invalid NS (Next-to-Send) value. Instead, the link service waits until the next poll before requesting retransmission of the frame.

This field is not configurable and must remain at the setting of "Do not use."

STATION TIMERS (described for SDLC only)

dataru[s+28..s+29]	Contact timeout

dataru[s+30..s+31]	Contact retry limit

This timer is started when an XID or Set Normal Response Mode (SNRM) is transmitted. If the timeout expires without acknowledgment, the frame is retransmitted. When the number of retransmitted frames reaches the retry limit, an outage is generated. Note that for XIDs, the timeout value is randomized to prevent possible clashes between two servers sending XIDs simultaneously.

This timer is configurable in SNA Server Admin, in the Advanced settings for an SDLC connection.

dataru[s+32..s+33]	Discontact timeout

dataru[s+34..s+35]	Discontact retry limit

This timer is started when a Discontact (DISC) is sent. It is stopped when an Unnumbered Acknowledgment (UA) or Disconnect Mode (DM) is received. If the number of sent DISCs reaches the retry limit, an outage is generated.

This timer is not configurable. The Discontact timeout is 1000 milliseconds; the Discontact retry limit is 3.

dataru[s+36..s+37]	Negative poll timeout

dataru[s+38..s+39]	Negative poll retry limit

This timer is used for primary SDLC only. At intervals specified by the negative poll timeout, a Receive Ready (RR) is transmitted. The Negative poll retry limit is set at no limit; therefore, no outage is generated, no matter how many RRs are transmitted without acknowledgment being received.

The Negative poll timeout is configurable in SNA Server Admin, in the Advanced settings for an SDLC connection, where the timeout is called Poll Rate. Poll Rate is set in polls per second (and translated internally into the Negative poll timeout, timed in milliseconds).

The Negative poll retry limit is not configurable. It is set at -1, meaning no limit.

dataru[s+40..s+41]	T1 (no acknowledgment) timeout

dataru[s+42..s+43]	N2 (no acknowledgment) retry limit

This timer is used for primary SDLC and is started when a poll/final bit is expected. If the timeout expires before a frame containing a poll/final bit is received, an RR is sent. When the number of sent RRs reaches the retry limit, an outage is generated.

This timer is configurable in SNA Server Admin, in the Advanced settings for an SDLC connection, where it is called the Poll Timeout and Poll Retry Limit.

dataru[s+44..s+45]	Remote station busy timeout

dataru[s+46..s+47]	Remote station busy retry limit

This timer is used for primary SDLC and is started when a Receive Not Ready (RNR) is received. It is stopped when an RR is received. If the timeout expires the number of times specified by the retry limit, an outage is generated.

This timer is not configurable. The Remote station busy timeout is 1000 milliseconds; the Remote station busy retry limit is 30. Therefore, the time allowed before an outage is 30 seconds.

LINK TIMERS (described for SDLC only)

dataru[s+48..s+49]	Idle timeout

dataru[s+50..s+51]	Idle retry limit

This timer is configurable in SNA Server Admin, in the Advanced settings for an SDLC connection.

dataru[s+52..s+53]	Nonproductive Receive timeout

dataru[s+54..s+55]	Nonproductive Receive retry limit

This timer is used for secondary SDLC only and is started when any frame is received for this station. It is stopped when additional frames are received for this station. If the timeout expires the number of times specified by the retry limit, the link service causes a pop-up message, but does not generate an outage (because multidrop lines can be very slow).

This timer is not configurable. The Nonproductive Receive timeout is 1000 milliseconds (1 second); the Nonproductive Receive retry limit is 60. Therefore, the time allowed before a pop-up message is 60 seconds.

dataru[s+56..s+57]	Write timeout

dataru[s+58..s+59]	Write retry limit

This timer is started after an information frame has been transmitted to the hardware and stopped when the hardware acknowledges the frame. If the timeout expires the number of times specified by the retry limit, an outage is generated.

This timer is not configurable. The Write timeout is 1000 milliseconds (1 second); the Write retry limit is 15. Therefore, the time allowed before an outage is 15 seconds.

dataru[s+60..s+61] Link Connection timeout

dataru[s+62..s+63] Link Connection retry limit

This timer is started when an Open Link for a leased line is received, and stopped when Data Set Ready (DSR) is raised. If the timeout expires the number of times specified by the retry limit, an outage is generated.

This timer is not configurable. The Link Connection timeout is 1000 milliseconds (1 second); the Link Connection retry limit is 300. Therefore, the time allowed before an outage is 300 seconds.

X.25 LINK DATA
dataru[s+22]		Circuit Type X'00' PVC X'01' SVC
dataru[s+23]		PVC Alias, starting at 1 for lowest PVC channel number (reserved for SVC)
dataru[s+24..s+25]		PVC packet size (reserved for SVC)
dataru[s+26]		Default level 3 window size for PVC (reserved for SVC)
dataru[s+27]		Link Role X'00' Primary X'01' Secondary X'02' Negotiable
802.2 LINK DATA
dataru[s+22]		Maximum receives without a transmit acknowledgment
dataru[s+23]		Maximum transmits without a receive acknowledgment
dataru[s+24]		Dynamic window increment value
dataru[s+25]		Remote SAP address
dataru[s+26]		Local SAP address (for incoming calls)
dataru[s+27]		Value for t1 timer multiplier
dataru[s+31]		Value for t2 timer multiplier
dataru[s+35]		Value for t3 timer multiplier
Note that if the above fields for timer multipliers are set to zero, the SNALink should use appropriate defaults
dataru[s+42]		Maximum retry count (N2 Value)
Note that this 802.2 link data is required for the 802.2 command DLC.OPEN.STATION
END OF LINK DATA SECTION
dataru[s+68..s+69]		Length of link Connection Data (= a)(X'0000') None present
dataru[s+70..s+70+a]		Link Connection Data
dataru[s+70+b..s+71+b]		Where b is maximum of a and 20. Size of XID I-frame (= n) (X'0000') NULL XID
dataru[s+72+b]		XID
Note that if there are 20 or fewer bytes of link connection data, the XID length is at s+90 and the actual XID starts at s+92
The link connection data can contain one of:

MAC address of remote station

X.25 address of remote station

Dial-digits for manual or auto-dial modems

Optional Second Element (Only Used by X.25 SVC)

Element 2
Field		Type	Description
hdreptr->elteptr->elteptr		PTRBFELT	Pointer to next buffer element NULL
hdreptr->elteptr->startd		INTEGER	Index to start of data in this buffer element's data array - 1
hdreptr->elteptr->endd		INTEGER	Index to last byte of data in this buffer element's data array
hdreptr->elteptr->dataru		CHAR[SNANBEDA]	Defined as follows, where s = startd -1
dataru[s]			Length of Facilities Data field (= c) inclusive of this length byte X'01' no Facilities Data
dataru[s+1..s+c-1]			CHAR[c-1] Facilities Data
dataru[s+c]			CHAR Length of User Data field (= d) inclusive of this length byte X'01' no User Data
dataru[s+c+1..s+c+d]			User Data


4.1.2  Open(LINK) Response
SNA Device Interface Specification: Message Formats	4 of 17

4.1.2  Open(LINK) Response

Flow : DLC ------> NODE

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header in a queue
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 - LINK (X'10')
ophdr.opresid	INTEGER	Resource Identifier
ophdr.operr1	INTEGER	Error code (see below)
ophdr.operr2	INTEGER	Reserved
hdreptr->elteptr	PTRBFELT	Pointer to next buffer element - NULL
hdreptr->startd	INTEGER	Index to start of data in this buffer element's data array - 1
hdreptr->endd	INTEGER	Index to last byte of data in this buffer element's data array
hdreptr->dataru	CHAR[SNANBEDA]	Defined as follows, where s = startd - 1
dataru[s..s+9]		Source Name  —  same as destination name from Open(LINK) Request
dataru[s+10..s+19]		Destination Name — name of local node; same as source name from Open(LINK) Request.
dataru[s+22..s+23]		Maximum BTU size supported bySNALink
The error codes (for an ERROR-RESPONSE) are defined as follows in SNA_CNST.H:

Symbolic constant		Value		Description
ERINIFAIL		X'01'		Hardware Initialization Failed
ERINVXID		X'08'		Invalid XID Length
ERLINKOPN		X'09'		Link already open
ERLLCERR		X'0A'		LCC error; fatal hardware failure
ERBADINDX		X'0B'		Invalid link index
ERBADOPN		X'0C'		Open(LINK) has insufficient data
ERCONNTO		X'0D'		Link connection timeout
ERNORES		X'0E'		Maximum connection count reachedOR No more internal control blocks
EROPNPND		X'11'		Close(LINK) arrived while Open(LINK) pending
ERDUPREQ		X'12'		Duplicate request


4.2  Close(LINK)
SNA Device Interface Specification: Message Formats	5 of 17

4.2  Close(LINK)

4.2.1  Close(LINK) Request

Flow : NODE ------> DLC

Field		Type		Description
Header
nxtqptr		PTRBFHDR		Pointer to next buffer header in a queue
hdreptr		PTRBFELT		Pointer to first buffer element - NULL
numelts		CHAR		Number of buffer elements - 0
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 Type - LINK (X'10')
Note:

The message consists of a buffer header only.


4.2.2  Close(LINK) Response
SNA Device Interface Specification: Message Formats	6 of 17

4.2.2  Close(LINK) Response

Flow : DLC ------> NODE

Field		Type		Description
Header
nxtqptr		PTRBFHDR		Pointer to next buffer header in a queue
hdreptr		PTRBFELT		Pointer to first buffer element  - NULL
numelts		CHAR		Number of buffer elements - 0
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') - RSPERR (X'03')
clhdr.clstype		CHAR		Close Type - LINK (X'10')
clhdr.clserr1		INTEGER		Error code (see below)
The error codes (for an ERROR-RESPONSE) are defined as:

X'03'		Link not open
X'04'		Invalid Link index

Note:

The message consists of a buffer header only.

The Close(LINK) message unconditionally shuts down the link.


4.3  Open(STATION)
SNA Device Interface Specification: Message Formats	7 of 17

4.3  Open(STATION)

4.3.1  Open(STATION) Request

Flow : NODE ------> DLC

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header in a queue
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 - REQU (X'01')
ophdr.opentype	CHAR	Open Type - STAT (X'11')
ophdr.opresid	INTEGER	Resource Identifier
ophdr.icreditr	INTEGER	Initial Credit for flow DLC -> NODE
Element
hdreptr->elteptr	PTRBFELT	Pointer to optional second buffer element (NULL if only one element)
hdreptr->startd	INTEGER	Index to start of data in this buffer element's data array - 1
hdreptr->endd	INTEGER	Index to last byte of data in this buffer element's data array
hdreptr->dataru	CHAR[SNANBEDA]	Defined as follows, where s = startd - 1
dataru[s..s+9]		Source Name -- name of local node
dataru[s+10..s+19]		Destination Name
dataru[s+20..s+21]		Link index as specified in Open(LINK) Request
dataru[s+22]		If NODE is primary, address of secondary station to initiate contact procedure with.X'00' if NODE is secondary
dataru[s+23]		FID2 indicator X'00' FID2 used
dataru[s+24]		Station Type X'00' Subarea X'01' Peer
dataru[s+25..s+26]		Length of Network Name from received XID '0000' = No name
dataru[s+27..s+27+n]		Network name from received XID, in local character set, or if this is null, the name of the remote PU record in the COM.CFG file.This name can be fully qualified and has a maximum length of 17 characters.
dataru[s+44..s+89]		Link Data — a copy of that supplied on the Open(LINK) Request.
dataru[s+90..s+91]		Maximum BTU size to be used with this station.


4.3.2  Open(STATION) OK Response
SNA Device Interface Specification: Message Formats	8 of 17

4.3.2  Open(STATION) OK Response

Flow : DLC ------> NODE

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header in a queue
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')
ophdr.opentype	CHAR	Open Type - STAT (X'11')
ophdr.opresid	INTEGER	Resource Identifier
ophdr.icreditr	INTEGER	Initial Credit for flow DLC -> NODE
ophdr.icredits	INTEGER	Initial Credit for flow NODE -> DLC
Element
hdreptr->elteptr	PTRBFELT	Pointer to next buffer element (NULL is only one element)
hdreptr->startd	INTEGER	Index to start of data in this buffer element's data array-1
hdreptr->endd	INTEGER	Index to last byte of data in this buffer element's data array
hdreptr->dataru	CHAR[SNANBEDA]	Defined as follows, where s = startd-1
dataru[s..s+9]		Source Name  —same as destination name from Open(STATION) Request
dataru[s+10..s+19]		Destination Name —name of local node; same as source name from Open(STATION) Request


4.3.3  Open(STATION) Error Response
SNA Device Interface Specification: Message Formats	9 of 17

4.3.3  Open(STATION) Error Response

Flow : DLC ------> NODE

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header in a queue
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 - RSPERR (X'03')
ophdr.opentype	CHAR	Open Type - STAT (X'11')
ophdr.opresid	INTEGER	Resource Identifier
ophdr.operr1	INTEGER	Error code
ophdr.operr2	INTEGER	Reserved
Element
hdreptr->elteptr	PTRBFELT	Pointer to next buffer element (NULL is only one element)
hdreptr->startd	INTEGER	Index to start of data in this buffer element's data array - 1
hdreptr->endd	INTEGER	Index to last byte of data in this buffer element's data array
hdreptr->dataru	CHAR[SNANBEDA]	Defined as follows, where s = startd - 1
dataru[s..s+9]		Source Name
dataru[s+10..s+19]		Destination Name
The error codes are defined as follows:

Symbolic constant		Value		Description
ERLKNOTOPEN		X'03'		Link not open
ERSTATOPEN		X'05'		Station already open
ERNOCB		X'06'		Station control blocks depleted
ERINVINDX		X'07'		Invalid Link Index
ERMAXSTAT		X'08'		Limit for number of stations per Link reached
ERDIFADDR		X'09'		Address different from on Request-Open-Station
ERBADADDR		X'0A'		Invalid DLC address


4.4  Close(STATION)
SNA Device Interface Specification: Message Formats	10 of 17

4.4  Close(STATION)

4.4.1  Close(STATION) Request

Flow : NODE ------> DLC

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header in a queue
hdreptr	PTRBFELT	Pointer to first buffer element  - NULL
numelts	CHAR	Number of buffer elements - 0
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 Type - STAT (X'11')
Note:

The message consists of a buffer header only.


4.4.2  Close(STATION) Response
SNA Device Interface Specification: Message Formats	11 of 17

4.4.2  Close(STATION) Response

Flow : DLC ------> NODE

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header in a queue
hdreptr	PTRBFELT	Pointer to first buffer element - NULL
numelts	CHAR	Number of buffer elements - 0
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.clsequal	CHAR	Close Qualifier  - RSPOK (X'02') - RSPERR (X'03')
clhdr.clstype	CHAR	Close Type  - STAT (X'11')
clhdr.clserr1	INTEGER	Error code
The error codes (for an ERROR-RESPONSE) are defined as:

aa		Station not open
X'04'		Link not connected
X'05'		Invalid Station index
X'06'		Duplicate request
Note:

The message consists of a buffer header only.

The Close(STATION) message unconditionally closes the station connection.


4.5  Request-Open-Station
SNA Device Interface Specification: Message Formats	12 of 17

4.5  Request-Open-Station

Flow : DLC ------> NODE
(Link connection)

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header in a queue
hdreptr	PTRBFELT	Pointer to first buffer element if present
numelts	CHAR	Number of buffer elements
msgtype	CHAR	Message type -DLCSTAT (X'11')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
dshdr.dstype	CHAR	Status Type -RQOPNSTN (X'16')
dshdr.dsqual	CHAR	Station address on XID or Mode-Set command.Set to X'01' for 802.2
dshdr.dsmdset	CHAR	Rcv-Set-Mode Flag X'00' XID received X'01' Mode Set Command received for example, SNRM for SDLC SABME for 802.2 QSM for X.25
Element
hdreptr->elteptr	PTRBFELT	Pointer to next buffer element (NULL is only one element)
hdreptr->startd	INTEGER	Index to start of data in this buffer element's data array - 1
hdreptr->endd	INTEGER	Index to last byte of data in this buffer element's data array
hdreptr->dataru	CHAR[SNANBEDA]	Defined as follows, where s = startd-1
dataru[s..s+n-1]		XID-starting at first byte of received XID information field. X'00' NULL XID received (n = 1) and signaling information present.
Optional Signaling information
dataru[s+n]		Length of data, including this bytes
dataru[s+n+1]		Type of data-not used at present
dataru[s+n+2..s+m]		Address or other ID data. For example, MAC address of remote station X.25 address of remote station
Note:

The signaling information is used by the node to identify the remote station on 802.2 and X.25 links.

If a NULL XID is received and no signaling information is required, the element can be omitted.

If a NULL XID is received and signaling information is required, an X'00' byte should be put in the element followed by the signaling information.

If the Rcv-Set-Mode Flag is set to X'01', the element can be omitted.


4.6  Station-Contacted
SNA Device Interface Specification: Message Formats	13 of 17

4.6  Station-Contacted

Flow : DLC ------> NODE
(station connection)

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header in a queue
hdreptr	PTRBFELT	Pointer to first buffer element -NULL
numelts	CHAR	Number of buffer elements -0
msgtype	CHAR	Message type -DLCSTAT (X'11')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
dshdr.dstype	CHAR	Status Type -STNCTCTD (X'17')
Note:

This message contains a buffer header only.


4.7  Outage
SNA Device Interface Specification: Message Formats	14 of 17

4.7  Outage

Flow : DLC ------> NODE
(link or station connection)

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header in a queue
hdreptr	PTRBFELT	Pointer to first buffer element -NULL
numelts	CHAR	Number of buffer elements -0
msgtype	CHAR	Message type -DLCSTAT (X'11')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
dshdr.dstype	CHAR	Status Type OUTAGE (X'18')
dshdr.dsqual	CHAR	Outage Qualifier
dshdr.dsoutsq	CHAR	Outage subqualifier (optional)
Note:

This message contains a buffer header only.

Outage qualifier codes are given in section 3.4.


4.8  Status-Resource
SNA Device Interface Specification: Message Formats	15 of 17

4.8  Status-Resource

Flow : DLC <------> NODE
(station connection)

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header in a queue
hdreptr	PTRBFELT	Pointer to first buffer element -NULL
numelts	CHAR	Number of buffer elements -0
msgtype	CHAR	Message type -DLCSTAT (X'11')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
dshdr.dstype	CHAR	Status Type RESOURCE (X'04')
dshdr.dlccred	INTEGER	DLC Credit
Note:

This message contains a buffer header only.

The dlccred field indicates that the message sender can receive a further dlccred DLC Data messages.


4.9  Send-XID
SNA Device Interface Specification: Message Formats	16 of 17

4.9  Send-XID

Flow : NODE ------> DLC
(link connection)

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header in a queue
hdreptr	PTRBFELT	Pointer to first buffer element
numelts	CHAR	Number of buffer elements - 1
msgtype	CHAR	Message type -DLCSTAT (X'11')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
dshdr.dstype	CHAR	Status Type SENDXID (X'1A')
dshdr.dsqual	CHAR	Station address on XID
Element
hdreptr->elteptr	PTRBFELT	Pointer to next buffer element (NULL is only one element)
hdreptr->startd	INTEGER	Index to start of data in this buffer element's data array-1
hdreptr->endd	INTEGER	Index to last byte of data in this buffer element's data array
hdreptr->dataru	CHAR[SNANBEDA]	Defined as follows, where s = startd-1
dataru[s..s+n-1]		XID information frame.
Note:

The dshdr.dsqual field is valid only for primary multipoint connections where station is specified on a multidrop line that the XID should be sent to. In all other cases, it is set to 0xFF.

In situations where the link protocol requires the address field on the XID to be set to a value other than 0xFF (for example, to specify that the XID is a response), it is the responsibility of the link service to set this byte appropriately.


4.10  DLCDATA
SNA Device Interface Specification: Message Formats	17 of 17

4.10  DLCDATA

Flow : DLC <------> NODE

Field	Type	Description
Header
nxtqptr	PTRBFHDR	Pointer to next buffer header in a queue
hdreptr	PTRBFELT	Pointer to first buffer element
numelts	CHAR	Number of buffer elements
msgtype	CHAR	Message type -DLCDATA (X'10')
srcl	CHAR	Source Locality
srcp	CHAR	Source Partner
srci	INTEGER	Source Index
destl	CHAR	Destination Locality
destp	CHAR	Destination Partner
desti	INTEGER	Destination Index
ddhdr.ddth01	CHAR[6]	Transmission header
Element
hdreptr->elteptr	PTRBFELT	Pointer to next buffer element (NULL is only one element)
hdreptr->startd	INTEGER	Index to start of data in this buffer element's data array-1
hdreptr->endd	INTEGER	Index to last byte of data in this buffer element's data array
hdreptr->dataru	CHAR[SNANBEDA]	Defined as follows, where s = startd-1
dataru[s..s+n-1]		SNA Request Header (RH) if present, and Request Unit (RU)


Setup Information
Chapter 6	1 of 33

Setup Information

6.1  Introduction

The Windows NT Setup Engine is designed to maximize versatility and minimize the work required to produce robust, full-featured Setup programs. The Engine contains most of the functions that a Setup program might need and provides a scripting language similar to BASIC in which entire Setup programs can be written. This language is somewhat documented in the reference manual Microsoft Windows 3.1 GUI Setup Toolkit, Chapter 3, "The .INF File."

The SNA Server main Setup program is such a script (as is the Setup program for Windows NT itself). As part of setting up the SNA Server, the user chooses and installs support for various kinds of link services, and each different type of link service comes with its own script, which gets called from the main SNA Setup as a subroutine to perform all the tasks required for setting up that particular link.

Installing any link service requires some common steps to be performed; beyond these, the installation process may vary widely among different link types. For example, the IBM DFT link service setup needs to install a device driver for the DFT card, but the 802.2 link service relies on the existing Token Ring or Ethernet adapter and doesn't need to install a device driver — but it does have to install the DLC transport if it's not already installed. Having some degree of commonality allows all link service setup scripts to share the same basic format and keeps the interface to the main SNA Server setup script relatively simple.

Since each SNA link service is actually part of the machine's "network ensemble," the SNA Server setup script (and the link service Setup scripts) have been designed to work with the Windows NT Network Control Panel Applet (NCPA). Adapter cards, device drivers, and link services for SNA communications that have been installed and configured by the SNA Setup program can be configured from the NCPA as well, hopefully resulting in fewer confused users.

You are not required to write your entire link service setup program as an .INF script. The actual script might merely launch a custom executable to perform the installation; in this case the script would just provide the interface to the main SNA Setup script. In addition, you may create custom Dynamic Link Libraries (DLLs) that contain code and resources for doing certain Setup jobs. The Windows NT Setup Engine already has such a DLL (SETUPDLL.DLL in the SYSTEM32 subdirectory of the root directory for Windows NT), which contains many useful Setup functions.

The available documentation for the Setup Engine, the scripting language, and the support DLL is sparse at best. However, much can be learned by examining the existing .INF files both for SNA setup (in the "system\hwsetup" and root directories of your SNA Server tree) and for Windows NT itself (in the SYSTEM32 subdirectory of the root directory for Windows NT). Note that the main entry point for an .INF script is the "[Shell Commands]" section. You can list the contents of the support DLL with the command: "link32 -dump -exports setupdll.dll," and search the scripts for calls to "LoadLibrary" and "LibraryProcedure." If you need further assistance, Microsoft Product Support should be able to help.


6.2  Setup File Structure
Setup Information	2 of 33

6.2  Setup File Structure

6.2.1  Link Service Setup Interface

Inside the link service setup scripts, each of the components that need to be installed are listed as "options." Two types of options used are main options and additional options. The main option usually represents the "high-level" view of what's being installed (the link service itself), and the additional options represent the other "subcomponents" that are needed (such as device drivers or other system services). For example, in the IBM DFT install script, the main option is "IBMDFTLS" (IBM DFT Link Service) and the only additional option is "IBMDFTDD" (IBM DFT Device Driver). These names are arbitrary, but should be chosen to reflect what's being installed. Each option has a number of other attributes, such as a title (in this case, something like "IBM DFT Link Service Support," and a version, such as "2.3."

At link service install time, main SNA Setup enumerates all the .INF files (link service setup scripts) in a certain directory and calls each one in turn, saying "Tell me who you are and what main options you have," and the LS script replies with its main options and attributes. The titles from each main option appear in the user's "Select A Link Type To Install" list box, and when one is double-clicked on, main Setup calls that LS script saying "Okay, tell me what your additional options are," to which the LS script replies with its list of additional options. Then, main Setup calls the LS script for each of its additional options, saying "Install your option <whatever>," and finally, calls it one last time saying "Now install your main option."

Each component can be configured to permit installation of only one instance of itself, or many instances, depending on the needs of the link service. This allows a device driver to be installed once and have only one link service running on it, as is the case of IBM DFT support, or to have several instances of a link service on top of one device driver, as is done for IBM SDLC support. You could also have one link service using several device drivers — mix and match.

An SNA Server Link Service setup script usually requires three files to work properly: the script itself (.INF), the Setup Resource Library (.SRL), and the on-line help (.HLP). The Setup Resource Library is a special Dynamic Link Library (.DLL) that contains the dialog boxes, icons, and other resources needed by a particular script. Creation and use of customized SRLs will be discussed later in this chapter. The on-line help file is a standard Windows help file, meant to be used with the Windows Help Engine. While references to these files may be removed from the scripts if they are not needed, it is recommended that stubs be placed for these files rather than removing the references.


6.2.2 Floppy Disk Layout
Setup Information	3 of 33

6.2  Setup File Structure

6.2.2 Floppy Disk Layout

The link service installation system was written with the assumption that IHV link services would be installed from a floppy disk during or after the initial SNA Server setup process. For each different link service on a particular floppy, main Setup looks in the root directory for its .INF, .SRL, and .HLP file and expects to find a subdirectory of the same name as the .INF file (without the .INF extension) where all other files for that link service are kept. For example, a floppy containing two different link services ("FastLink" and "SlowLink," for example) would have in its root directory two .INF files (FASTLINK.INF and SLOWLINK.INF), two .SRL files (FASTDLG.SRL and SLOWDLG.SRL), two .HLP files (FASTLINK.HLP and SLOWLINK.HLP), and the directories FASTLINK and SLOWLINK. Other files for these link services (device driver binaries, libraries, config files, and so on.) reside in their respective directories. The names used here are suggestions only, and you can call these files whatever you want, as their names are just constants in the .INF scripts.


6.2.3 The Setup Resource Library
Setup Information	4 of 33

6.2  Setup File Structure

6.2.3 The Setup Resource Library

The Setup Resource Library (.SRL) file contains resources for the dialog templates that setup will use. This file is built in the same manner as a dynamically linked library (.DLL) but is renamed to minimize confusion. Setup loads the SRL once and keeps a handle to it; then when it needs to pop up a dialog, Setup uses the stored handle and the dialog template name to fetch the dialog from the library.

The SRL may be built by using the template and makefile found in the "\setup\dlgdll" directory on the SDK diskette. Here's a list and brief description of the files to be found there:

DLLINIT.C	Contains startup and initialization code for the SRL to be used by Setup as a resource. This file is common to every SRL and should not be changed.

TEMPLATE.H	This file contains many of the constant declarations that setup uses to recognize controls such as radio buttons and checkboxes. These constants may be added to but should not be modified.

TEMPLATE.DLG	Contains the actual definitions of what the dialogs look like, their size and position, their replaceable text, their buttons and other controls, where their icons and/or bitmaps are located, etc.

TEMPLATE.RC	This file lists all the resources to be compiled into the library — dialogs, icons, bitmaps, strings, and so on. It's the input file for the Resource Compiler (RC.EXE) and includes TEMPLATE.DLG.

TEMPLATE.RES	This is the binary output of the Resource Compiler and is converted to an object file (.OBJ) and linked with DLLINIT.OBJ to produce the SRL. This file is also the input for the Dialog Editor, which writes out a new .RES, .DLG, and .H if you change something.

MAKEFILE	This file should be used with NMake to build the SRL. It should be edited to ensure that the path and filenames are correctly assigned.


6.2.4  Replaceable Text in Setup Resource Libraries
Setup Information	5 of 33

6.2  Setup File Structure

6.2.4  Replaceable Text in Setup Resource Libraries

In the dialog definition file (.DLG), most of the text strings in the dialog start with an at sign (@). This is the mechanism by which a single dialog can be used for multiple purposes inside a Setup script. If the text is "@Text1," for example, the script may set a symbol called "Text1" to some arbitrary text before displaying the dialog, and when the dialog comes up, the new text will occupy the position where "@Text1" is in the dialog definition. This also applies to list box and edit field titles, text on button faces, and so on.

One good use for this feature is error handling — a single dialog box with caption "@ErrorString," text "@ErrorDesc," and buttons "@Button1" and "@Button2" could be used to display information about many different possible errors, for example, set ErrorString="Fatal Setup Error" and ErrorDesc="Some Important File Is Corrupted." The buttons at the bottom of the dialog box could be changed by setting Button1="Ignore Error" and Button2="Try Again." Look at the existing .INF scripts for examples.


6.2.5  The On-line Help File
Setup Information	6 of 33

6.2  Setup File Structure

6.2.5  The On-line Help File

The context sensitive on-line help (.HLP) file must be a standard Windows help file. It is written in "Rich Text Format" and compiled into WINHELP format. The first page in this file should be a contents page, and it should contain a page for each individual context-sensitive help message required. When the user presses the HELP button in a dialog, the setup engine calls WINHELP with the script's help file and the HelpContext ID. See the existing .INF scripts for examples.


6.3  Setup Registry Architecture
Setup Information	7 of 33

6.3  Setup Registry Architecture

There are two main subtrees in the Windows NT System Registry where information is kept relevant to SNA Server: the SOFTWARE tree and the SYSTEM tree. Both of these are subtrees of HKEY_LOCAL_MACHINE. The SOFTWARE tree contains generic information about IHV link services, and the SYSTEM tree contains information about the individual components of those services. While reading the following, it may be helpful to view examples of what's being discussed by inspecting the registry of an existing system with several of the built-in link services installed.


6.3.1  Product Entries
Setup Information	8 of 33

6.3  Setup Registry Architecture

6.3.1  Product Entries

All of the information relevant to the product as a whole will reside in the Registry under the key SOFTWARE\Microsoft. Each product or link support will have an entry whose name consists of the product name and version separated by an underscore. This key will contain most of the information about the product, such as the script name and option name that control it as well as the service name for that particular instance.

Each instance key must also have a NetRules key. This key contains all of the information for the Network Control Panel Applet bindings.

SNA Server Setup writes the path of the root directory of the machine's SNA Server tree into the key SOFTWARE\Microsoft\SNA Server \CurrentVersion\Setup\RootDir.


6.3.2  Service Entries
Setup Information	9 of 33

6.3  Setup Registry Architecture

6.3.2  Service Entries

Each instance of a component appears to the system as a unique service. These services must be created using the Service Control Manager (SCM). The SCM creates a registry entry for each service under SYSTEM\CurrentControlSet\Services. This key contains all of the service- specific information.

The top level service key contains information that the SCM uses to control the service. This includes the type of service this key represents, how it should be started, what sort of error handling should be used, the path to the executable image, and so on. All information in this key should be handled by the Service Control Manager. Each service key also contains two subkeys: the Linkage key and the Parameters key.

The Linkage key is used by the NCPA to store binding information. The Parameters key contains information that is relevant to SNA Server Setup, such as the name of the DLL responsible for handling a link service. All information in this key should be handled by the SNA Server Setup. The Parameters key contains another key, ExtraParameters, which is to be used for any IHV-specific information, including component-specific parameters and other information not required by the main SNA setup program.


6.4  Creating Your Setup
Setup Information	10 of 33

6.4  Creating Your Setup

This section describes the recommended sequence of steps to follow when creating a setup script for an IHV link service. As always, it's most helpful to refer to existing .INF files while reading this discussion.


6.4.1  Initialization Section
Setup Information	11 of 33

6.4  Creating Your Setup

6.4.1  Initialization Section

The first section in the setup script is the initialization section. It contains most of the constant text strings and other values that describe the link service and its components. This section should be completed first and double-checked thoroughly. It is important that a clear layout of the SNA options and their additional components is created in this section, since it marks the way for the rest of the script.


6.4.2  Define the Parameters
Setup Information	12 of 33

6.4  Creating Your Setup

6.4.2  Define the Parameters

Define the parameters that each component will have and how they will fit into the registry. It is generally a good idea to name the variables for these parameters after their names in the registry, as this simplifies the code and greatly improves its readability.


6.4.3  Complete the Basic Code
Setup Information	13 of 33

6.4  Creating Your Setup

6.4.3  Complete the Basic Code

Fill in the code sections in the main body of the setup script. Write only the code to initialize the components, and write their parameters to the registry. Since modification of variables involves reading their values from the registry, it may be ignored until this step is complete and the information in the registry is correct.


6.4.4  Design Dialogs
Setup Information	14 of 33

6.4  Creating Your Setup

6.4.4  Design Dialogs

Copy the Setup Resource Library template files into another directory, then change the file names from TEMPLATE.* to WHATEVER.* (use whatever name you want). Using the dialog editor, add your own dialogs that will be used to modify the parameters. Make sure the dialog layouts are clear and intuitive. Consider which dialogs will require on-line help and which won't. Also, remember that controls should be accessible through tabstops.

When you have your dialogs the way you want them, edit the makefile and .RC file to make sure all paths and filenames are correct. Type "nmake" to build the new SRL.


6.4.5  Fill In the Code
Setup Information	15 of 33

6.4  Creating Your Setup

6.4.5  Fill In the Code

Fill in the code sections to modify the variables. This includes writing the dialog-handling code as subroutines in the script and writing the sections that call those subroutines from the main body of the script. This step is probably the most complex, but as usual, look at the existing link service setup scripts to determine what's required.


6.5  Setup Template Description
Setup Information	16 of 33

6.5  Setup Template Description

This section contains a detailed description of the variables and entry points used in the setup scripts. A more detailed definition of the variables can be found in the last section of this chapter.

Note

Variables that are underlined are modifiable by individual IHV setup scripts.


6.5.1  Initialization Section
Setup Information	17 of 33

6.5  Setup Template Description

6.5.1  Initialization Section

This section describes the variables that control the general behavior of all the options manipulated by this script.

Source Media Descriptions

The Source Media Descriptions section contains the labels for the disks (media) used by the setup script for its installations. For more details on this section, you may consult the chapter on .INF files in the Windows [image] version 3.1 GUI Setup Toolkit reference guide. Note that additional parameters on the description lines (TAGFILE, etc.) must be in uppercase, and the spacing must be exactly as used in the existing .INFs.

Option Type

The option type is used by the Network Control Panel Applet (NCPA) to determine what kind of option this setup script can install. The NCPA expects each script to support only one type of option. For our purposes, we need to install multiple types of components in each script. The most general type of component is a Network Service, abbreviated NetService. This is the kind we will use for all of our setup scripts.

Languages Supported

This section should contain a list of human languages supported by the setup script. Each language is represented by a three letter abbreviation, the most common of which is "ENG" for the English language. Throughout the setup script, each section that has a language dependency should be rewritten, once for each language. Examples of this usage abound in the existing .INF files.

Note

The SNA Server setup scripts currently support only the English language. While it is possible for the IHV script to supports its own set of languages, before calling any of the utility functions, you must set the language specifier to English.

Option List

The option list is the most important subsection of the initialization section. It lists all of the options that a particular setup script can handle. When the NCPA queries this script, it will expect to be able to install each of these options.

Note

Although the SNA Server setup scripts allow link services to be inspected and configured via the NCPA, they do not support installation by the NCPA at this time.

Options Text List

This is a list of names or titles for each of the options specified in the option list. When the NCPA or SNA Server Setup calls this script, this is the name that will be presented to the user. Since names are language dependent, there should be a list of names for each language supported.

SNA Option List

The SNA option list is a subset of the option list specified above. It lists all the options that SNA Server Setup will offer the user.

SNA Option Additionals

Whenever SNA Server Setup needs to install one of the options available to the user, it will first try to install these options. SNA Server Setup will read this list of additional components and install each of these in order before it installs the main component. Also, when SNA Server is removed, this list of components is used in the removal of a particular support system. The SNA Server Setup will loop through its list of installed options, call this script for the list of additional components and attempt to remove each of those components as well as the main option.

Installation Steps

There are two steps involved in file copying in the installation of a component. The script can add files to a list of files to be copied, and it can call the function to copy the files in the copy list. These options specify which of these steps will be executed for each component's installation. These options only apply to installation by the SNA Server Setup. The NCPA will always execute both steps of the file copying.

The option to set these two variables allows you to perform all of the file copying for all the components at the end of the installation. This can be accomplished by making the main component the only component that copies files in the copy list. All other additional components will add their files to the copy list until the main component copies all of the files at once.


6.5.2  Dialog Constants
Setup Information	18 of 33

6.5  Setup Template Description

6.5.2  Dialog Constants

This section defines many of the major dialog constants. It contains the variables used for displaying the file copy progress gauge, as well as those for displaying the context sensitive help. This section is also used to define variables to represent radio buttons, check boxes, and dialog entities.

Progress Copy Variables

These variables define the look and behavior of the progress gauge displayed during file copies.

ProCaption	The caption of the gauge window.

ProCancel	The text displayed in the "Cancel" button of the gauge window.

ProCancelMsg	The message that appears in the cancellation window, which pops up when the user presses the cancel button.

ProCancelCap	The caption of the cancellation popup window.

ProText1	The label that precedes the source filename.

ProText2	The label that precedes the destination filename.

Help Context IDs

The HelpContext IDs are used to identify which dialog has had its "Help" button pressed. When the user presses this button, Setup calls WINHELP with the ID assigned to the particular dialog being displayed.


6.5.3  File Constants
Setup Information	19 of 33

6.5  Setup Template Description

6.5.3  File Constants

File Names and Initialization Constants

These variables define some useful constants.

UtilityInf		This .INF file contains all of the SNA Server Setup utility functions.
SubroutineInf		This .INF file contains some of the utility functions used by both SNA Server Setup and by Windows NT Setup.
ThisFile		This variable should hold the name of this .INF file without the extension. It needs to be defined because there's no other way to access this information in the setup script.
ThisInf		This variable contains the full name of the setup script.
ThisSrl		This variable contains the full name of the Setup Resource Library for this script.
ThisHlp		This variable contains the full name of the WINHELP file for this setup script.
HlpMin		This number should be set to one less than the minimum value of the context sensitive help IDs.
HlpMax		This number should be set to one more than the maximum value of the context sensitive help IDs.
ShellCode		This variable holds the error return code from all shell executions and is set by the Setup Engine itself. A value of zero represents success; all other values represent errors.
Product Information

This section contains all the information about this component. There should be a section of this form for each of the options supported by this script.

ProductVersion		The version of this product (component.) This number will be used in creating the registry key for this product under the SOFTWARE key of the registry.
ProductName		The name of this product. This name will be used in conjunction with the version to arrive at the full name of the registry entry for this product.
ProductFullName		This is the actual value used to represent this product in the registry. It's a combination of the product name and version, separated by an underscore.
ProductRegBase		The specific location for this product's registry entry under the SOFTWARE registry key. This variable should not be changed since all the SNA Server components should reside under SOFTWARE\Microsoft in the registry.
ProductType		This variable is an internal representation of the type of component this option belongs to. Currently, this variable can take on the values of "Link" and "Driver." Note: This value is currently unused in the SNA Server scripts; however, it should still be set since its usage will be implemented in the future.
ProductImagePath		This variable contains the filename of the executable image for this product. This may be an executable or a system file. For a link service, this variable must always contain the value SNALINK.EXE.
ProductDepends		This variable holds the dependencies of this product. This value is only used in the creation of the product service key.
ProductParams		This variable holds the entries for the "Parameters" subkey of the product service key. It is recommended that any modifications to the value of this parameter be done in the body of the setup script with the rest of the assignments. This line should not be deleted since it serves to initialize this variable.
ProductExtraParams		This variable holds the entries for the "ExtraParameters" subkey of the product service key. Like the above, it should be modified in the body of the script. This line serves as the initialization for this variable.
ProductExclusive		This variable dictates the behavior of multiple attempts at installing this component. It can hold one of three values: FALSE: This product is not exclusive and may be installed as many times as the user chooses. TRUE: This product is exclusive and may only be installed once. NOTIFY: This product is exclusive, and the user should be informed of this fact. SNA Server Setup pops up a message to inform the user.
ProductDll		The dynamic library that should be linked to by the control APIs for this component. This variable is only necessary for link services and should be given a null value for all other cases.
ProductServicePrefix		This is a prefix that will be used to algorithmically decide the service name for this component. All service names for SNA Server are limited to no more than eight characters. Since SNA Server Setup will attach a single character suffix based on the index, this prefix should be no longer than seven characters.
SNAServiceType		This value contains a more specific description of the type of component this option represents. It should be set to one of the values specified in the "SNAServiceTypes" section of the UtiltyInf file.
NetRulesClass		This is the class to which this product belongs for bindings determination by the NCPA.
FullInfName		This is the full path to this setup script (.INF file) after installation.
ServiceType		This variable is used to declare the type of this component for usage with the NCPA bindings.


6.5.3  General Constants
Setup Information	20 of 33

6.5  Setup Template Description

6.5.3  General Constants

This section defines some general constants that are used in the setup scripts. You may add variables to this section, but you may not modify or delete any of the existing ones.

Flow Control Variables	Description

from	This variable contains the label that the setup script last passed.

to	This variable contains the label that the setup script is headed for.

State Variables	Description

TRUE	Boolean true.

FALSE	Boolean false.

NOTIFY	Used in the ProductExclusive variable defined earlier.

Registry Initialization	Description

NoTitle	This variable is used in the creation of registry keys. It specifies that the key to be created should not be assigned a title. None of the keys created by SNA Server Setup scripts require a title. For more information, please refer to documentation on the Windows NT registry.

KeyNull	This variable represents the null key handle. It is used mostly for comparisons and initializations of other handles.

KeyProduct	This variable holds a handle to the product key in the SOFTWARE registry tree. It is assigned here for initialization purposes.

KeyParameters	This variable holds a handle to the Parameters subkey of the product service key. It is assigned here for initialization purposes only.

Additional Initialization Parameters	Description
ExitState	This variable should hold the state of the script after it exits. Note: This feature is currently unused.
OldVersionExisted	This variable holds a Boolean value that describes whether a previous version of this product exists.


6.5.4  Language Dependent Dialog Constants
Setup Information	21 of 33

6.5  Setup Template Description

6.5.4  Language Dependent Dialog Constants

This section contains dialog variables and constants that are language dependent. Any dialog information that is language dependent should be placed in this section. This section contains a list of the basic dialog button English texts. This list should not be modified, as consistency should be preserved across SNA Server Setup scripts.


6.5.5  Language Dependent File Constants
Setup Information	22 of 33

6.5  Setup Template Description

6.5.5  Language Dependent File Constants

This section contains language dependent variables and constants that relate to file information. The SetupTitle variable should be defined as it is used in some captions. Also, this section should include a subsection for each option and each language containing two variables each:
ProductTitle and ProductDesc. These variables contain the default values for the title and description of this product. The user is allowed to modify the title of the product but not the description.


6.5.6  Date Section
Setup Information	23 of 33

6.5  Setup Template Description

6.5.6  Date Section

This section is used to determine the date of installation. This information is currently unused by SNA Server Setup but may be useful for some purposes.


6.5.7  Input Dialogs Information
Setup Information	24 of 33

6.5  Setup Template Description

6.5.7  Input Dialogs Information

This section should contain all information about the input dialogs. Each dialog to be displayed should have a subsection that contains its variables. There should be a subsection of this kind for each language supported, since dialog text is generally language dependent. For examples, refer to any of the existing setup scripts.


6.5.8  Input Dialogs Scripts
Setup Information	25 of 33

6.5  Setup Template Description

6.5.8  Input Dialogs Scripts

This section should contain all the code for handling the input dialogs. Each script may return as many parameters as it wants to, as long as the first parameter is the overall status and is one of the standard status return values.


6.5.9  Identification Functions
Setup Information	26 of 33

6.5  Setup Template Description

6.5.9  Identification Functions

The functions in this section are used by SNA Server Setup and by the NCPA to gather information about this script and the options it manages.

Identify

This function is called only by the NCPA and returns the most basic information about this script. It lets the NCPA know what type of option this script installs as well as the media it requires. The NCPA expects the option type returned by this function to represent all of the options in this script. Since we have multiple types of options, we will use the most generic type, "NetService."

Return Options

This function returns a list of the options supported by this script and their appropriate text strings. The text is assumed to be language dependent and will be drawn from one of the "OptionsText" sections.

Return SNA Options

This is SNA Server Setup's parallel function to the "Return Options" function. It returns only those options that SNA Server should display to the user. These are specified in the initialization section.

Return SNA Additionals

This function takes as a parameter the option it should query and returns the list of additional components for that option. It also returns a list of the text strings for those additional components.


6.5.10  SNA Invocation Section
Setup Information	27 of 33

6.5  Setup Template Description

6.5.10  SNA Invocation Section

When SNA Server Setup needs to call out to this script, it will do so through this entry point. By setting the variables NTN_InstallMode and NTN_InfOption, SNA Server Setup can control the behavior of this script. This entry point also expects the STF_LANGUAGE variable to be set to a language the script can support.


6.5.11  NCPA Invocation Section
Setup Information	28 of 33

6.5  Setup Template Description

6.5.11  NCPA Invocation Section

When the NCPA needs to call out to this script, it will use this entry point to do so. Like the above entry point, the NCPA will set the appropriate variables before shelling to this entry point. This entry point is also in charge of setting up some other variables that the SNA Server Setup would normally create. Among these variables are SNARootDir and SNAVersion.


6.5.12  Common Code Section
Setup Information	29 of 33

6.5  Setup Template Description

6.5.12  Common Code Section

This section contains most of the actual code that the script runs. It expects to receive the name of an option and an index as parameters. It also checks to see that the language specified in STF_LANGUAGE is supported. It then checks the NTN_InstallMode variable to determine what it should do. Before proceeding to the section of code that will complete the required task, the script sets up default values for all the variables of the particular option being installed.

Main Entry Section

Checks the value of the NTN_InstallMode variable and determines the label of the code that will complete that operation. Also assigns defaults values for the variables.

Set Defaults (set_defaults)

This subsection sets the default values for the options; among them are the service name, title, and description. These three must be set in this section; however, more variables may be added as needed.

Install Component (install_component)

This section checks to see if there are any instances of this component already installed. If there are none, it sets the install index to one and continues. Otherwise, if one instance exists, it checks for the value of the ProductExclusive variable to determine what it should do. In the case where it needs to install another instance of the component, it shells out to the utility file and finds the next available index for it to use.

When it is ready, the script determines the service name for this component using an algorithmic definition (install_nextstep). If the ProductServiceQuery variable is set to TRUE, the user is presented with this value and is allowed to change it. Once all the variables are ready, it proceeds to the parameter modification section.

Configure Component (config_component)

This code determines whether or not the particular component in question is installed. If it isn't installed or the index is invalid, it fails with an error. Otherwise, it reads the parameters for this component from the registry (read_params). This code reads the parameters from the Parameters and ExtraParameters keys in the registry and creates a list of their values. It then loops through the list and assigns the values to the variables using a switch/case construct (assign_value_option). When that is done, there is an extra section (assign_extra_option) where other parameters that don't reside in the standard location may be read or any other code that assigns values to variables may be placed. Once the variables are all assigned, the code proceeds to the parameter modification section.

Modify Parameters (modify_params)

This section contains the code that modifies the variables or calls out other code that modifies them. As soon as this section is entered, control is routed to subsections, one for each option (modify_params_option). These subsections should contain all of the actual modification code. When this section is done, the variables should be ready to write to the registry and the code proceeds to the adjustment section.

Adjust Parameters (adjust_params)

This code takes control from the parameter modification section. If the script is supposed to configure an existing component, the control is routed directly to the code that is in charge of writing the parameters to the registry. Otherwise, control falls to code that creates the appropriate service entries in the registry before it writes out the variables.

Create Registry Entries (create_regvals)

This section is in charge of creating the service and registry entries for this component. It also writes out some of the values that the product entry under the SOFTWARE\Microsoft key needs to contain. This section is also currently in charge of the NCPA bindings information. If the product files have not been copied, this code shells out to the installation section that takes care of file copying (InstallRemove). When all the keys are created, control falls to the section that writes out the variable values to the registry.

Write Out Variables (write_params)

This section first ensures that the appropriate handles are open and then routes control to a subsection that should prepare the appropriate variables for registry output (write_params_option). Each of these sections must prepare the ProductParams and ProductExtraParams variables to be written to the registry. Each of these parameters is a list of registry creation lists. Each registry creation list must contain the name of the entry to be created, the NoTitle variable, the type of entry to create, and the value of the entry. See the existing link service .INF scripts.

The ProductParams variable must contain the name and option entries. Both variables may contain any additional entries that are needed. Also, any other parameter-writing code should be written in these sections. For an example, see the setup script for the NDIS 802.2 link support (SNADLC.INF).

After the subsections are finished, control is passed to the code that actually adds the list of entries to the registry. It also prepares the data return structure and finishes by using the successful escape hatch.

Get Bindings From Component (getbind_component)

This section is responsible for communicating the option bindings back to SNA Server Setup. It queries the NCPA bindings, sets the information in the data return structure, and returns it to the SNA Server Setup. SNA Server Setup then uses this information to determine whether this particular instance may be removed or not. An instance may be removed if it is not needed (bound to) by any other component.

Remove Component (remove_component)

This code is in charge of removing one or all of the instances for a particular product. In the case of a complete removal, it also removes the files and software entries for this product. In the case of a single instance removal, the code passes control to the remove_one_piece subsection, which handles a single removal. Otherwise, code control goes to the remove_all_pieces subsection.

For a full removal, the setup script will loop through all of the instances and call the remove_one_piece subsection for each of those instances. When the loop is complete, the code control is passed to a common point for both removal types (remove_product). The subsection remove_one_piece removes the software entry for the instance and deletes the service from the Service Control Architecture. If it is dealing with a complete removal, it returns control to the loop, otherwise, it falls to the remove_product subsection. This subsection determines whether files should be removed (full removal) and calls the appropriate installation section (InstallRemove). After all is done, it uses the successful escape hatch to return control to SNA Server Setup.

Escape Hatches

These are all the available hatches that may be used throughout the setup script.

Successful (successful)

Sets the status to STATUS_SUCCESSFUL and exits through end.

Warning Message (warning_msg)

This hatch pops up a warning window with the error message stored in the variable Error. This variable should be defined before calling this escape hatch. This warning box has two dialog buttons: "OK" and "cancel." If the user chooses to continue, control is passed to the to label, otherwise, control is returned to the from label. If the warning box fails, the script exits through end.

NonFatal Message (nonfatal_msg)

This hatch pops up a nonfatal warning window with the error message stored in the variable
Error. This variable should be defined before calling this escape hatch. This box has only one dialog button, "OK." After the user presses this button, control is returned to the from label. If the nonfatal warning box fails, the script exits through end.

Fatal Registry Message (fatal_registry)

This is probably the most-used escape hatch, next to the successful hatch. It sets up the Error variable with a template that includes three other variables: ErrMesg, ErrProc, and ErrFunc. The first should be a short message describing the error. The second should be the section or subsection that called the registry function. The third should be the name of the registry function that was called. All three variables should be set before calling this escape hatch. After the error message is prepared, the fatal_msg escape hatch gets control.

Fatal Message (fatal_msg)

This hatch pops up a window with the fatal error message. When the user clicks on the button, this hatch exits through the set_status_failed escape hatch.

Shell Code Error (ShellCodeError)

This hatch is only used when a shell execution fails. If the script receives a ShellCode that is not zero, it calls this hatch. This hatch displays an error message and exits through the set_status_failed hatch.

Failed Exit (set_status_failed)

Sets the status to STATUS_FAILED and exits through end.

End

This hatch makes sure that the handle to the SRL for this file is closed and exits this script. It should not be called directly without ensuring that the Status variable contains the correct return value for the operation.


6.5.13  Installation Control Section
Setup Information	30 of 33

6.5  Setup Template Description

6.5.13  Installation Control Section

This section contains the code that copies and removes files for the scripts.

Install Section

In the case of an installation, this section reads in the file list to be copied and copies it, depending on the values of the appropriate variables (see the initialization section.) The script copies files into the SYSTEM and SYSTEM\HWSETUP subdirectories. However, you may add files to the file list by calling the same function that the script calls.

In the case of a removal, the script will read in the same list of files that it used for the copy and create a list of filenames in the global variable _FileRemoveList. Each of the filenames in this list is specified by its full path. SNA Server Setup then tries to remove all the files on this list. This layer of abstraction is necessary because the SRL file cannot be deleted while a handle to it remains open.

File List Section

This section specifies the file list for each of the options supported by this setup script. Options may or may not have a section for files to be copied into the SYSTEM and SYSTEM\HWSETUP subdirectories. If a section listing files exists, those files will be added to the copy list as needed. The three main files for each script (INF, SRL, and HLP) should be placed under the SYSTEM\HWSETUP subdirectory and invoked by all the SNA options in this script.

In the case where more than one SNA option exists, the script will use version numbers to determine whether or not the files should be recopied. If the version numbers are the same, the files are not recopied.


6.6  Global Variables
Setup Information	31 of 33

6.6  Global Variables

LIBHANDLE	Handle to the Setup Support Library, SETUPDLL.DLL.

SNARootDir	The root directory of the machine's SNA Server tree.

LF	Constant for printing newlines in dialog text.

DriverDir	Path where link service .INF files will be found.

NTN_InstallMode	Controls installation/configuration/removal behavior.

STF_LANGUAGE	Which human language is currently in use.

REG_KEY_READ	Constant for "read-only" registry access.

REG_KEY_READWRITE	Constant for "read-write" registry access.

REG_H_LOCAL	Handle to top of HKEY_LOCAL_MACHINE registry tree.

REG_VT_SZ, etc.	Constants representing data types for registry entries.

NTN_SoftwareBase	Handle to SOFTWARE\Microsoft registry tree.

NTN_InfOption	Which option is currently being installed/removed.

STF_WINDOWSSYSPATH	Path to Windows NT "system" subdirectory.

AddCopy	Boolean indicating whether files should be added to the copy list.

DoCopy	Boolean indicating whether files should be copied at all.

IHVDLGHANDLE	Handle to SRL containing dialogs.

SNAVersion	Current version of the SNA Server.


6.7  Utility Functions
Setup Information	32 of 33

6.7  Utility Functions

6.7.1  Product Functions

The following are some of the useful entry points in the Utility .INF file (UtilityInf; usually SNAUTILS.INF unless it's been renamed).

CreateSNARegEntry

Description

This function creates the necessary entries for an instance in the SOFTWARE\Microsoft registry tree. If the product isn't already in the registry, it will create an entry for the product. It then creates an entry for the particular instance of the product and for the NetRules key under that. This function leaves open handles to all the important subkeys for further usage.

Arguments
Argument 0	Name of the top-level registry node to use. This should be a full registry path. For most scenarios, this will be the value held in the ProductRegBase variable (SOFTWARE\Microsoft).
Argument 1	Name of the product. This is the name of the key that will be created for this product.
Argument 2	Instance index. This is the index of this particular instance of this product.
Return Values
Return 0	Status of the operation: STATUS_SUCCESSFUL: Operation succeeded. STATUS_FAILED: Operation failed.
Return 1	Handle to the top-level registry node.
Return 2	Handle to the product's registry key under the top-level node.
Return 3	Handle to the instance entry under the product key.
Return 4	Handle to the NetRules entry under the instance key.
FindSNARegEntry

Description

This function is written as a parallel to the above function. When called, it will attempt to open all of the necessary registry keys and return open handles to them.

Arguments
Argument 0	Name of the top-level registry node to use.
Argument 1	Name of the product.
Argument 2	Instance index.
Return Values
Return 0	Status of the operation.
Return 1	Handle to the top-level registry node.
Return 2	Handle to the product's registry key under the top-level node.
Return 3	Handle to the instance entry under the product key.
Return 4	Handle to the NetRules entry under the instance key.
FindSNAProductServices

Description

This function enumerates all of the particular instances of a product. It returns lists of information for the instances that may be used in the script. This function may also be used to determine whether or not a product exists in the registry by analyzing the return status.

Arguments
Argument 0	Name of top-level registry node to use.
Argument 1	Name of the product.
Return Values
Return 0	Status of the operation: STATUS_SUCCESSFUL: Operation succeeded. STATUS_NOSUCHPRODUCT: The product does not exist in the registry. STATUS_FAILED: Operation failed.
Return 1	List of indexes for the instances of this product.
Return 2	List of service names for the instances of this product.
Return 3	List of titles for the instances of this product.
Return 4	List of descriptions for the instances of this product.
FindNextAvailableIndex

Description

This function is used to determine the index a new instance should receive. For example, if the current indexes in use are { "01," "02," "04" }, this function would return "03" as its return value.

Arguments
Argument 0	A list of the indexes currently in use. This list may be obtained by using the FindSNAProductServices function.
Return Values
Return 0	Status of the operation: STATUS_SUCCESSFUL: Operation succeeded. STATUS_FAILED: Operation failed.
Return 1	First available index for the list.
GrepUniqueServiceInfo

Description

This function is used to determine the information about a particular instance when only one of the four is available. Since there is no way to determine the position of an element in a list, it is hard to figure out the respective name, title, or description of an instance given only the index. This function takes care of searching the list and returning the rest of the information about the instance.

Arguments
Argument 0	Type of information to search: INDEX: Search the list of indexes. NAME: Search the list of service names. TITLE: Search the list of titles. DESC: Search the list of descriptions.
Argument 1	Keyword to search for in the list.
Argument 2	List of indexes for the instances of this product.
Argument 3	List of service names for the instances of this product.
Argument 4	List of title for the instances of this product.
Argument 5	List of descriptions for the instances of this product.
Return Values
Return 0	Status of the operation:
Return 1	Index for this instances of the product.
Return 2	Service name for this instance of the product.
Return 3	Title for this instance of the product.
Return 4	Description for this instance of the product.
EnterServiceName

Description

This function presents the user with an algorithmically determined service name for a component and allows them to change it before returning the final value. This function takes care of ensuring that the new service name is unique in the Service Control Architecture before accepting it.

Arguments
Argument 0	Title of the product the user should be queried about.
Argument 1	Default service name prefix.
Argument 2	Index for this instance of the product. The algorithm uses this index to determine the default name.
Return Values
Return 0	Status of the operation: STATUS_SUCCESSFUL: Operation succeeded. STATUS_NOSUCHLANGUAGE: The language specified is not supported. STATUS_USERCANCEL: User pressed the "Cancel" button.
Return 1	Service name that the user entered.


6.7.2  Service Entry Functions
Setup Information	33 of 33

6.7  Utility Functions

6.7.2  Service Entry Functions

CreateSNAService

Description

This function creates the necessary entries for an instance in the Services registry tree. This function adds particular values that are necessary for the services as well as all the subkeys under the service key, including Parameters and ExtraParameters.

Arguments
Argument 0	Name of the service that needs to be created.
Argument 1	Type of SNA Service. (SNAServiceType variable.)
Argument 2	Image path of this component. (ImagePath variable.)
Argument 3	Dependency list. (ProductDepends variable.)
Argument 4	Parameter list. (ProductParams variable.)
Argument 5	Extra parameter list. (ProductExtraParams variable.)
Argument 6	Event Log message file.
Argument 7	Event types supported (usually 0x07).
Return Values
Return 0	Status of the operation: STATUS_SUCCESSFUL: Operation succeeded. STATUS_FAILED: Operation failed.
Return 1	Handle to the service key.
Return 2	Handle to the Parameters key under the service key.
Return 3	Handle to the ExtraParameters key under the Parameters key.
FindSNAService

Description

This function is written as a parallel to the above function. It is written to provide an easy way to access the keys for a particular service.

Arguments
Argument 0	Name of the service to look for.
Return Values
Return 0	Status of the operation.
Return 1	Handle to the service key.
Return 2	Handle to the Parameters key under the service key.
Return 3	Handle to the ExtraParameters key under the Parameters key.
DeleteSNAService

Description

This function deletes a particular service using the Service Control Manager. All the keys for the service are deleted as well.

Arguments
Argument 0	Name of the service to be deleted.
Return Values
Return 0	Status of the operation.
SetupMessage

Description

This function displays a dialog box with user-defined text plus OK and Cancel buttons. Useful for debugging.

Arguments
Argument 0	Language to use (just pass STF_LANGUAGE).
Argument 1	Which icon to display in the dialog box: STATUS, WARNING, NONFATAL, etc.
Argument 2	The text to be displayed. May contain linefeeds using the LF symbol.
Return Values
Return 0	Status.
SNAServiceType Values

The decimal value for the SNAServiceType Registry entry for each of the link service types is as follows:

Link service type	SNAServiceType value
802.2	11
SDLC	3
X.25	4
DFT	10
Channel	32
Twinax	31
Note

A link service for Twinax works like a link service for DFT, and therefore does not contain any link-specific data.


Diagnostics
Chapter 7	1 of 8

Diagnostics

This chapter describes the following diagnostics mechanisms available to SNA Server applications:

Error and audit log messages

Internal tracing in the SNALink

DLC tracing

In addition, there is a section describing how the IHV may provide a link level tracing facility similar to the standard SNA Server SNALinks.


7.1  Error and Audit Log Messages
Diagnostics	2 of 8

7.1  Error and Audit Log Messages

7.1.1  Options for Logging

The SNA Server header file TRACE.H provides macros that may be used to write to the Windows NT event log files.

These macros use the SNA Server message file NTEVTS.MC which is linked into the central logging DLL, SNAEVENT.DLL, which contains every log message in the SNA Server system. The IHV has two options when logging an error message:

1.	If the standard SNA Server product contains a log message that describes the error condition, this may be used by the IHV.

2.	If extra messages are required, the generic log messages COM0393 and COM0394 may be used. Each takes two parameters, both of which are text strings: the first is an identifier for the SNALink 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.


7.1.2  SNA Server DMOD Logging Macros
Diagnostics	3 of 8

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 the SNA Server 802.2 DLC SNALink 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
All logs are placed in the Windows NT Event log. The default level of audit logs can be specified when configuring SNA Server, so that all or some of the audit logs can be suppressed and can filter out lower-level messages when viewing log files using the NT Event Viewer 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 "cleanup" 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 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 one parameter.

COM0236W: DM or DISC received

COM0242E: Invalid adapter (%1) configured.

The following call:

COM_LOG12(236)""));

would give the following message in the error log:

DM or DISC received

The following call:

COM_LOG16(242)"%d", adptr));

where adptr = 17, would give the following message in the error log:

Invalid adapter (17) configured.

The complete message log entry contains the following information about the error or event and the service that logged it:

Date/Time
User Name
Computer Name
Message Number (Event 10)
SourceType (Severity)
Message with optional parameters

The source is the name of the link service that generated the event log. For example, SNA SDLC link service.


7.2  Internal Tracing
Diagnostics	4 of 8

7.2  Internal Tracing

SNA Server provides internal tracing macros that 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. 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.

Note

Tracing must be initialized by the IHV DLL before any TRACEnn macros are used. Use the INITIALIZE_TRACING macro, listed in the TRACE.H header file, to initialize tracing. The TRACE.H header file appears in section A.3 of this specification. The best place to issue the INITIALIZE_TRACING call is at the start of the "SNALinkInitialize" routine.


7.2.1  Internal Tracing Macros
Diagnostics	5 of 8

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	6 of 8

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.

Note

The registry entries used to control tracing are inserted by Setup. 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

FlipLength=Length_in_Bytes

The entries should be stored under:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services
\<SNALink name>\Parameters

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 FLIPLENGTH BYTES and then to the second file; when the second file also reaches FLIPLENGTH BYTES, 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 FLIPLENGTH, so that only the most recent FLIPLENGTH of trace information is retained. If only one filename is specified, FLIPLENGTH is disregarded and tracing continues to this file regardless of file size.


7.3  DLC Tracing
Diagnostics	7 of 8

7.3  DLC Tracing

SNA Server provides the facility for tracing message flows at the DLC, both at the local node and at the application's Base. This allows you to track the messages being sent and received by the local node and/or the SNALink.

Note

The registry entries used to control tracing are inserted by Setup. The SNATRACE.EXE program may be used to enable/disable internal tracing dynamically at runtime (assuming binaries have been compiled with internal tracing enabled).

Message tracing at the SNALink is controlled by entries in the Windows NT Registry under:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\...

<SNALink name>\Parameters

Message tracing at the local node is controlled by placing similar entries under:

HKEY_LOCAL_MACHINE\System\CurrentControlSet
\Services\SNAServr\Parameters

The entries required in both cases are as follows:

MessageTraceFile1=file1
MessageTraceFile2=file2
DLCTraceState=on	(or off)


7.4  Connection Tracing
Diagnostics	8 of 8

7.4  Connection Tracing

All SNA Server shipping SNALinks provide connection tracing at their lowest level. This information consists of (for example):

Parameter blocks passed to/received from the CCB2 interface by the 802.2 DLC SNALink.

Frames sent/received on the line by the X.25 and SDLC SNALinks.

Command frames sent to/received from the controller by the DFT SNALink.

It is recommended that IHVs also provide this type of tracing to aid troubleshooting when the SNALink is in operation at remote customer sites.

Because the lowest level of the SNALink may vary greatly, according to both the type of the link being serviced and the functionality provided by driver software being used, it is not feasible for SNA Server to provide a tracing interface that will format raw data passed to/from the adapter.

The Connection Tracing interface provided for IHV use requires the SNALink to provide a preformatted buffer of ASCII text that will be written to a trace file maintained by SNA Server. This allows the IHV SNALink to trace to the same trace file as other SNALinks but leaves SNA Server in control of access to the file.

COM_TRC_IHV

The COM_TRC_IHV macro specifies the buffer to be output to the trace file. It is invoked using

COM_TRC_IHV(&Buffer);

The buffer must be formatted as multiple lines of ASCII text (a maximum of 18 lines), each exactly 60 characters in length. Carriage returns and line feeds should not be used. The end of the buffer should be signaled by an ASCII NULL in the data. The buffer will be output to the file in the standard SNA Server format, as shown in figure 7.1.

Figure 7.1    Format of connection tracing. (Where PP is the process ID, and TT is the thread ID.)

Note

The registry entries used to control tracing are inserted by Setup. The SNATRACE.EXE program may be used to enable/disable internal tracing dynamically at runtime (assuming binaries have been compiled with internal tracing enabled).

IHV connection tracing is enables by including the following entries in the Windows NT Registry:

ConnectionTraceState=on	(or off)
ConnectionTraceFile1=file1
ConnectionTraceFile2=file2

These entries should be stored under:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\...

Services\<SNALink_Name>\Parameters

For further details of connection tracing, please refer to the SNA Server Administrator's Reference Guide.


Compiling and Linking with SNA Server
Chapter 8	1 of 6

Compiling and Linking with SNA Server

This chapter lists and explains the header files and libraries for use with SNA Server SNALink and provides information on compiling and linking.


8.1  SNA Server DLC Header Files
Compiling and Linking with SNA Server	2 of 6

8.1  SNA Server DLC Header Files

The following files are required to build the SNA Server SNALink:

SNA_DLC.H	Main header file containing the definitions of buffer and message formats.

SNA_CNST.H	Function prototypes for the 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).

IHVLINK.LIB	Main library for the SNADIS interface.


8.2  Included Files
Compiling and Linking with SNA Server	3 of 6

8.2  Included Files

To compile the SNALink, the header files SNA_DLC.H, SNA_CNST.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 <sna_dlc.h>
#include <sna_cnst.h>
#include <trace.h>


8.3  Required Exports
Compiling and Linking with SNA Server	4 of 6

8.3  Required Exports

The IHV link support .DLL must export the following entry points:

SNALinkInitialize
SNALinkWorkProc
SNALinkDispatchProc

These will be called by the Base scheduler when the SNALink is invoked.


8.4  Compiler Options
Compiling and Linking with SNA Server	5 of 6

8.4  Compiler Options

When compiling the SNALink .DLL, 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 WIN32_SUPPORT 	The macro NT_SUPPORT is used in the header files sna_dlc.h, sna_cnst.h and trace.h to support variants of the DLC interface for Windows NT.

/Gzs	s:	remove stack check calls

z:	use stdcall conventions only on i386/i486 processors, not MIPS or Alpha

The following compiler flags are required, but any of the valid options for each flag may be used, as appropriate to your application:

/O	Optimization

/W	Warning level


8.5  Linking
Compiling and Linking with SNA Server	6 of 6

8.5  Linking

The following library must be linked with the application:

SNALINK.LIB	BASE, DMOD imports, and diagnostics routines

The DMOD and the BASE are implemented as Dynamic Link Libraries (DLLs).

Note that the SNA Server library only contains the external references for the corresponding DLLs, which are part of the main SNA Server product.


Appendix
Appendix A	1 of 9

Appendix

A.1  Synchronous Dumb Card Interface

This appendix describes the interface to the synchronous dumb card device driver used by the SNA Server supplied SDLC and X25 SNALinks. The interface provides a simple but flexible mechanism for the transfer of frames of data through a "dumb" synchronous communications card (such as the IBM MPCA card).

This interface is intended primarily for IHVs who wish to provide drivers for their own dumb cards that will be directly compatible with the SNA Server provided SDLC and X.25 SNALinks. It may also be used by IHVs who intend writing their own SNALinks but who wish to ensure their drivers conform to the standard SNA Server model.


A.2  The Driver Interface
Appendix	2 of 9

A.2  The Driver Interface

Application software running on Windows NT normally does not interact directly with device drivers. Usually, the operating system itself controls the interface to underlying device drivers on behalf of the application. For example, Disk I/O consists of sequences of driver requests generated by a file system, as a result of an application making file system requests.

By contrast, in the SNA Server device driver model, synchronous dumb cards are controlled directly by the SNALink using "IoCtl" commands. This mechanism allows the SNALink to pass "raw" control packets to the driver without any intervention from the operating system.

This is achieved by issuing an Open request with a "filename" that identifies the device driver. The operating system detects the fact that this "file" is in fact a driver and passes an OPEN I/O request packet to the driver. The user application is returned a handle that may be used to reference the driver.

The IBMSYNC driver creates various device names. During setup, the configuration for adapters in the computer is saved in the Registry; when the driver starts up, it reads in this data and creates the device names for all the adapters that are found.

The following table lists the device names that the IBMSYNC driver may create:

Device name created by the IBMSYNC driver		Description
\Device\IBMSDLC		Standard IBM SDLC adapter.
\Device\MPCA_1		IBM MPCA 1 adapter. This adapter has had a switch set on it to enforce MCPA 1 operation. This adapter is the primary MPCA adapter in the computer and supports DMA interrupt mode.
\Device\MPCA_2		IBM MPCA 2 adapter. This adapter has had a switch set on it to enforce MCPA 2 operation. This adapter is the secondary MPCA adapter in the computer and supports only interrupt mode.
\Device\SYNC_x		Generic adapter (for example, Microgate). The letter x will be 1 (for the primary adapter) or 2 (for the secondary adapter).
\Device\MPAA_Sx		IBM MPAA adapter, where x represents the number of the MCA slot where the adapter is installed in the computer. This number will be a value from 1 through 8.
\Device\SYNC_Sx		Generic MPAA adapter (for example, the Microgate MPAA adapter). The letter x represents the number of the MCA slot where the adapter is installed in the computer. This number will be a value from 1 through 8.
Subsequent IoCtl calls (using DeviceIOControl under Windows NT) made by the SNALink using the driver handle cause the operating system to pass an IoCtl I/O request packet to the driver. The driver therefore sees IoCtl requests from the SNALink as a series of I/O request packets passed to it by the operating system.

The SNA Server dumb card interface uses the following operating system calls:

OpenFile

DeviceIOControl

CloseFile

DeviceIOControl allows free-format information to be passed to the driver. The dumb card interface uses its own format of information to pass all requests to the driver (with the exception of Open and Close requests, which are handled differently by the operating system).


A.2.1  Architecture Overview
Appendix	3 of 9

A.2  The Driver Interface

A.2.1  Architecture Overview

The Interface Record

Status information is transferred between the driver and the SNALink using an area of shared memory known as the interface record.

This memory must be allocated by the SNALink before any IOCtl calls are made to the driver. Its address is passed to the driver using an IoCtl call of type SET_INTERFACE_RECORD.

The interface record is continuously updated by the driver. Once the SNALink has a pointer to the record, it may examine the current status of the driver without issuing any explicit calls to the driver software.

Event Signaling

The device driver will notify the SNALink whenever an event occurs (such as a frame being received from the line) by setting an event.

The SNALink provides the driver with a handle to this event (or semaphore) at start of day by issuing an IoCtl call of type SET_EVENT_HANDLE.

Link Characteristics

Before the driver can transfer any data, it needs information about the link. This includes:

The frame size

The station address to listen on (if required)

Details of hardware selectable options, such as SDLC/HDLC, Internal/External clocking, and so on.

For more details of these options, refer to the description of the SET_LINK_CHARACTERISTICS IoCtl call.


A.3  I/O Request Packets
Appendix	4 of 9

A.3  I/O Request Packets

All I/O requests are passed to the driver by Windows NT using the standard IRP structure. For more details of this, refer to the Windows NT Device Driver Kit.

I/O request packets are defined in terms of "C" structures. The relevant fields are accessed as follows:

IRP.CurrentStackLocation->MajorFunction		Defines the IRP as an IOCTL
IRP.IoStatus		Status codes upon completion of request
IRP.CurrentStackLocation->IoControlCode		The IOCTL function code
IoControlCode identifies the function to be performed and IoStatus is the mechanism for returning result codes to the SNALink. The structure IOStatus is defined as follows:

IoStatus.Status		A standard Windows NT result code (e.g. STATUS_INVALID_PARAMETER) as defined in the Windows NT header file ntstatus.h
IoStatus.Information		For successful read-frame IoCtls, the length of the received buffer (may be zero if no data available)Additional error information, as defined in the header file SECLINK.H
The bit-numbering convention used in the following descriptions is as follows: The bits in a byte are numbered 0 through 7, where bit 0 is the least significant and bit 7 is the most significant.


A.3.1  INITIALIZATION
Appendix	5 of 9

A.3  I/O Request Packets

A.3.1  INITIALIZATION

Device drivers under Windows NT should perform all initialization required at start of day when they are loaded by Windows NT. Configuration information for device drivers is stored in the Configuration Registry under Windows NT. For more details, refer to the documentation supplied with the Windows NT Device Driver Kit.

The SNALinks for dumb cards are implemented by the following files:

SDLC SNALink

SNAroot\SYSTEM\IBMSDLC.DLL

X.25 SNALink

SNAroot\SYSTEM\IBMX25.DLL

To bind to one of these, an installation script should mention the appropriate DLL in the IHVDLL registry entry that the script creates for the link service.


A.3.2  OPEN
Appendix	6 of 9

A.3  I/O Request Packets

A.3.2  OPEN

(No parameters)

This call grants access to the driver from a particular process. The driver ensures that only one OPEN is accepted by the link at any one time. When OPEN is processed, the driver attempts to reserve access to hardware resources such as interrupt vectors; the OPEN is rejected if this fails.

After a successful OPEN request, the driver expects to receive the following IoCtl commands (see detailed descriptions of these later in this chapter):

SET_EVENT_HANDLE

SET_INTERFACE_RECORD

SET_LINK_CHARACTERISTICS

Of these, the first two may be performed in any order, but both should be issued before calling SET_LINK_CHARACTERISTICS.

Once these three calls have been successfully performed by the SNALink, the driver is ready for information transfer.


A.3.3  CLOSE
Appendix	7 of 9

A.3  I/O Request Packets

A.3.3  CLOSE

(No Parameters)

This performs the logical converse of OPEN. Resources are released back to the operating system when a CLOSE is performed.


A.3.4  IOCTL Commands
Appendix	8 of 9

A.3  I/O Request Packets

A.3.4  IOCTL Commands

The parameters to the IOCtl request packet are stored in the following fields in the associated I/O request packet (IRP).

IRP.CurrentStackLocation->IOControlCode		Function Code
IRP.SystemBuffer		Address of ParameterBuffer (if used)
IRP.CurrentStackLocation->InputBufferLength		Length of Parameter buffer
IRP.UserBuffer		Address of Data Buffer
IRP.CurrentStackLocation->OutputBufferLength		Length of Data Buffer
Note that under Windows NT, the operating system reserves the low nibble of IOCtl function codes to determine the method used to map the various buffers passed on the DeviceIoControl function call into the drivers address space. The various options available to device drivers writers are:

Low nibble	IOCtl definition
0	METHOD_BUFFERED
1	METHOD_IN_DIRECT
2	METHOD_OUT_DIRECT
3	METHOD_NEITHER
For further details of the memory mapping performed by these various options, refer to the Windows NT DDK documentation.

For a driver function code of ZZ, using memory mapping code M, the IOCtl code passed on the DeviceIoControl function call will therefore be 0xZZM.

The Function Codes are set out as shown below. Note that all other Function codes will be returned with the error "ERROR_INVALID_DEVICE_REQUEST" in the field IoStatus.Status. The Windows NT I/O System validates the address and length of the areas passed as parameter and data packets. If the address validation fails, an exception will be raised.

All requests must return immediately. In general, they are simple, immediate operations anyway, but in the case of Transmit Frame and Receive Frame, the driver must not suspend the calling SNALink thread while waiting for I/O to complete — a relevant return code should be sent instead, allowing the SNALink to retry.

The complete list of functions is:

Function		Function Code	Windows NT IOCtl Code
Set Event/Semaphore Handle		0x41	0x410
Set Link Characteristics		0x42	0x420
Set V24 Output Status		0x43	0x430
Transmit Frame		0x44	0x441
Abort Transmitter		0x45	0x450
Abort Receiver		0x46	0x460
Off-Board Load		0x47	0x470
Set/Get Interface Record		0x61	0x613
Get V24 Status		0x62	0x622
Receive Frame		0x63	0x632
Function 0x41: Set Event/Semaphore Handle

Purpose:

This supplies the driver with the handle of an event that can be used for signaling the SNALlink software.

Parameter taken from IoCtl Call:

IRP.UserEvent		Event Handle
where:

The handle must refer to an Event/Semaphore owned by the SNALink process. The driver will set the event to indicate the completion of a transmission or the availability of received data or status. Although not required by the driver, the event passed here by the SNALink will normally be the global Base event.

Notes:

This function should be called once only, immediately after the OPEN has been issued. The event will be set when:

Frames are transmitted from the driver buffers.

Frames are received into the driver buffers.

Status information is updated in the Interface Record (see function 61H).

Returns:

If the supplied parameter is NULL, the function will return a status of STATUS_INVALID_PARAMETER, with additional information of INFO_SET_EVENT_NO_EVENT. For any other illegal parameter, an exception will be raised.

Function 0x42: Set Link Characteristics

Purpose:

This request sets the link protocol parameters required by the driver.

Parameter Packet Format:

WORD	Frame Size
DWORD	Data rate
BYTE	Station address 1
BYTE	Station address 2
BYTE	Link Options
BYTE	Reserved
where:

Frame Size indicates to the driver the minimum amount of contiguous receiver buffering that must be available for any individual frame.

Data Rate is the line speed in bits per second. If Link Options bit 3 is not set, this field is ignored.

Link Options is a bit map. The default is all values set to 0. The bits are used as follows:

Bit 7 set to	1 = Four Wire (constant RTS/CTS) 0 = Two Wire (switched RTS/CTS)
Bit 6 set to	1 = NRZI encoding 0 = NRZ encoding
Bit 5 set to	1 = HDLC level 1 conventions 0 = SDLC level 1 conventions
Bit 4 set to	1 = Full duplex (simultaneous 2-way) data 0 = Half duplex (alternating 1-way) data
Bit 3 set to	1 = Generate internal clocking 0 = Take external clocking
Bit 2 set to	1 = Use DMA if available 0 = Don't use DMA on this link
Bit 1 set to	1 = Reset all statistics to 0 0 = Leave accumulated statistics as is
Bit 0 reserved.
Note

Not all of the above options are supported by the standard SNA Server synchronous card drivers.

Station Address 1 and 2

These bytes should be set to the station addresses the user wishes to receive on if "selective" reception is to be used (typically for multi-dropped secondaries). Only frames of data commencing with either of these values will be passed up to the user — others are ignored or discarded.

If the SNALink wishes to listen on only one station address, station address 2 should be set to 0.

A value of 0 in both fields indicates that all error-free received frames are to be passed to the SNALink, regardless of the contents of their first address byte.

Notes:

The driver should always start the receiver at the end of processing this request. If either the transmitter or receiver are active when this command is issued, the driver aborts the current frame before resetting the link characteristics. Upon the setting of the characteristics, the previous operation will be restarted.

Returns:

IoStatus.Status		IoStatus.Information		Description
STATUS_INVALID _PARAMETER		INFO_LINKCHARBUF_WRONG_SIZE
STATUS_INVALID _PARAMETER		INFO_FRAME_BUF_TOO_SMALL		Buffer must be at least 268 bytes
STATUS_INVALID _PARAMETER		INFO_FRAME_BUF_TOO_BIG		Buffer maximum size is 2048 bytes
STATUS_INVALID _PARAMETER		INFO_NO_CLOCKS		No internal clocking available
STATUS_DATA _ERROR		INFO_HARDWARE_8273CMD _TIMEOUT
STATUS_SUCCESS		INFO_NO_DMA_FDX		DMA requested, but can't be used
Function 0x43: Set V.24 Output Status

Purpose:

This call allows the SNALink software to alter the modem output status on the adapter V24 interface. There is no parameter or data packet on this request. The relevant V.24 settings are put into the driver Interface Record (see Function 61H) by the SNALink prior to calling the driver.

Error returns:

IoStatus.Status		IoStatus.Information
STATUS_DATA_ERROR		INFO_HARDWARE_8273CMD_TIMEOUT
Function 0x44: Transmit Frame

Purpose:

The SNALink calls this function to transfer a frame of data to the driver.

Parameters:

IRP.CurrentStackLocation.OutputBufferLength		Frame Length
IRP.UserBuffer		Frame data
where:

Frame Length is the size of the frame pointed to by the data buffer pointer. The frame includes the control, address and information field (if present), but no allowance should be made for flags or CRC bytes.

where:

Frame Data is the contents of the frame, Frame Length bytes long, being transmitted.

Notes:

In two-wire configurations, the driver must raise RTS and wait for CTS from the modem before initiating a transmission. The driver should then drop RTS when all frames have been transmitted. The driver assumes that the transmission is complete when both of the following are true:

The transmit buffer becomes empty (if the link is configured as half duplex)

The last frame transmitted had the Poll/Final bit set in the second byte.

Returns:

IoStatus.Status		IoStatus.Information
STATUS_BUFFER_TOO_SMALL		INFO_TX_BUFFER_FULL
STATUS_INVALID_PARAMETER		INFO_TX_FRAME_TOO_BIG
Refer also to the description of the interface record — the driver updates a field within the interface record reflecting the amount of buffer space available.

Function 0x45: Abort Transmitter

Purpose:

The SNALink calls this function to clear down the driver's transmitter.

Notes:

This request causes the driver to abort the current frame transmission and to flush its internal buffers of any further data pending transmission. In two-wire configurations, the driver should also drop RTS.

Function 0x46: Abort Receiver

Purpose:

The SNALink calls this function to clear down the driver's receiver.

Notes:

This request causes the driver to stop the receiver and to flush its internal buffers of any received data. It should be used to clear down the receiver, for instance, before altering the Link Characteristics.

Function 0x47: Off-Board Load

Purpose:

The SNALink calls this function to allow drivers supporting intelligent link protocol cards to load software for the off-board processor.

Parameter Packet Format:

The parameter and data packets for this function are undefined.

Notes:

This request may not be supported by drivers for "dumb" cards, in which case the driver should return "ERROR_INVALID_FUNCTION."

Function 0x61: Get/Set Interface Record

Purpose:

Passes the address of a buffer for the driver's shared data area used for transferring data between it and the SNALink. The buffer must be allocated by the SNALink prior to making this call.

Parameters:

IRP.SystemBuffer	Interface Record Address (IN)
where:

Interface Record Address is a 32-bit pointer to the driver's interface record area (described below).

The interface record format is as follows:

Description	Type
Received Frames	int
Transmit Buffer Space	int
Status Events	int
Input V.24 Status	UCHAR
Output V.24 Status	UCHAR
Statistics Counters	int[11]
Received Frames is the number of frames currently queued in the driver receive buffers.

Transmit Buffer Space is used to signal to the SNALink:

Whether more frames can be provided to the driver.

Whether the driver still has frames waiting to be sent.

The transmit Buffer Space field indicates the maximum frame size that the driver can currently accept. This is updated after each successful Transmit Frame IoCtl, and should be checked by the SNALink before sending further frames to the driver.

Status Events is a count of the total number of increments made to the Statistics Counters.

Input V.24 Status is a bit-map of the current logical state of the input interface lines, a value of 1 meaning ON and a value of 0 meaning OFF. The pins are mapped as follows:

Bit No.		V.24 Circuit Name		Circuit No.	RS-232C Pin
7 - 5		Reserved		142	25
4		Test Indicator		125	22
3		Calling Indicator		125	22
2		RLSD (commonly DCD)		109	8
1		Data Set Ready (DSR)		107	6
0		Ready For Sending (i.e. CTS)		106	5
Output V.24 Status is a bit-map of the current logical state of the output interface lines, a value of 1 meaning ON and a value of 0 meaning OFF. The pins are mapped as follows:

Bit No.		V.24 Circuit Name		Circuit No.	RS-232C Pin
7 - 5		Reserved
4		Maintenance Test		140	18
3		Select Standby		116	11
2		Data Signal Rate Selector		111	23
1		Data Terminal Ready		108/2	22
0		Request to Send		105	4
Note that the driver will raise and lower RTS as necessary while transmitting, reflecting the state of RTS in the output V.24 status field. The application should not, therefore, try to manipulate RTS itself.

The Statistics Counters are running counts of various kinds of link status information. The events they relate to are:

Counter 1	frames received with incorrect CRC
Counter 2	frames larger than the maximum size received
Counter 3	frames smaller than 32 bits received
Counter 4	frames received that are not a multiple of 8 bits
Counter 5	Aborted frames received
Counter 6	Transmitter underruns
Counter 7	Receiver Overruns
Counter 8	RLSD drops in mid-reception
Counter 9	CTS drops in mid-transmission
Counter 10	DSR drops
Counter 11	Hardware failures (adapter or modem).
Notes:

The interface record provides a fast mechanism to use to decide whether a frame can be transmitted, whether there are any frames to be received, and so on.

The driver ONLY may update Received Frames, Transmit Buffer Space, and Input V.24 Status. Output V.24 Status may be altered as necessary, however, and the Status Events and Statistics Counters fields may be decremented or cleared to 0. Such update operations should be "atomic", however, to avoid losing statistics data, since the driver may be incrementing the various counters during interrupt service routines.

The interface record address is generated by the driver at OPEN time and is valid for the duration of the DLC software process's connection to the driver. This request should, therefore, be issued once only, immediately after the OPEN.

Function 0x62: Get V.24 Status

Purpose:

The SNALink calls this function to read the current state of the modem interface lines. No parameter or data packet is passed. This request causes the driver to update the Input V.24 Status field in the driver interface record.

Function 0x63: Receive Frame

Purpose:

The SNALink calls this function to read a data frame from the driver's buffers.

Parameters:

IRP.CurrentStackLocation.OutputBufferLength		Frame Length
IRP.UserBuffer		Frame Data ()
Frame Length is the size of the frame transferred into the data buffer by the driver. The frame includes the control, address and information field (if present), but no flags or CRC bytes. When the request is issued, Frame Length is set to the maximum length of the buffer addressed by the Data Packet pointer.

Frame Data is the contents of the frame, Frame Length bytes long, that has been received.

Notes:

The driver will transfer the next available received frame to the supplied buffer. Note that if the buffer is not large enough, a "buffer overflow" error is returned. This allows the application to decide if "oversize" frames are an error. If not, then a second attempt to read should be made, using a buffer at least Frame Length bytes long. A length of 0 is returned if there are no frames ready to be received.

Returns:

IoStatus.Status		IoStatus.Information
STATUS_BUFFER_TOO_SMALL		n/a


A.4  Equates and Structure Layouts
Appendix	9 of 9

A.4  Equates and Structure Layouts

Many "standard" operating system device driver error codes are used ("invalid function," for instance), together with a new set of device-driver specific errors. Return codes below 80h reflect serious failures.

/* Copyright Data Connection Ltd. 1989 */_

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

/* Link Device Driver interface constants and structures.                 */

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

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

/* WIN32  16/04/92  SW   Added more helpful names from WIN32 hdr file        */

/* IHV    03/06/92  MF2  Add semfisui.h                                      */

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

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

/* This include file is used in 5 subsystems                                 */

/*                                                                           */

/* - the NT   driver                         LINK_NTDRIVER                   */

/* - the X25  link service for NT            LINK_NTX25                      */

/* - the SDLC link service for NT            LINK_NTSDLC                     */

/* - the X25  link service for OS/2          LINK_OS2X25                     */

/* - the SDLC link service for OS/2          LINK_OS2SDLC                    */

/*                                                                           */

/* (The OS/2 driver doesn't count because it is in assembler).            */

/*                                                                           */

/* These are distinguished based on #defines as set in the following         */

/*                                                                           */

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

#ifdef        IMADRIVER

#define     LINK_NTDRIVER

#else

#ifdef      SDLC

  #ifdef    WIN32

    #define LINK_NTSDLC

  #else

    #define LINK_OS2SDLC

  #endif

#else

  #ifdef    WIN32

    #define LINK_NTX25

  #else

    #define LINK_OS2X25

  #endif

#endif

#endif

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

/* Device function codes for DosDevIOCtl to link device driver               */

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

#ifdef WIN32                /* WIN32 constants defined in semfisui.h         */

#define IoctlCodeSetEvent               0x410

#define IoctlCodeSetLinkChar            0x420

#define IoctlCodeSetV24                 0x430

#define IoctlCodeTxFrame                0x440

#define IoctlCodeAbortTransmit          0x450

#define IoctlCodeAbortReceiver          0x460

#define IoctlCodeSetInterfaceRecord     0x610 /*IRMdl?*/

#define IoctlCodeGetV24                 0x623

#define IoctlCodeRxFrame                0x633

#define IoctlCodeReadInterfaceRecord    0x643   /*IRMdl?*/

#else

//obsolete names from previous version

//#define CELDDSSH 0x41       /* Set Semaphore Handle                        */

//#define CELDDSLC 0x42       /* Set Link Characteristics                    */

//#define CELDDSVS 0x43       /* Set V24 Output status                       */

//#define CELDDTXF 0x44       /* Transmit a frame of data                    */

//#define CELDDATX 0x45       /* Abort Transmitter                           */

//#define CELDDARX 0x46       /* Abort Receiver                              */

//#define CELDDGIR 0x61       /* Get Interface Record Address                */

//#define CELDDGVS 0x62       /* Get V24 Input Status                        */

//#define CELDDRXF 0x63       /* Receive a frame of data                     */

//#define CELDDCAT 0x82       /* Device function category code               */

//

// new names

#define IoctlCodeSetEvent               0x41

#define IoctlCodeSetLinkChar            0x42

#define IoctlCodeSetV24                 0x43

#define IoctlCodeTxFrame                0x44

#define IoctlCodeAbortTransmit          0x45

#define IoctlCodeAbortReceiver          0x46

#define IoctlCodeSetInterfaceRecord     0x61

#define IoctlCodeGetV24                 0x62

#define IoctlCodeRxFrame                0x63

#endif

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

/* Constants for the driver-specific IOCtl return codes.                  */

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

#define CEDNODMA 0xff80     /* Warning (NO DMA!) from set link chrctrstcs    */

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

/* Equates for the link options byte 1.                                   */

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

#define CEL4WIRE 0x80

#define CELNRZI  0x40

#define CELPDPLX 0x20

#define CELSDPLX 0x10

#define CELCLOCK 0x08

#define CELDSRS  0x04

#define CELSTNBY 0x02

#define CELDMA   0x01

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

/* Equates for the driver set link characteristics byte 1.                */

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

#define CED4WIRE 0x80

#define CEDNRZI  0x40

#define CEDHDLC  0x20

#define CEDFDPLX 0x10

#define CEDCLOCK 0x08

#define CEDDMA   0x04

#define CEDRSTAT 0x02

#define CEDCSTAT 0x01

/* Nicer names for NT-style code */

#define LinkOption_4Wire           CED4WIRE

#define LinkOption_NRZI            CEDNRZI

#define LinkOption_HDLC            CEDHDLC

#define LinkOption_FullDuplex      CEDFDPLX

#define LinkOption_InternalClock   CEDCLOCK

#define LinkOption_DMA             CEDDMA

#define LinkOption_ResetStatistics CEDRSTAT

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

/* Equates for the output V24 interface flags.                             */

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

#define CED24RTS 0x01

#define CED24DTR 0x02

#define CED24DRS 0x04

#define CED24SLS 0x08

#define CED24TST 0x10

/* Nicer names for NT-style code */

#define IR_OV24RTS  CED24RTS

#define IR_OV24DTR  CED24DTR

#define IR_OV24DSRS CED24DRS

#define IR_OV24SlSt CED24SLS

#define IR_OV24Test CED24TST

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

/* Equates for the input V24 interface flags.                             */

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

#define CED24CTS 0x01

#define CED24DSR 0x02

#define CED24DCD 0x04

#define CED24RI  0x08

/* Nicer names for NT-style code */

#define IR_IV24CTS  CED24CTS

#define IR_IV24DSR  CED24DSR

#define IR_IV24DCD  CED24DCD

#define IR_IV24RI   CED24RI

#define IR_IV24Test 0x10

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

/* Structure for the device driver interface record.                      */

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

#define CEDSTCRC  0         /* Frames received with incorrect CRC            */

#define CEDSTOFL  1         /* Frames received longer than the maximum       */

#define CEDSTUFL  2         /* Frames received less than 4 octets long       */

#define CEDSTSPR  3         /* Frames received ending on a non-octet bndry   */

#define CEDSTABT  4         /* Aborted frames received                       */

#define CEDSTTXU  5         /* Transmitter interrupt underruns               */

#define CEDSTRXO  6         /* Receiver    interrupt overruns                */

#define CEDSTDCD  7         /* DCD (RLSD) lost during frame reception        */

#define CEDSTCTS  8         /* CTS lost while transmitting                   */

#define CEDSTDSR  9         /* DSR drops                                     */

#define CEDSTHDW 10         /* Hardware failures - adapter errors            */

#define CEDSTMAX 11

#define SA_CRC_Error       CEDSTCRC

#define SA_RxFrameTooBig   CEDSTOFL

#define SA_RxFrameTooShort CEDSTUFL

#define SA_Spare           CEDSTSPR

#define SA_RxAbort         CEDSTABT

#define SA_TxUnderrun      CEDSTTXU

#define SA_RxOverrun       CEDSTRXO

#define SA_DCDDrop         CEDSTDCD

#define SA_CTSDrop         CEDSTCTS

#define SA_DSRDrop         CEDSTDSR

#define SA_HardwareError   CEDSTHDW  /* e.g. CmdBufferFull not set  */

#define SA_Max_Stat        CEDSTMAX

#ifdef WIN32

typedef struct         _INTERFACE_RECORD

{

int                   RxFrameCount;   /* incremented after each frame rx'd */

int                   TxMaxFrSizeNow; /* max available frame size av. now  */

                                      /* (changes after each Tx DevIoctl   */

                                      /* to DD or after Tx completed)      */

int                   StatusCount;    /* How many status events have been  */

                                      /* triggered.                     */

UCHAR                 V24In;          /* Last 'getv24i/f' value got        */

UCHAR                 V24Out;         /* Last 'setv24 outputs' value set   */

/*       The values for the indexes into the link statistics array of the */

/*       various types of statistic. */

int                   StatusArray[SA_Max_Stat];

}                       IR,

                   * PIR;

#else

typedef struct teifrec {

      USHORT    RxFrameCount;

      USHORT    TxMaxFrSizeNow;

      USHORT    StatusCount;

      UCHAR     V24In;

      UCHAR     V24Out;

      USHORT    StatusArray[CEDSTMAX];

      }TEIFREC;

typedef TEIFREC far * TEIFRPTR;

#endif

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

/* Structure for the set link characteristics parameter block.            */

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

#ifdef WIN32

typedef struct  _SLPARMS

{

      int     SLFrameSize;            /* max frame size on link - must be  */

                                      /* in range 270 to ?2K-ish           */

      LONG    SLDataRate;             /* not used by us - external clocks  */

      UCHAR   SLOurAddress1;          /* ) e.g C1/FF or 00/00 or 01/03     */

      UCHAR   SLOurAddress2;          /* )                                 */

      UCHAR   SLLinkOptionsByte;      /* see documentation & LinkOption_*  */

      UCHAR   SLSpare1;

}

              SLPARMS;

#else

typedef struct teslcrec {

      USHORT  SLFrameSize;

      ULONG   SLDataRate;

      UCHAR   SLOurAddress1;

      UCHAR   SLOurAddress2;

      UCHAR   SLLinkOptionsByte;

      UCHAR   SLSpare1;

      }TESLCREC;

#endif

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

/* DEVICEIOCTL macros                                                        */

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

#ifdef WIN32

/* NT_SUCCESS ripped of from DDK's ntdef.h, which we do not want to include  */

/* for now temporarily (12/5/92)                                             */

#define NT_SUCCESS(Status) ((NTSTATUS)(Status) >= 0)

#define SETEVENTHANDLE(H) NtDeviceIoControlFile(                   \

              seldrvrh,                   \

              H,                          \

              ( PVOID ) NULL,             \

              ( PVOID ) NULL,             \

              &IoStatus,                  \

              IoctlCodeSetEvent,          \

              ( PVOID ) NULL,             \

              0L,                         \

              ( PVOID ) NULL,             \

              0L                          \

             )

#define SETINTERFACERECORD(R) NtDeviceIoControlFile(                   \

              seldrvrh,                   \

              ( PVOID ) NULL,             \

              ( PVOID ) NULL,             \

              ( PVOID ) NULL,             \

              &IoStatus,                  \

              IoctlCodeSetInterfaceRecord,                             \

                                          \

              &R,                         \

              sizeof(R),                  \

              ( PVOID ) NULL,             \

              0L                          \

             )

#define SETV24STATUS NtDeviceIoControlFile(                            \

              seldrvrh,                   \

              ( PVOID ) NULL,             \

              ( PVOID ) NULL,             \

              ( PVOID ) NULL,             \

              &IoStatus,                  \

              IoctlCodeSetV24,            \

              NULL,             \

              0L,                         \

              &pInterfaceRecord->V24Out,  \

              1L                          \

             )

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

/* The above change is temporary!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!*/

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

#define GETV24STATUS NtDeviceIoControlFile( \

                seldrvrh,                   \

                ( PVOID ) NULL,             \

                ( PVOID ) NULL,             \

                ( PVOID ) NULL,             \

                &IoStatus,                  \

                IoctlCodeGetV24,            \

                ( PVOID ) NULL,             \

                0L,                         \

                ( PVOID ) NULL,             \

                0L                          \

               )

#define SETLINKCHARACTERISTICS(A) NtDeviceIoControlFile(               \

              seldrvrh,                   \

              NULL,                       \

              ( PVOID ) NULL,             \

              ( PVOID ) NULL,             \

              &IoStatus,                  \

              IoctlCodeSetLinkChar,       \

              &A,                         \

              sizeof(A),                  \

              ( PVOID ) NULL,             \

              0L                          \

             )

#define TRANSMITFRAME(A,B) NtDeviceIoControlFile(                      \

               seldrvrh,                 \

               NULL,                     \

               ( PVOID ) NULL,           \

               ( PVOID ) NULL,           \

               &IoStatus,                \

               IoctlCodeTxFrame,         \

               ( PVOID ) NULL,           \

               0L,                       \

               A,                        \

               B                         \

              )

#define RECEIVEFRAME(A,B) NtDeviceIoControlFile(                       \

               seldrvrh,             \

               NULL,                 \

               ( PVOID ) NULL,       \

               ( PVOID ) NULL,       \

               &IoStatus,            \

               IoctlCodeRxFrame,     \

               ( PVOID ) NULL,       \

               0L,                   \

               A,                    \

               B                     \

              )

#define READINTERFACERECORD NtDeviceIoControlFile(                       \

               seldrvrh,             \

               NULL,                 \

               ( PVOID ) NULL,       \

               ( PVOID ) NULL,       \

               &IoStatus,            \

               IoctlCodeReadInterfaceRecord,     \

               ( PVOID ) NULL,       \

               0L,                   \

               &InterfaceRecord,     \

               sizeof(InterfaceRecord)      \

              )

#else

#define NT_SUCCESS(R) ((R) == 0)

#define SETEVENTHANDLE(H)  DosDevIOCtl(NULL,           \

                 &H,                                 \

                 IoctlCodeSetEvent,                  \

                 CELDDCAT,                           \

                 seldrvrh)

#define GETINTERFACERECORD(P) DosDevIOCtl(NULL,        \

                 &P,                                 \

                 IoctlCodeGetInterfaceRecord,        \

                 CELDDCAT,                           \

                 seldrvrh)

#define SETV24STATUS DosDevIOCtl(NULL,                 \

                 NULL,                               \

                 IoctlCodeSetV24,                    \

                 CELDDCAT,                           \

                 seldrvrh)

#define GETV24STATUS DosDevIOCtl(NULL,                 \

                   NULL,                             \

                   IoctlCodeGetV24,                  \

                   CELDDCAT,                         \

                   seldrvrh)

#define SETLINKCHARACTERISTICS(A) DosDevIOCtl((long) NULL,  \

                 (char far *) &A,                         \

                 IoctlCodeSetLinkChar,                    \

                 CELDDCAT,                                \

                 seldrvrh)

#define TRANSMITFRAME(F,L) DosDevIOCtl(F,              \

                 &L,                                 \

                 IoctlCodeTxFrame,                   \

                 CELDDCAT,                           \

                 seldrvrh)

#define RECEIVEFRAME(F,L)  DosDevIOCtl(F,              \

                         &L,                         \

                         IoctlCodeRxFrame,           \

                         CELDDCAT,                   \

                         seldrvrh)

#endif

//############################################################################

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

/* INFO_ : additional information error codes put in IoStatus.Information    */

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

#define INFO_CANT_ALLOCATE_SPINLOCK      1

#define INFO_CANT_CONNECT_INTERRUPT      2

#define INFO_HARDWARE_INIT_FAILURE       3

#define INFO_SET_EVENT_NO_EVENT          4

#define INFO_HARDWARE_CMD_TIMEOUT        5

#define INFO_LINKCHAR_BUF_WRONG_SIZE     6

#define INFO_FRAME_BUF_TOO_BIG           7

#define INFO_FRAME_BUF_TOO_SMALL         8

#define INFO_NO_CLOCKS                   9

#define INFO_NO_DMA_FDX                 10

#define INFO_CANT_ALLOCATE_MDL          11

#define INFO_CANT_ALLOCATE_MEMORY       12

#define INFO_DMA_BUFFER_UNUSABLE        14

#define INFO_TX_BUFFER_FULL             15

#define INFO_TX_FRAME_TOO_BIG           16

#define INFO_TX_FRAME_TOO_SMALL         17

#define INFO_READ_IR_BUFFER_WRONG_SIZE  18

#define INFO_NEEDS_MCA_BUS              19

#define INFO_NEEDS_ISA_BUS              20