Copyright: LUA Programmer's Guide
Citation: LUA Programmer's Guide


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


LUA Programmer's Guide Contents
Microsoft SNA Server

LUA Programmer's Guide

Contents

Before You Begin

Chapter 1	Concepts

Chapter 2	Writing LUA Applications

Chapter 3	LUA RUI Verbs

Chapter 4	LUA SLI Verbs

Chapter 5	Extensions for the Windows Environment

Appendix A	SNA Server Enhancements to the Windows Environment

Appendix B	Verb Control Block

Appendix C	Common Return Codes

Appendix D	LUA Code Samples in the SDK

List of Figures

List of Tables


LUA Programmer's Guide Contents
Microsoft SNA Server

LUA Programmer's Guide

Contents

Before You Begin

How to Use This Guide

Document Conventions

Common Abbreviations

Finding Further Information

Chapter 1	Concepts

Chapter 2	Writing LUA Applications

Chapter 3	LUA RUI Verbs

Chapter 4	LUA SLI Verbs

Chapter 5	Extensions for the Windows Environment

Appendix A	SNA Server Enhancements to the Windows Environment

Appendix B	Verb Control Block

Appendix C	Common Return Codes

Appendix D	LUA Code Samples in the SDK

List of Figures

List of Tables


LUA Programmer's Guide Contents
Microsoft SNA Server

LUA Programmer's Guide

Contents

Before You Begin

Chapter 1	Concepts

Windows LUA Overview

Windows LUA Asynchronous Support

Before Using Windows LUA

Using Asynchronous Verb Completion

LUs and Sessions

Configuring for LUA

LUA Verbs

Verb Summary

A Sample LUA Communication Sequence

RUI and SLI Sessions

Chapter 2	Writing LUA Applications

Chapter 3	LUA RUI Verbs

Chapter 4	LUA SLI Verbs

Chapter 5	Extensions for the Windows Environment

Appendix A	SNA Server Enhancements to the Windows Environment

Appendix B	Verb Control Block

Appendix C	Common Return Codes

Appendix D	LUA Code Samples in the SDK

List of Figures

List of Tables


LUA Programmer's Guide Contents
Microsoft SNA Server

LUA Programmer's Guide

Contents

Before You Begin

Chapter 1	Concepts

Chapter 2	Writing LUA Applications

Using LUA Verbs

RUI/SLI Definition

Issuing an LUA Verb

The LUA VCB Format

Common Data Structure

Specific Data Structure

Synchronous and Asynchronous Verb Completion

Synchronous Verb Completion

Asynchronous Verb Completion

Compiling and Linking an LUA Application

Resetting LUA LUs

Multiple Processes and Multiple Sessions

LUA Pools: Programming Techniques

Writing Portable Applications

Windows NT System Considerations

Windows Environment Considerations

MS-DOS System Considerations

OS/2 Considerations

SNA Considerations

Chapter 3	LUA RUI Verbs

Chapter 4	LUA SLI Verbs

Chapter 5	Extensions for the Windows Environment

Appendix A	SNA Server Enhancements to the Windows Environment

Appendix B	Verb Control Block

Appendix C	Common Return Codes

Appendix D	LUA Code Samples in the SDK

List of Figures

List of Tables


LUA Programmer's Guide Contents
Microsoft SNA Server

LUA Programmer's Guide

Contents

Before You Begin

Chapter 1	Concepts

Chapter 2	Writing LUA Applications

Chapter 3	LUA RUI Verbs

RUI_BID

RUI_INIT

Using 3270 LUs

Encryption

RUI_PURGE

RUI_READ

RUI_TERM

RUI_WRITE

Chapter 4	LUA SLI Verbs

Chapter 5	Extensions for the Windows Environment

Appendix A	SNA Server Enhancements to the Windows Environment

Appendix B	Verb Control Block

Appendix C	Common Return Codes

Appendix D	LUA Code Samples in the SDK

List of Figures

List of Tables


LUA Programmer's Guide Contents
Microsoft SNA Server

LUA Programmer's Guide

Contents

Before You Begin

Chapter 1	Concepts

Chapter 2	Writing LUA Applications

Chapter 3	LUA RUI Verbs

Chapter 4	LUA SLI Verbs

SLI_BID

SLI_CLOSE

SLI_OPEN

Secondary with INITSELF

Secondary with an Unformatted LOGON Message

Primary Waiting for a BIND Command

Primary with SSCP Access

BIND, CRV, and STSN Routines

Recovering from SESSION_FAILURE

Ending a Pending SLI_OPEN

SLI_PURGE

SLI_RECEIVE

SLI_SEND

SLI_BIND_ROUTINE

SLI_STSN_ROUTINE

Chapter 5	Extensions for the Windows Environment

Appendix A	SNA Server Enhancements to the Windows Environment

Appendix B	Verb Control Block

Appendix C	Common Return Codes

Appendix D	LUA Code Samples in the SDK

List of Figures

List of Tables


LUA Programmer's Guide Contents
Microsoft SNA Server

LUA Programmer's Guide

Contents

Before You Begin

Chapter 1	Concepts

Chapter 2	Writing LUA Applications

Chapter 3	LUA RUI Verbs

Chapter 4	LUA SLI Verbs

Chapter 5	Extensions for the Windows Environment

WinRUI( ) / WinSLI( )

WinRUICleanup( ) / WinSLICleanup( )

WinRUIGetLastInitStatus( )

WinRUIStartup( ) / WinSLIStartup( )

RUI( ) / SLI( )

Appendix A	SNA Server Enhancements to the Windows Environment

Appendix B	Verb Control Block

Appendix C	Common Return Codes

Appendix D	LUA Code Samples in the SDK

List of Figures

List of Tables


LUA Programmer's Guide Contents
Microsoft SNA Server

LUA Programmer's Guide

Contents

Before You Begin

Chapter 1	Concepts

Chapter 2	Writing LUA Applications

Chapter 3	LUA RUI Verbs

Chapter 4	LUA SLI Verbs

Chapter 5	Extensions for the Windows Environment

Appendix A	SNA Server Enhancements to the Windows Environment

GetLuaReturnCode( )

Appendix B	Verb Control Block

Appendix C	Common Return Codes

Appendix D	LUA Code Samples in the SDK

List of Figures

List of Tables


LUA Programmer's Guide Contents
Microsoft SNA Server

LUA Programmer's Guide

Contents

Before You Begin

Chapter 1	Concepts

Chapter 2	Writing LUA Applications

Chapter 3	LUA RUI Verbs

Chapter 4	LUA SLI Verbs

Chapter 5	Extensions for the Windows Environment

Appendix A	SNA Server Enhancements to the Windows Environment

Appendix B	Verb Control Block

Common Structure of LUA VCBs

Values for lua_message_type

Command-Specific Structure of LUA VCBs

SLI_OPEN VCB Structure

SLI_BID and RUI_BID VCB Structure

SLI_SEND VCB Structure

Appendix C	Common Return Codes

Appendix D	LUA Code Samples in the SDK

List of Figures

List of Tables


LUA Programmer's Guide Contents
Microsoft SNA Server

LUA Programmer's Guide

Contents

Before You Begin

Chapter 1	Concepts

Chapter 2	Writing LUA Applications

Chapter 3	LUA RUI Verbs

Chapter 4	LUA SLI Verbs

Chapter 5	Extensions for the Windows Environment

Appendix A	SNA Server Enhancements to the Windows Environment

Appendix B	Verb Control Block

Appendix C	Common Return Codes

Primary Return Codes

Secondary Return Codes

Appendix D	LUA Code Samples in the SDK

List of Figures

List of Tables


LUA Programmer's Guide Contents
Microsoft SNA Server

LUA Programmer's Guide

Contents

Before You Begin

Chapter 1	Concepts

Chapter 2	Writing LUA Applications

Chapter 3	LUA RUI Verbs

Chapter 4	LUA SLI Verbs

Chapter 5	Extensions for the Windows Environment

Appendix A	SNA Server Enhancements to the Windows Environment

Appendix B	Verb Control Block

Appendix C	Common Return Codes

Appendix D	LUA Code Samples in the SDK

Specifying a Filename for Table G for Code Conversion

Code Samples Using the RUI APIs

Code Samples Using the SLI APIs

List of Figures

List of Tables


LUA Programmer's Guide Contents
Microsoft SNA Server

LUA Programmer's Guide

Contents

Before You Begin

Chapter 1	Concepts

Chapter 2	Writing LUA Applications

Chapter 3	LUA RUI Verbs

Chapter 4	LUA SLI Verbs

Chapter 5	Extensions for the Windows Environment

Appendix A	SNA Server Enhancements to the Windows Environment

Appendix B	Verb Control Block

Appendix C	Common Return Codes

Appendix D	LUA Code Samples in the SDK

List of Figures

SNA Components Required for LUA Communications

Sample LUA Communications Sequence

List of Tables


LUA Programmer's Guide Contents
Microsoft SNA Server

LUA Programmer's Guide

Contents

Before You Begin

Chapter 1	Concepts

Chapter 2	Writing LUA Applications

Chapter 3	LUA RUI Verbs

Chapter 4	LUA SLI Verbs

Chapter 5	Extensions for the Windows Environment

Appendix A	SNA Server Enhancements to the Windows Environment

Appendix B	Verb Control Block

Appendix C	Common Return Codes

Appendix D	LUA Code Samples in the SDK

List of Figures

List of Tables

LUA Configuration Components

Common Data Structure Parameters

RUI_BID-Specific Data Structure Parameter

SLI_SEND Parameter Settings Based on lua_message_type

Common VCB Structure

Possible Values for lua_message_type

SLI_OPEN VCB Structure

SLI_BID and RUI_BID VCB Structure

SLI_SEND VCB Structure


Before You Begin
1 of 5

Before You Begin

The Microsoft SNA Server LUA Programmer’s Guide explains how to develop C-language applications that use the conventional Logical Unit Application programming interface (LUA) to exchange data in a Systems Network Architecture (SNA) environment.

This implementation of LUA is compatible with the request unit interface (RUI) and the session level interface (SLI) of LUA for the Microsoft [image] Windows NT [image] operating system, the Microsoft Windows [image] graphical environment, and the IBM [image] Extended Services for OS/2 [image] version 1.0 (IBM ES for OS/2 version 1.0).

This guide provides conceptual information for programmers who are not familiar with LUA and detailed reference information for experienced LUA programmers.

Before reading this guide, you should be familiar with:

General concepts for the communications software you have installed. Refer to your product documentation for more information.

Microsoft C version 5.1 or later.

One of the following operating environments:

Microsoft Windows NT

Microsoft Windows version 3.0 or later

IBM ES for OS/2 version 1.0

SNA concepts.


How to Use This Guide
Before You Begin	2 of 5

How to Use This Guide

The guide contains the following chapters:

Chapter 1, “Concepts”

Introduces the fundamental concepts of LUA and includes information on the SNA concepts involved in LUA.

Chapter 2, “Writing LUA Applications”

Provides general information needed for writing LUA applications. This chapter also includes information on compiling and linking an LUA application.

Chapter 3, “LUA RUI Verbs”

Describes each RUI verb.

Chapter 4, “LUA SLI Verbs”

Describes each SLI verb and routine.

Chapter 5, “Extensions for the Windows Environment”

Provides extensions to the Windows LUA.

Appendix A, “SNA Server Enhancements to the Windows Environment”

Describes the API extension to Windows LUA that converts primary and secondary return codes in the VCB to a printable string.

Appendix B, “Verb Control Block”

Defines the structure of individual Windows LUA verb control blocks (VCBs), including the common structures and the command-specific structures of LUA VCBs.

Appendix C, “Common Return Codes”

Provides a listing of all return codes in hexadecimal order.

Appendix D, “LUA Code Samples in the SDK”

Describes the LUA code samples in the SNA Server SDK.


Document Conventions
Before You Begin	3 of 5

Document Conventions

The following document conventions are used in this guide.

Convention	Purpose

bold	Indicates syntax items that must be typed exactly as shown.

italic	Indicates variables.

monospace	Represents examples and program code.

SMALL CAPS	Represent return values and key names, such as CTRL.

UPPERCASE	Represents filenames, paths, volumes, array and structure names, values, and conversation states.

[brackets]	Enclose optional items in syntax statements.

{braces}	Enclose required items in syntax statements.

| (vertical bar)	Stands for OR and separates items in syntax statements.

... (ellipsis)	Indicates that the preceding syntax item can be repeated. If a punctuation mark precedes the ellipsis, you must include the punctuation when repeating the item.

X'nnnn'	Indicates hexadecimal digits.


Common Abbreviations
Before You Begin	4 of 5

Common Abbreviations

The following abbreviations are used in this guide.

Abbreviation	Description

API	application programming interface

APPC	Advanced Program-to-Program Communications

ASCII	American Standard Code for Information Interchange

CPI-C	Common Programming Interface for Communications

CSV	Common Service Verb

DAF	destination address field

DFT	distributed function terminal

DLC	data link control

DLL	dynamic-link library

DR1I	definite response 1 indicator

DR2I	definite response 2 indicator

EBCDIC	Extended Binary Coded Decimal Interchange Code

EDI	enciphered data indicator

ERI	exception response indicator

EXR	exception request

K	kilobyte

LU	logical unit

LUA	conventional Logical Unit Application programming interface

MB	megabyte

NAU	network addressable unit

NC	network control

NCP	Network Control Panel

NSPE	network services procedure error

OAF	originating address field

PC	personal computer

PDI	padded data indicator

PU	physical unit

PVC	permanent virtual circuit

QLLC	qualified logical link control

QRI	queued response indicator

RH	request/response header

RTI	response-type-indicator

RU	request/response unit

RUI	Request Unit Interface

SC	session control

SDI	sense-data-included indicator

SDLC	Synchronous Data Link Control

SLI	Session Level Interface

SNA	Systems Network Architecture

SSCP	system service control point

STSN	set and test sequence number

SVC	switched virtual circuit

TH	transmission header

TP	transaction program

TS	transmission service

VCB	verb control block

VTAM	Virtual Telecommunications Access Method


Finding Further Information
Before You Begin	5 of 5

Finding Further Information

This guide does not provide a detailed explanation of the products, architectures, or standards developed by other companies or organizations. For information on OS/2, refer to your OS/2 manuals. For information on Microsoft Windows version 3.0 and 3.1, refer to your Windows manuals.

For information about SNA, refer to your system network documentation.

The following manuals provide additional information about SNA Server application programming interfaces (APIs):

Microsoft SNA Server APPC Programmer’s Guide

Microsoft SNA Server CPI-C Programmer’s Guide

Microsoft SNA Server Reference

For more information about SNA and about 3270 information display systems, see the following manuals:

IBM 3270 Information Display System: 3274 Control Unit Description and Programmer’s Guide

IBM 3270 Information Display System: Color and Programmed Symbols

IBM 3270 Information Display System: 3274 Control Unit Display Station: Operator’s Guide

IBM Systems Network Architecture: Technical Overview

IBM Systems Network Architecture: Concepts and Products

IBM Advanced Communications Function Products Installation Guide

IBM Installation and Resource Definition

IBM 9370 LAN Token Ring Support

IBM SNA Format and Protocol Reference Manual: Architectural Logic

For background information about logical unit (LU) 6.2, Advanced Program-to-Program Communications (APPC), and/or the Common Programming Interface for Communications (CPI-C), see the following manuals:

IBM Systems Network Architecture: Introduction to APPC

IBM Systems Network Architecture: Transaction Programmer’s Reference Manual for LU Type 6.2

IBM SNA: Format and Protocol Reference Manual: Architecture Logic for LU Type 6.2

IBM SNA: Formats

IBM SNA: Technical Overview

IBM SNA: ACF/VTAM Programming for LU Type 6.2


Concepts
Chapter 1	1 of 10

Concepts

The conventional Logical Unit Application programming interface (LUA) is an application programming interface (API) that allows you to write LUA applications to communicate with host applications.

The interface is provided at the request/response unit (RU) and session levels, allowing programmable control over the Systems Network Architecture (SNA) messages sent between your communications software and the host. It can be used to communicate with any of the logical unit (LU) types 0, 1, 2, or 3 at the host; it is up to the application to send the appropriate SNA messages as required by the host.

For example, you can use LUA to write a 3270 emulation program that communicates with a host 3270 application.


Windows LUA Overview
Concepts	2 of 10

Windows LUA Overview

In order to provide one common API to port applications from various operating environments to Windows NT and Windows version 3.x, a Windows SNA standard was created. As a direct result of this work, Windows LUA was developed. The LUA verbs (both Request Unit Interface [RUI] and Session Level Interface [SLI]), routines, and information presented in this guide represent an evolving Windows LUA that is based on IBM ES for OS/2 version 1.0 and includes a set of Windows enhancements.


Windows LUA Asynchronous Support
Concepts	3 of 10

Windows LUA Overview

Windows LUA Asynchronous Support

Asynchronous verb completion returns the initial verb immediately so the application can continue with other processes. A program that issues a verb and does not regain control until the operation completes is not able to perform any other operations. This type of operation, referred to as blocking, is not suited to a server application designed to handle multiple requests from many clients.

By design, LUA is asynchronous and uses semaphores for notification messages. While semaphores work extremely well for the Windows NT and OS/2 systems, the Windows enhancements built into Windows LUA also allows for asynchronous support for Windows version 3.x applications in the LUA interface. Windows LUA provides the following entry-points for both RUI and SLI verbs:  RUI, SLI, WinRUI, and WinSLI. WinRUI and WinSLI provide asynchronous message notification for all Windows-based RUI and SLI verbs while RUI and SLI provide support for event notification. Windows version 3.x applications use WinRUI and WinSLI for asynchronous message notification.

Asynchronous support allows you to be notified of verb completion on a Windows handle. Through RegisterWindowsMessage with "WinRUI" or "WinSLI" as the string, you pass a Windows handle by which you are notified of verb completion. You then make your call and once it completes, a message is posted to the Windows handle that you passed, notifying you that the verb is complete.

The only Windows extensions required for Windows LUA are for initialization (WinRUIStartup or WinSLIStartup) and termination (WinRUICleanup or WinSLICleanup) purposes. Depending on your application, other Windows extension may be useful to you, but they are not required. A complete description of all Windows LUA verbs, routines, and extensions is provided in: Chapter 3, "LUA RUI Verbs" Chapter 4, "LUA SLI Verbs" Chapter 5, "Extensions for the Windows Environment"


Before Using Windows LUA
Concepts	4 of 10

Windows LUA Overview

Before Using Windows LUA

The following Windows enhancements are of particular importance and should be reviewed before using this version of SNA Server:

WinRUI/WinSLI

Provides asynchronous notification for all Windows-based RUI and SLI verbs. When the asynchronous operation is complete, the application's window hWnd receives the message returned by RegisterWindowMessageBwith "WinRUI" or "WinSLI" as the input string. The lParam argument contains the address of the verb control block (VCB) being posted as complete. The wParam argument is undefined.

Note

An application must call either WinRUIStartupBor WinSLIStartup before it calls WinRUI/WinSLI

Contrast with RUI/SLI.

WinRUIStartup/WinSLIStartup

Allows an application to specify the version of Windows LUA required and to retrieve details of the specific LUA implementation.

Important

This function must be called by an application before issuing any further Windows LUA calls to register itself with a Windows LUA implementation.

WinRUICleanup/WinSLICleanup

Terminates and deregisters an application from a Windows LUA implementation.

Important

This function must be called by an application when finished to deregister itself from the Windows LUA implementation.

RUI/SLI

Provides event notification for all RUI and SLI verbs. The application must provide a handle to an event in the lua_post_handle parameter of the VCB. The event must be in the not-signaled state. When the asynchronous operation is complete, the application is notified via the signaling of the event. Upon signaling of the event, examine the primary return code and secondary return code for any error conditions.

Contrast with WinRUI/WinSLI.

Using Asynchronous Verb Completion

SNA Server permits one outstanding Windows SNA asynchronous call per connection and one blocking verb per thread. When the asynchronous verb completes, LUA does the following depending on your environment:

For a Windows NT system, two types of notification are possible. Either the LUA application issues WaitforSingleObject/WaitForMultipleObject or it posts the "WinRUI/WinSLI" notification message to the Windows handle of the WinRUI/WinSLI message. The event method is the preferred way to receive asynchronous notification in the Windows NT system.

For the Windows version 3.x system, it notifies the completion of an asynchronous request by posting the "WinRUI/WinSLI" notification message to the Windows handle of the WinRUI/WinSLI message. A Windows handle has been added as the first parameter passed to the WinRUI and WinSLI entry point.

For OS/2, it notifies the completion of an asynchronous request by posting a message to the application's Window procedure or by clearing a semaphore/event. Additionally, the application can use system queues for asynchronous verbs.

For more information on RUI verbs, SLI verbs and routines, and the Windows extensions, see: Chapter 3, "LUA RUI Verbs" Chapter 4, "LUA SLI Verbs" Chapter 5, "Extensions for the Windows Environment"


LUs and Sessions
Concepts	5 of 10

LUs and Sessions

Figure 1.1 shows the SNA components required for LUA communications.

Figure 1.1    SNA Components Required for LUA Communications

An LUA application uses a local LU, which uses SNA Server to communicate with the host system. There are three progressive sessions when the SNA Server connects to the host node:

The PU-SSCP session, between the SNA Server physical unit (PU) and the host's system services control point (SSCP); this is used mainly for diagnostic information. LUA communications require only the capabilities of PU 2.0; SNA Server provides these capabilities, plus the additional capabilities included in PU 2.1.

The SSCP-LU session, between the LUA LU at the personal computer (PC) and the SSCP; this is used for controlling the LU.

The LU-LU session, between the LUA LU at the PC and the host LU; this is used for data transfer between the PC and the host application.

LUA allows applications to send and receive data on the SSCP-LU session and on the LU-LU session. It does not provide access to the PU-SSCP session. (An LUA application can send data on this session using the Common Service Verb (CSV) TRANSFER_MS_DATA.)

The SSCP and LU sessions each provide two priorities of messages, normal and expedited. Expedited messages take precedence over other messages waiting to be transmitted on the same session. There are, therefore, four different flows on which a message can be sent or received:

SSCP session (expedited flow)

LU session (expedited flow)

SSCP session (normal flow)

LU session (normal flow)

The LU session normal flow carries most of the data; the other flows are used only for control purposes.

Note that this implementation of LUA does not allow applications to send data on the SSCP expedited flow and does not return data to an application on this flow.


Configuring for LUA
Concepts	6 of 10

LUs and Sessions

Configuring for LUA

SNA Server configuration file - which is set up and maintained by the system administrator - contains information that is required for LUA applications to communicate. An LUA LU is configured  to use a connection to the host by the link service and given an LU number that matches that of an LU on the host.

The configuration may include LUA LU pools. A pool is a group of LUs with similar characteristics, and it allows an application to use any free LU from the pool. This feature can be used to allocate LUs on a first-come, first-served basis when there are more applications than LUs available or to provide a choice of LUs on different connections.

The following communications components are configured for use with an LUA application.

Table 1.1    LUA Configuration Components

Item	Description

Link service	A link service for communicating with the host. This component is configured during installation of SNA Server by the Setup program.

Connection	A connection to the host that uses the link service.

Local node	A local node, which owns the connection. This component is configured automatically.

LUA LU	An LUA LU on the local node, configured to use the connection, with an LU number that matches an LU on the host.

LUA LU pool (optional)	If necessary, you can configure more than one LUA LU for the application, and group the LUs into a pool. This means that an application can specify the pool rather than a specific LU when issuing RUI_INIT to start a session. SNA Server uses this name in one of the ways described in the following paragraphs.

If the name supplied is the name of an LU that is not in a pool, a session is assigned using that LU if it is available (that is, if it is not already in use by an LUA application).

If the name supplied is the name of an LU pool, or the name of any LU within the pool, a session is assigned using the first available LU in the pool (if one is available). Note that this may not be the LU whose name was specified by RUI_INIT.


LUA Verbs
Concepts	7 of 10

LUA Verbs

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


Verb Summary
Concepts	8 of 10

LUA Verbs

Verb Summary

The following is a brief summary of each LUA verb or user-supplied routine. For a detailed explanation of each verb, see: Chapter 3, "LUA RUI Verbs" Chapter 4, "LUA SLI Verbs"

RUI_BID

Allows the application to determine when information from the host is available to be read.

RUI_INIT

Sets up the SSCP-LU session for an LUA application.

RUI_PURGE

Cancels an outstanding RUI_READ.

RUI_READ

Receives data or status information sent from the host to the LUA application's LU, on either the SSCP session or the LU session.

RUI_TERM

Ends the SSCP session for an LUA application. It also terminates the LU session if it is active.

RUI_WRITE

Sends data to the host on either the SSCP session or the LU session.

SLI_BID

Notifies the SLI application that a message is waiting to be read using SLI_RECEIVE. SLI_BID also provides the current status of the session to the LUA application.

SLI_CLOSE

Ends a session opened with SLI_OPEN.

SLI_OPEN

Transfers control of the specified LU to the LUA application. SLI_OPEN establishes a session between the SSCP and the specified LU, as well as an LU-LU session.

SLI_PURGE

Cancels SLI_RECEIVE verbs issued with a wait condition.

SLI_RECEIVE

Receives responses, SNA commands, and data into an LUA application's buffer. SLI_RECEIVE also provides the current status of the session to the LUA application.

SLI_SEND

Sends responses, SNA commands, and data from an LUA application to a host LU.

SLI_BIND_ROUTINE

An optional, user-supplied exit routine that notifies the LUA application that a BIND request has come from the host. It allows the routine to examine the request and formulate a response.

SLI_STSN_ROUTINE

An optional, user-supplied exit routine that notifies the LUA application that a set and test sequence number (STSN) command has come from the host. It allows the routine to examine the request and formulate a response.


A Sample LUA Communication Sequence
Concepts	9 of 10

A Sample LUA Communication Sequence

This section provides an example of an LUA communication sequence. Figure 1.2 illustrates the LUA verbs used to start a session, to exchange data, and to end the session, as well as the SNA messages sent and received. The arrows indicate the direction in which SNA messages flow.

Figure 1.2    Sample LUA Communications Sequence

In the example shown in Figure 1.2, the application performs the following tasks:

Issues RUI_INIT or SLI_OPEN to establish the SSCP session. (RUI_INIT does not complete until the LUA application has received an ACTLU message from the host and sent a positive response; however, these messages are handled by SNA Server and are not exposed to the LUA application.)

Sends an INITSELF message to the SSCP to request a BIND and reads the response.

Reads a BIND message from the host and writes the response. This establishes the LU session.

Reads an SDT message from the host, which indicates that initialization is complete and data transfer can begin.

Note

INITSELF, BIND, and SDT messages are handled by SNA Server if the application is using SLI. The SLI_OPEN does not return until SNA Server has sent an SDT and response.

For an RUI session:

Sends a chain of data consisting of three RUs (the last indicates that a definite response is required) and reads the response.

Reads a chain of data consisting of three RUs and writes the response.

Reads an UNBIND message from the host and writes the response. This terminates the LU session.

For an SLI session:

Issues SLI_SEND and SLI_RECEIVE to transfer data, SNA commands, or SNA responses between the host and the application.

Issues RUI_TERM or SLI_CLOSE to terminate the SSCP session. (SNA Server sends a NOTIFY message to the host and waits for a positive response; however, these messages are handled by SNA Server and not exposed to the LUA application.)


RUI and SLI Sessions
Concepts	10 of 10

RUI and SLI Sessions

LUA application programs can establish and use SNA sessions with either the RUI API or the SLI API. If an LUA application establishes an SNA session using RUI_INIT, it cannot issue any SLI verbs for that session. Likewise, if an LUA application establishes an SNA session using SLI_OPEN, it cannot issue any RUI verbs for that session.


Writing LUA Applications
Chapter 2	1 of 20

Writing LUA Applications

The information contained in this chapter will help you write LUA application programs for use with SNA Server. The following topics are covered:

Using LUA verbs

Synchronous and asynchronous verb completion

Compiling and linking an LUA application

Resetting LUA LUs

Multiple processes and multiple sessions

Writing portable applications

Windows NT, Windows, MS-DOS [image], and OS/2 system considerations

SNA considerations


Using LUA Verbs
Writing LUA Applications	2 of 20

Using LUA Verbs

This implementation of LUA is available to applications written in Microsoft C version 5.1 or later. Applications access all LUA functions by calling the external C function RUI or SLI.

Symbolic constants are defined in the WINLUA.H header file for many parameter values. Refer to the WINLUA.H file (contained in the SNA Server Software Development Kit) for a list of LUA constants.

You should use the symbolic constant and not the hexadecimal value when setting values for supplied parameters, or when testing values of returned parameters.

Parameters marked as "reserved" should always be set to 0.


RUI/SLI Definition
Writing LUA Applications	3 of 20

Using LUA Verbs

RUI/SLI Definition

The definitions of the RUI and SLI functions are as follows:

void far RUI(verb)

void far SLI(verb)

struct LUA_VERB_RECORD far * verb;

The WINLUA.H header file supplied with your SNA Server Software Development Kit does not include a declaration of this function; you need to include it in your program source. (This is intended for compatibility with IBM ES for OS/2 version 1.0, which does not include this declaration in its supplied LUA header file.)

The only parameter passed to the RUI or SLI function is the address of a VCB. The VCB is a structure made up of variables that identify the LUA verb to be executed, supply information used by the verb, and contain information returned by the verb when execution is complete. The VCB structure is declared in the WINLUA.H header file. See: Chapter 3, “LUA RUI Verbs” Chapter 4, “LUA SLI Verbs” for a detailed listing of the VCB structure.


Issuing an LUA Verb
Writing LUA Applications	4 of 20

Using LUA Verbs

Issuing an LUA Verb

The following procedure is required to issue an LUA verb. In this case, the verb issued is RUI_INIT.

1.	Create a variable for the VCB structure. For example:

#include <winlua.h>
  .
  .
  .
struct LUA_VERB_RECORD rui_init;

The LUA_VERB_RECORD structure is declared in the WINLUA.H header file.

2.	Clear (set to 0) the variables within the VCB:

memset( &rui_init, 0, sizeof( rui_init) );

LUA requires that all reserved parameters, and all parameters not required by the particular verb being issued, must be set to 0. The simplest way to do this is to set the entire VCB to zeros before setting the parameters required for this particular verb.

3.	Assign values to the VCB parameters that supply information to LUA:

rui_init.common.lua_verb = LUA_VERB_RUI;

rui_init.common.lua_verb_length = sizeof(struct LUA_COMMON);

rui_init.common.lua_opcode = LUA_OPCODE_RUI_INIT;

memcpy (rui_init.common.lua_luname, "THISLU  ", 8);

The values LUA_VERB_RUI and LUA_OPCODE_RUI_INIT are symbolic constants. These constants are defined in the WINLUA.H header file in the SNA Server Software Development Kit. To ensure portability between different systems, use symbolic constants and not integer values.

4.	Invoke LUA. The only parameter is a pointer to the address of the structure containing the VCB for the desired verb.

RUI( &rui_init );

5.	Check the asynchronous flag (rui_init.common.lua_flag2.async) to determine whether the verb completed asynchronously. If events are being used and the verb did complete asynchronously, wait for the event to complete.

if (rui_init.common.lua_flag2.async)
{
/* verb will complete asynchronously so continue
with other processing */
/* then wait */
WaitForSingleObject (...)
}

Do not check the return code; it may have changed from LUA_IN_PROGRESS to LUA_OK by the time you check it.

6.	Check the variables returned by LUA.

if( rui_init.common.lua_prim_rc == LUA_OK )
{
/* Init OK */
       .
       .
       .
}
else

{
/* Do error routine */
.
.
.
}


The LUA VCB Format
Writing LUA Applications	5 of 20

The LUA VCB Format

The VCB consists of two parts:

A common part, which is used for all verbs

A specific part, which is used only by RUI_BID

To access parameters in the common part of the VCB, you need to include the structure name COMMON. For example, when using a verb record structure THIS_VERB, you access lua_prim_rc as this_verb.common.lua_prim_rc.

Similarly, for RUI_BID, you access lua_peek_data as this_verb.specific.lua_peek_data.

For a complete listing of the structures and related values in the LUA VCB, see Appendix B, "Verb Control Block."


Common Data Structure
Writing LUA Applications	6 of 20

The LUA VCB Format

Common Data Structure

Table 2.1 lists the common data structure parameters used by all the LUA verbs.

Table 2.1    Common Data Structure Parameters

Field	Type	Explanation
lua_verb	unsigned short	Specifies the Windows LUA verb code. It must always contain a value of X'5200'.
lua_verb_length	unsigned short	Specifies the length of the VCB.
lua_prim_rc	unsigned short	Primary return code set by Windows LUA at the completion of the verb.
lua_sec_rc	unsigned long	Secondary return code set by Windows LUA at the completion of the verb.
lua_opcode	unsigned short	Specifies the Windows LUA command to be executed.
lua_correlator	unsigned long	Contains a user-supplied value that links the verb with other user-supplied information.
lua_luname	unsigned char[8]	Specifies the ASCII name for the local LU to be used for the Windows LUA session.
lua_extension_list_offset	unsigned short	Specifies the offset from the start of the VCB to the extension list of user-supplied dynamic-link libraries (DLLs).
lua_cobol_offset	unsigned short	Not defined in the Windows LUA standard. Set to 0.
lua_sid	unsigned long	Specifies the session ID of the LUA session on which this verb is issued.
lua_max_length	unsigned short	Indicates the length of the buffer used to receive data.
lua_data_length	unsigned short	Specifies the length of the data to be sent, or the actual length of data received.
lua_data_ptr	char far *	Indicates a pointer to the application data buffer.
lua_post_handle	unsigned long	For the Windows NT system, contains the handle of the event to be signaled for asynchronous notification by events.
lua_th	struct (see the following parameters)	Contains the data structure containing SNA transmission header (TH) of the message sent or received, as follows:
lua_th.flags_fid	four bits	Format identification type 2.
lua_th.flags_mpf	two bits	Segmenting mapping field.
lua_th.flags_odai	one bit	Originating address field - destination address field (OAF-DAF) assignor indicator.
lua_th.flags_efi	one bit	Expedited flow indicator.
lua_th.daf	unsigned char	Destination address field (DAF).
lua_th.oaf	unsigned char	Originating address field (OAF).
lua_th.snf	unsigned char[2]	Sequence number field.
lua_rh	struct (see the following parameters)	A data structure containing the SNA request/response header (RH) of the message sent or received, as follows:
lua_rh.rri	one bit	Request-response indicator.
lua_rh.ruc	two bits	RU category.
lua_rh.fi	one bit	Format indicator.
lua_rh.sdi	one bit	Sense data included indicator.
lua_rh.bci	one bit	Begin chain indicator.
lua_rh.eci	one bit	End chain indicator.
lua_rh.dr1i	one bit	Definite response 1 indicator.
lua_rh.dr2i	one bit	Definite response 2 indicator.
lua_rh.ri	one bit	Exception response indicator (for a request), or response type indicator (for a response).
lua_rh.qri	one bit	Queued response indicator.
lua_rh.pi	one bit	Pacing indicator.
lua_rh.bbi	one bit	Begin bracket indicator.
lua_rh.ebi	one bit	End bracket indicator.
lua_rh.cdi	one bit	Change direction indicator.
lua_rh.csi	one bit	Code selection indicator.
lua_rh.edi	one bit	Enciphered data indicator.
lua_rh.pdi	one bit	Padded data indicator.
lua_flag1	struct (see the following parameters)	Contains a data structure containing flags for messages supplied by the application, as follows:
lua_flag1.bid_enable	one bit	Bid enable indicator.
lua_flag1.close_abend	one bit	Close immediate indicator.
lua_flag1.nowait	one bit	No wait for data flag.
lua_flag1.sscp_exp	one bit	SSCP expedited flow.
lua_flag1.sscp_norm	one bit	SSCP normal flow.
lua_flag1.lu_exp	one bit	LU expedited flow.
lua_flag1.lu_norm	one bit	LU normal flow.
lua_message_type	unsigned char	Specifies the type of the inbound or outbound SNA commands and data.
lua_flag2	struct (see the following parameters)	Contains a data structure containing flags for messages returned by LUA, as follows:
lua_flag2.bid_enable	one bit	Bid enabled indicator.
lua_flag2_async	one bit	Asynchronous verb completion flag.
lua_flag2.sscp_exp	one bit	SSCP expedited flow.
lua_flag2.sscp_norm	one bit	SSCP normal flow.
lua_flag2.lu_exp	one bit	LU expedited flow.
lua_flag2.lu_norm	one bit	LU normal flow.
lua_encr_decr_option	unsigned char	On RUI_INIT, only the following are supported: lua_encr_decr_option = 0 lua_encr_decr_option = 128


Specific Data Structure
Writing LUA Applications	7 of 20

The LUA VCB Format

Specific Data Structure

Table 2.2 shows the data structure that is included for RUI_BID only.

Table 2.2    RUI_BID-Specific Data Structure Parameter

Field	Type	Explanation
lua_peek_data	unsigned char[12]	Up to 12 bytes of the data waiting to be read.


Synchronous and Asynchronous Verb Completion
Writing LUA Applications	8 of 20

Synchronous and Asynchronous Verb Completion

LUA verbs can complete execution either synchronously or asynchronously. These completion types are explained in this section.


Synchronous Verb Completion
Writing LUA Applications	9 of 20

Synchronous and Asynchronous Verb Completion

Synchronous Verb Completion

When LUA is able to complete all the processing for a verb as soon as it is issued, the verb has completed synchronously. When this happens, the primary return code is set to a value other than LUA_IN_PROGRESS, and the lua_flag2.async bit is set to 0. (See: Chapter 3, “LUA RUI Verbs” Chapter 4, “LUA SLI Verbs” for information on these returned parameters.)


Asynchronous Verb Completion
Writing LUA Applications	10 of 20

Synchronous and Asynchronous Verb Completion

Asynchronous Verb Completion

Some LUA verbs complete quickly after some local processing (for example, RUI_PURGE); however, most verbs take some time to complete because they require messages to be sent to and received from the local node or from the host application.

When LUA must wait for information from the remote LU or from the local node before it can complete the verb, the verb completes asynchronously.

When this happens, the primary return code is set to LUA_IN_PROGRESS, and the lua_flag2.async bit is set to 1. The application can now perform other processing, or wait for notification from LUA that the verb has completed. LUA issues this notification by setting the primary return code to its final value and leaving lua_flag2.async set to 1.

When the verb completes, LUA does the following depending on your environment:

For a Windows NT system, two types of notification are possible. Either the LUA application issues WaitForSingleObject/WaitForMultipleObject or posts the "WinRUI/WinSLI" notification message to the Windows handle of the "WinRUI/WinSLI" message. The event method is the preferred way to receive asynchronous notification in the Windows NT system.

In the Windows environment, it notifies the completion of an asynchronous request by posting the "WinRUI/WinSLI" notification message to the Windows handle of the "WinRUI/WinSLI" message. A Windows handle has been added as the first parameter passed to the WinRUI and WinSLI entry point.

For OS/2, it notifies the completion of an asynchronous request by posting a message to the application’s Window procedure or by clearing a semaphore/event. Additionally, the application can use system queues for asynchronous verbs.

Note that if the verb completes synchronously, LUA does not clear the semaphore.


Compiling and Linking an LUA Application
Writing LUA Applications	11 of 20

Compiling and Linking an LUA Application

To compile and link an LUA application for use with SNA Server, follow these general steps:

1.	Update the path statement to include the directory containing the LUA application.

2.	Set any required environmental variables.

3.	Compile the application, including the WINLUA.H header file, provided in the SNA Server Software Development Kit, to produce the .OBJ files.

4.	Link the application with the WINLUA.LIB library to produce an .EXE file.


Resetting LUA LUs
Writing LUA Applications	12 of 20

Resetting LUA LUs

SNA Server provides a facility for resetting LUA LUs or forcing off LUA applications, which is useful if an application has become deadlocked or is looping.

The NetView [image] command deactivate-oldlu can also be used to reset an LUA LU. These facilities interact with the LUA application as described in the following sections.

When an LUA LU is reset through SNA Server, or by using the deactivate-oldlu command, SNA Server sends an UNBIND message to the application (as though the host had issued it).

The UNBIND message sent to the application is X'32' X'0E', indicating a recoverable LU failure, and is returned to the application on a subsequent RUI_READ. The LU session is terminated, but the SSCP session remains active (that is, the LU is returned to the same state as if RUI_INIT has just completed).


Multiple Processes and Multiple Sessions
Writing LUA Applications	13 of 20

Multiple Processes and Multiple Sessions

Two processes cannot use the same LUA session. Only the process that issues RUI_INIT can use the session that is started by the verb. Before another process can use LUA, it must issue RUI_INIT to obtain a new session. However, different threads of the same process can issue verbs for the same LUA session.

A single process can simultaneously use more than 1 LUA session (up to 512 for applications based on the Windows NT, Windows version 3.x, or OS/2 systems) by issuing multiple RUI_INIT verbs. Each session must use a different LU; two or more sessions may use the same pool, but the lua_luname parameter (which is either the name of the pool or the name of an LU within the pool) must be different for each RUI_INIT.

Two or more instances of the same LUA application can run as different processes, but they must use different LUs. This can be done by using LU pools; the two processes can specify the same pool and are allocated different LUs from that pool.


LUA Pools: Programming Techniques
Writing LUA Applications	14 of 20

LUA Pools: Programming Techniques

When working with an LUA LU pool, specify the pool name at the beginning of the conversation, and then use the lua_sid parameter (not the pool name) with subsequent calls. This is necessary because the lua_sid parameter is a unique identifier, but the pool name is not (since a pool is designed to supply LUs for multiple conversations). The following paragraph gives a more detailed description of this process.

When using RUI_INIT or SLI_OPEN with an LUA pool, specify the pool name with the lua_luname parameter. Then, for subsequent calls in the same conversation, use the lua_sid parameter returned from RUI_INIT or SLI_OPEN to specify the conversation.

Also note that on completion of RUI_INIT or SLI_OPEN, the lua_luname parameter will contain the actual name of the LU used. This allows you to create code for a display for the user, showing the actual LU name used in a particular conversation.


Writing Portable Applications
Writing LUA Applications	15 of 20

Writing Portable Applications

Use the following guidelines for writing LUA applications that are portable to other environments:

Use the symbolic constant names for parameter values and return codes, not the numeric values shown in the WINLUA.H file. (See the WINLUA.H file in the SNA Server Software Development Kit for more information.)

When accessing SNA sense codes in a data buffer, use the symbolic constants rather than the numeric values; this ensures that the byte storage order is correct for your particular system. You should use memcpy to set the values, and memcmp to test them. For example:

memcpy (this_verb.common.lua_data_ptr, LUA_INCORRECT_REQ_CODE, 4);
if (memcmp (this_verb.common.lua_data_ptr,
LUA_INCORRECT_REQ_CODE, 4) == 0)
{
.....
}

Ensure that any parameters shown as reserved are set to 0.

Set the lua_verb_length parameter as described in Chapter 3, “LUA RUI Verbs.”


Windows NT System Considerations
Writing LUA Applications	16 of 20

Windows NT System Considerations

This section provides information about developing LUA applications on a Windows NT system.

Byte ordering

The values of constants defined in the WINLUA.H file are dependent on the byte ordering of the hardware used. Macros are used to set the constants to the correct value.

Currently, the include files in the Windows NT system use the i386 [image] and MIPS [image] macros to indicate the hardware. These same macros are used by SNA Server, along with the Win32 [image] macro, to indicate the byte ordering needs. The macros must be defined in the application or on the command line when building the application.

For example, the primary return code of LUA_PARAMETER_CHECK is defined to have a value of X'001'. Depending on the environment, the constant LUA_PARAMETER_CHECK may or may not be X'0001'. Some formats will define the value as it appears in memory, others will define it as a 2-byte variable. Because it cannot be assumed that the application will always use provided constants rather than hard-wired values, a macro can be defined to swap the bytes. The following example shows how the macro can be used:

#define LUA_PARAMETER_CHECK LUA_FLIPI (0X0001)
/* X '0001' */

Packing

For performance considerations, the VCBs are not packed. As a result, DWORDs are on DWORD boundaries, WORDs on WORDs, and BYTEs on BYTEs. This means, for example, that there is a 2-byte gap between the primary and secondary return codes. VCBs should be accessed using the structures provided.

Events

To receive data asynchronously, an event handle is passed in the semaphore field of the VCB. This event must be in the nonsignaled state when passed to LUA, and the handle must have EVENT_MODIFY_STATE access to the event.

Multiple threads

An LUA application can have multiple threads that issue verbs. LUA for the Windows NT system makes provisions for multithreaded Windows NT-based processes. A process contains one or more threads of execution. All references to threads refer to actual threads in a multithreaded Windows NT environment.

Load-time linking

To be dynamically linked to LUA at load time, you must do one of the following at link time:

Insert the following imports statements in the definition (.DEF) file used to link the application:

(For RUI)

IMPORTS WINRUI.RUI
IMPORTS WINRUI/WinRUI
IMPORTS WINRUI.WinRUIStartup
IMPORTS WINRUI.WinRUICleanup

(For SLI)

IMPORTS WINSLI.SLI
IMPORTS WINSLI.WinSLI
IMPORTS WINSLI.WinSLIStartup
IMPORTS WINSLI.WinSLICleanup

Link the application to WINRUI.LIB (for RUI) or WINSLI.LIB (for SLI), which contain the entry-point linkage information.

Run-time linking

For an application to be dynamically linked to LUA at run time, it must issue the following calls:

LoadLibrary to load the dynamic load libraries for Windows LUA. That is, WINRUI.DLL or WINRUI32.DLL (for RUI), and WINSLI.DLL or WINSLI32.DLL (for SLI).

GetProcAddress to specify LUA on all the desired entry points to the DLL. For RUI, the entry points are RUI, WinRUI, WinRUIStartup, and WinRUICleanup. For SLI, the entry points are SLI, WinSLI, WinSLIStartup, and WinSLICleanup.

Registering and deregistering applications

All LUA applications for the Windows NT system must call the Windows SNA extension WinRUIStartup/WinSLIStartup at the beginning of the session to register the application and WinRUICleanup/WinSLICleanup at the end of the session to deregister the application. For more information on using the Windows SNA extensions, see Chapter 5, “Extensions for the Windows Environment.”

Library names

In preparation for the coexistence of Win16 and Win32 API libraries on the same computer, the Win32 DLL names have been changed.

Old DLL names	New DLL names

WINRUI.DLL	WINSLI.DLL

WINRUI32.DLL	WINSLI32.DLL

The old DLL names should be used for Win32-based applications that are required to run on SNA Server version 2.0. The new DLL names should be used for Win32-based applications that are intended to run only on SNA Server version 2.1 or later versions.

If you intend your Win32-based application to be used with SNA Server version 2.0, you should link with the libraries included with SNA Server version 2.0. Otherwise use the new libraries provided with SNA Server version 2.1.


Windows Environment Considerations
Writing LUA Applications	17 of 20

Windows Environment Considerations

This section summarizes information for developing LUA applications on a Windows version 3.x system.

Packing

VCB’s are not packed. As a result, DWORDs and WORDs are on WORD boundaries, and BYTEs are on BYTE boundaries. This means, for example, that there is not a 2-byte gap between the primary and secondary return codes. VCBs should be accessed using the structures provided, and compiler options that change this packing method should be avoided.

Simultaneous sessions

An application can participate in as many as 16 sessions simultaneously with the Windows environment. However, if more than 1 LUA application is active at once, the total number of sessions cannot exceed 16.

Load-time linking

To be dynamically linked to LUA at load time, you must do one of the following at link time:

Insert the following imports statements in the definition (.DEF) file used to link the application:

(For RUI)

IMPORTS WINRUI.RUI
IMPORTS WINRUI/WinRUI
IMPORTS WINRUI.WinRUIStartup
IMPORTS WINRUI.WinRUICleanup

(For SLI)

IMPORTS WINSLI.SLI
IMPORTS WINSLI.WinSLI
IMPORTS WINSLI.WinSLIStartup
IMPORTS WINSLI.WinSLICleanup

Link the application to WINRUI.LIB (for RUI) or WINSLI.LIB (for SLI), which contain the entry-point linkage information.

Run-time linking

For an application to be dynamically linked to LUA at run time, it must issue the following calls:

LoadLibrary to load WINRUI.DLL (for RUI) or WINSLI.DLL (for SLI), the dynamic load libraries for Windows LUA.

GetProcAddress to specify LUA on all the desired entry points to the DLL. For RUI, the entry points are RUI, WinRUI, WinRUIStartup, and WinRUICleanup. For SLI, the entry points are SLI, WinSLI, WinSLIStartup, and WinSLICleanup.

Registering and deregistering applications

All Windows LUA applications must call the Windows SNA extension WinRUIStartup/WinSLIStartup at the beginning of the session to register the application and WinRUICleanup/WinSLICleanup at the end of the session to deregister the application. For more information on using Windows SNA extension, see Chapter 5, “Extensions for the Windows Environment.”


MSDOS System Considerations
Writing LUA Applications	18 of 20

MS-DOS System Considerations

This section summarizes information for developing LUA applications on an MS-DOS system. Only RUI is supported on MS-DOS; SLI is not supported on MS-DOS.

Packing

VCB’s are not packed. As a result, DWORDs and WORDs are on WORD boundaries, and BYTEs are on BYTE boundaries. This means, for example, that there is not a 2-byte gap between the primary and secondary return codes. VCBs should be accessed using the structures provided, and compiler options that change this packing method should be avoided.

Load-time linking

To be dynamically linked to LUA at load time, you must link the application to DOSACS.LIB, which contains the entry-point linkage information.

Implementing semaphores

RUI signals that an asynchronous verb has completed by setting lua_post_handle to 0. For example:

/*Set lua_post_handle to non-zero value  */
rui_innit.common.lua_post_handle = 1l ;

/*Issue RUI verb  */
RUI  (&rui_init)  ;

/*Check to see if verb will complete asynchronously  */
if (rui_init.common.lua_flag2.async)

{

/*Verb will complete asynchronously  */

To wait for the verb to complete, loop until lua_post_handle is cleared. For example:

while (rui_init.common.lua_post_handle  != 0)

{

/* The application is free to do other work in this loop  */

}

/* The loop has exited, so the verb completed  */

Keep in mind the following guidelines:

The application should set lua_post_handle to 0 before it issues a verb.

A single MS-DOS application can run up to 16 sessions, but memory limitations can cause problems if the application sends anything except very small RUs.  A more realistic limit is two to three sessions per application.


OS/2 Considerations
Writing LUA Applications	19 of 20

OS/2 Considerations

This section summarizes information for developing LUA applications on OS/2.

This implementation of LUA is binary compatible with the implementation of the RUI and SLI interfaces in IBM ES for OS/2 version 1.0 LUA. Note that this LUA implementation does not support user-defined encryption and decryption routines.

Since LUA is binary compatible with the IBM ES for OS/2 version 1.0 RUI and SLI implementation, there are no migration steps for IBM ES for OS/2 version 1.0 applications. However, if you recompile an IBM ES for OS/2 version 1.0 LUA application for use with LUA, include the WINLUA.H header file provided in the SNA Server Software Development Kit to ensure complete platform compatibility.

Packing

VCB’s are not packed. As a result, DWORDs and WORDs are on WORD boundaries, and BYTEs are on BYTE boundaries. This means, for example, that there is not a 2-byte gap between the primary and secondary return codes. VCBs should be accessed using the structures provided, and compiler options that change this packing method should be avoided.

Data segments

Data is sent from and received in data buffers established by the application. A data buffer must reside on an unnamed, shared data segment and must fit entirely within the data segment. Many data buffers can reside on the same data segment.

The data segment for the VCB must have read and write attributes. It can be one of the following:

A variable (not a local variable as LUA will copy data to it on completion of the verb).

Allocated dynamically using DosAllocSeg or DosSubAlloc.

VCB segment

The segment containing the VCB must be a writable segment. All reserved and unused fields in the VCB should be set to X'00'.

Simultaneous sessions

An application can participate simultaneously in as many as 512 sessions per OS/2 process.

Load-time linking

For an application to be dynamically linked to LUA at load time, you must do one of the following at link time:

Insert the following imports statement in the definition (.DEF) file used to link the application:

(For RUI)
IMPORTS RUI.RUI

(For SLI)
IMPORTS SLI.SLI

Link the application to ACSRUI.LIB (for RUI) or ACSSLI.LIB (for SLI), which contain the entry-point linkage information for various APIs.

Run-time linking

For an application to be dynamically linked to LUA at run time, it must issue the following calls:

DosLoadModule to load ACSRUI.DLL (for RUI) or ACSSLI.DLL (for SLI), the dynamic load libraries for LUA.

DosGetProcAddr to set the entry point RUI or SLI to the dynamic link library.

Unlinking (the DosFreeModule call) is not supported.

Stack size

The recommended stack size for an application is at least 3000 bytes.

When executing a verb, LUA uses the calling application’s stack. The combination of OS/2 and LUA requires 2560 bytes of stack space, and the application requires additional stack space for its variables.

Process support

A single RUI or SLI LU can be used by only a single process. A single process may act as multiple RUI/SLI applications and have sessions using multiple LUs.

Multiple threads

An application session can have multiple threads that issue verbs. However, the same thread of an application cannot issue two verbs simultaneously. If LUA is executing a verb and the same thread of the application issues a verb, LUA returns the LUA_UNSUCCESSFUL return code to the later verb and leaves it unexecuted.

Critical sections

Exercise great caution when using critical sections, which are the parts of a program that must run without interruption. An application must not issue an LUA verb within a critical section.

OS/2 exception TRAP 000D

The OS/2 exception TRAP 000D is issued when LUA is unable to pass a return code to the application for one of the following reasons:

The data segment containing the VCB is not read/writable.

The VCB is fewer than 10 bytes in length.

The semaphore supplied through the lua_post_handle parameter is neither a valid RAM or OS/2 system semaphore nor a pointer to a location within a writable segment.


SNA Considerations
Writing LUA Applications	20 of 20

SNA Considerations

This section explains SNA information you need to consider when writing LUA applications.

BIND checking

During initialization of the LU session, the host sends to the LUA application a BIND message that contains information such as RU sizes for use by the LU session. SNA Server returns this message to the LUA application on RUI_READ. The LUA application must verify that the parameters specified on the BIND are suitable. The application has the following options:

It can accept the BIND as it is, by issuing RUI_WRITE containing an OK response to the BIND. No additional BIND data can be sent on the response.

It can try to negotiate one or more BIND parameters (this is only permitted if the BIND is negotiable). To do this, the application issues RUI_WRITE containing an OK response, but including the modified BIND as data.

It can reject the BIND by issuing RUI_WRITE containing a negative response, using an appropriate SNA sense code as data.

See Chapter 3, “LUA RUI Verbs,” for more information on RUI_WRITE.

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

SNA Server rejects any RUI_WRITE that specifies an RU length greater than the size specified on the BIND.

SNA Server requires the BIND to specify that the secondary LU is the contention winner and that error recovery is the responsibility of the contention loser.

Note

For SLI, an application must specify that it will use SLI_BIND_ROUTINE on the SLI_OPEN if it will do any BIND checking.

Negative responses and SNA sense codes

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

When the host sends a negative response to a request from the LUA application, this includes an SNA sense code indicating the reason for the negative response. This is reported to the application on a subsequent RUI_READ or SLI_RECEIVE with the primary return code set to LUA_OK; the request/response indicator, response type indicator, and sense data included indicator all set to 1, indicating a negative response that includes sense data; and the data returned by RUI_READ or SLI_RECEIVE is the SNA sense code.

When SNA Server receives invalid data from the host, it generally sends a negative response to the host and does not pass the invalid data to the LUA application. This is reported to the application on a subsequent RUI_READ, SLI_RECEIVE, RUI_BID, or SLI_BID with the primary return code set to LUA_NEGATIVE_RESPONSE, and the secondary return code is the SNA sense code sent to the host.

In some cases, SNA Server detects that data supplied by the host is invalid, but cannot determine the correct sense code to send. In this case, it passes the invalid data in an exception request (EXR) to the LUA application on RUI_READ or SLI_RECEIVE with the request/response indicator set to 0, indicating a request; the sense data included indicator is set to 1, indicating that sense data is included (this indicator is normally used only for a response); and the message data is replaced by a suggested SNA sense code.

The application must then send a negative response to the message; it may use the sense code suggested by SNA Server, or it may alter it.

SNA Server may send a sense code to the application to indicate that data supplied by the application was invalid. This is reported to the application on RUI_WRITE or SLI_SEND, which supplied the data with the primary return code set to LUA_UNSUCCESSFUL and the secondary return code is the SNA sense code.

The sense codes that can be returned as secondary return codes on LUA verbs are listed in the WINLUA.H header file; see the SNA Server Software Development Kit for this file.

Distinguishing SNA sense codes from other secondary return codes

A secondary return code that is not a sense code always contains a value of 0 in its first 2 bytes.

An SNA sense code always contains a nonzero value in its first two bytes; the first byte gives the sense code category, and the second identifies a particular sense code within that category. (The third and fourth bytes may contain additional information, or may be 0.)

Information on SNA sense codes

If you need information on a returned sense code, see your IBM manuals. The sense codes are listed in numerical order by category.

Pacing

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

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

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

Segmentation

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

Courtesy acknowledgments

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

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

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

Purging data to end of chain

When the host sends a chain of request units to an LUA application, the application may wait until the last RU in the chain is received before sending a response, or it may send a negative response to an RU that is not the last in the chain. If a negative response is sent midchain, LUA purges all subsequent RUs from this chain and does not send them to the application.

When LUA receives the last RU in the chain, it indicates this to the application by setting the primary return code of RUI_READ or RUI_BIDBto LUA_NEGATIVE_RESPONSE with a 0 secondary return code.

Note that the host may terminate the chain by sending a message such as CANCEL while in midchain. In this case, the CANCEL message is returned to the application on RUI_READ. The LUA_NEGATIVE_RESPONSE return code (as described earlier) is not used.


LUA RUI Verbs
Chapter 3	1 of 7

LUA RUI Verbs

This chapter describes the LUA RUI verbs. It provides the following information for each RUI verb:

Details of the LUA verb control block structure for all RUI verbs.

A description of each RUI verb and its purpose.

Parameters (VCB fields) supplied to and returned by LUA. The description of each parameter includes information on the valid values for that parameter.

Interaction with other verbs.

There are six RUI verbs:

RUI_BID

Notifies the RUI application that a message is waiting to be read using RUI_READ.

RUI_INIT

Transfers control of the specified LU to the LUA application and establishes a session between the SSCP and the specified LU.

RUI_PURGE

Cancels a previous RUI_READ.

RUI_READ

Receives responses, SNA commands, and data into an LUA application’s buffer.

RUI_TERM

Ends both the LU session and the SSCP session for a given LUA LU.

RUI_WRITE

Sends an SNA RU from the LUA application to the host, over either the LU session or the SSCP session, and sends responses, SNA commands, and data from an LUA application to the host LU.

For information about the LUA SLI verbs, see Chapter 4, “LUA SLI Verbs.”


RUI_BID
LUA RUI Verbs	2 of 7

RUI_BID

Notifies the RUI application that a message is waiting to be read using RUI_READ.

Syntax

lua_opcode	unsigned short int

lua_prim_rc	unsigned short int

lua_sec_rc	unsigned long int

lua_verb	unsigned short int

lua_verb_length	unsigned short int

lua_luname	unsigned char

lua_post_handle	unsigned long int

lua_correlator	unsigned long int

lua_sid	unsigned long int

lua_data_length	unsigned int

lua_peek_data	unsigned char[12]

lua_th	struct (unsigned) char

lua_rh	struct (unsigned) char

lua_message_type	unsigned char

lua_flag2.async	struct (unsigned) char

lua_flag2.sscp_exp	struct member (unsigned) char

lua_flag2.sscp_norm	struct member (unsigned) char

lua_flag2.lu_exp	struct member (unsigned) char

lua_flag2.lu_norm	struct member (unsigned) char

Parameter	Description

lua_opcode	Supplied parameter; LUA_OPCODE_RUI_BID.

lua_verb	Supplied parameter; LUA_VERB_RUI.

lua_verb_length	Supplied parameter; specifies the length, in bytes, of the LUA VCB. It must contain the length of the verb being issued.

lua_luname	Supplied parameter; specifies the ASCII name of the local LU used by the Windows LUA session.

SLI_OPEN and RUI_INIT require this parameter. Other Windows LUA verbs only require this parameter if lua_sid is 0.

This parameter is 8 bytes long; pad on the right with spaces, X'20', if the name is shorter than 8 characters.

lua_post_handle	Returned parameter; for the Windows NT system, if asynchronous notification is to be accomplished by events, lua_post_handle contains the handle of the event to be signaled.

For all other environments, this parameter is reserved and should be set to 0.

lua_correlator	Supplied parameter; a user-supplied value that links the verb with other user-supplied information. LUA does not use or change this information. This parameter is optional.

lua_sid	Supplied/returned parameter; specifies the session ID and is returned by SLI_OPEN and RUI_INIT. Other verbs use this parameter to identify the session used for the command. If other verbs use the lua_luname parameter to identify sessions, set the lua_sid parameter to 0.

lua_data_length	Returned parameter; specifies the length of data returned in lua_peek_data.

lua_peek_data	Returned parameter; contains the first 12 bytes of the message data.

lua_th	Returned parameter; contains the SNA TH of the message sent or received. Various subparameters are to be set for write functions and returned for read functions. For a list of the subparameters that apply to this parameter, see Appendix B, “Verb Control Block.”

lua_rh	Returned parameter; contains the SNA RH of the message sent or received. It is set for the write function and returned by the read and bid functions. For a list of the bit masks that apply to this parameter, see Appendix B, “Verb Control Block.”

lua_message-type	Returned parameter; specifies the type of SNA message indicated to RUI_BID. Possible values are:

LUA_MESSAGE_TYPE_LU_DATA

LUA_MESSAGE_TYPE_SSCP_DATA

LUA_MESSAGE_TYPE_BID

LUA_MESSAGE_TYPE_BIND

LUA_MESSAGE_TYPE_BIS

LUA_MESSAGE_TYPE_CANCEL

LUA_MESSAGE_TYPE_CHASE

LUA_MESSAGE_TYPE_CLEAR

LUA_MESSAGE_TYPE_CRV

LUA_MESSAGE_TYPE_LUSTAT_LU

LUA_MESSAGE_TYPE_LUSTAT_SSCP

LUA_MESSAGE_TYPE_QC

LUA_MESSAGE_TYPE_QEC

LUA_MESSAGE_TYPE_RELQ

LUA_MESSAGE_TYPE_RQR

LUA_MESSAGE_TYPE_RTR

lua_message-type 	LUA_MESSAGE_TYPE_SBI

LUA_MESSAGE_TYPE_SHUTD

LUA_MESSAGE_TYPE_SIGNAL

LUA_MESSAGE_TYPE_SDT

LUA_MESSAGE_TYPE_STSN

LUA_MESSAGE_TYPE_UNBIND

The SLI receives and responds to the BIND, CRV, and STSN requests through the LUA interface extension routines.

LU_DATA, LUSTAT_LU, LUSTAT_SSCP, and SSCP_DATA are not SNA commands.

lua_flag2.async	Returned parameter; set to 1 if the LUA interface verb completed asynchronously.

lua_flag2.sscp_exp  	Returned parameter; flag indicates SSCP expedited flow.

lua_flag2.sscp_norm 	Returned parameter; flag indicates SSCP normal flow.

lua_flag2.lu_exp 	Returned parameter; flag indicates LU expedited flow.

lua_flag2.lu_norm	Returned parameter; flag indicates LU normal flow.

Return Codes

LUA_OK

Primary return code; the verb executed successfully.

LUA_CANCELED

Primary return code; the verb did not complete successfully because it was canceled by another verb:

LUA_TERMINATED

Secondary return code; RUI_TERM was issued while this verb was pending.

LUA_PARAMETER_CHECK

Primary return code; the verb did not execute because of a parameter error:

LUA_BAD_SESSION_ID

Secondary return code; an invalid value for lua_sid was specified in the VCB.

LUA_BID_ALREADY_ENABLED

Secondary return code; RUI_BID was rejected because a previous RUI_BID was already outstanding. Only one RUI_BID can be outstanding at any time.

LUA_INVALID_POST_HANDLE

Secondary return code; for a Windows NT system using events as the asynchronous posting method, the Windows LUA VCB does not contain a valid event handle.

For a Windows version 3.x system, the Windows LUA VCB does not contain the valid procedure address returned by the MakeProcInstance command.

For OS/2, the Windows LUA VCB does not contain a valid semaphore or queue handle, which is needed when the verb completes asynchronously.

LUA_RESERVED_FIELD_NOT_ZERO

Secondary return code; a reserved field in the verb record, or a parameter not used by this verb, was set to a nonzero value.

LUA_VERB_LENGTH_INVALID

Secondary return code; an LUA verb was issued with the value of lua_verb_length unexpected by the LUA.

LUA_STATE_CHECK

Primary return code; the verb did not execute because it was issued in an invalid state:

LUA_NO_RUI_SESSION

Secondary return code; RUI_INIT has not yet completed successfully for the LU name specified on this verb.

LUA_UNSUCCESSFUL

Primary return code; the verb record supplied was valid, but the verb did not complete successfully:

LUA_INVALID_PROCESS

Secondary return code; the process that issued this verb was not the same process that issued RUI_INIT for this session. Only the process that started a session can issue verbs on that session.

LUA_NEGATIVE_RSP

Primary return code; LUA detected an error in the data received from the host. Instead of passing the received message to the application on RUI_READ, LUA discards the message (and the rest of the chain if it is in a chain), and sends a negative response to the host.

LUA informs the application on a subsequent RUI_READ or RUI_BID that a negative response was sent.

The secondary return code contains the sense code sent to the host on the negative response. See “SNA Considerations” in Chapter 2 for information on interpreting the sense code values that can be returned.

A zero secondary return code indicates that, following a previous RUI_WRITE of a negative response to a message in the middle of a chain, LUA has now received and discarded all messages from this chain.

LUA_COMM_SUBSYSTEM_ABENDED

Primary return code; indicates one of the following conditions:

The node used by this conversation encountered an ABEND.

The connection between the TP and the PU 2.1 node has been broken (a LAN error).

The SnaBase at the TP’s computer encountered an ABEND.

LUA_SESSION_FAILURE

Primary return code; a required SNA Server component has terminated:

LUA_LU_COMPONENT_DISCONNECTED

Secondary return code; indicates that the LUA session has failed because of a problem with the link service or with the host LU.

LUA_RUI_LOGIC_ERROR

Secondary return code; an internal error was detected within LUA. This error should not occur during normal operation.

LUA_INVALID_VERB

Primary return code; either the verb code or the operation code, or both, is invalid. The verb did not execute.

LUA_STACK_TOO_SMALL

Primary return code; the stack size of the application is too small to execute the verb. Increase the stack size of your application.

LUA_COMM_SUBSYSTEM_NOT_LOADED

Primary return code; a required component could not be loaded or has terminated while processing the verb. Thus, communication could not take place. Contact the system administrator for corrective action.

LUA_UNEXPECTED_DOS_ERROR

Primary return code; after issuing an operating system call, an unexpected operating system return code was received and is specified in the secondary return code.

Remarks

RUI_BID is used by applications that require notification that a message is waiting to be read. This allows the application to determine how it will handle the message before issuing RUI_READ.

When a message is available, RUI_BID returns with details of the message flow on which it was received, the message type, the TH and RH of the message, and up to 12 bytes of message data.

The main difference between RUI_BID and RUI_READ is that RUI_BID allows the application to check the data without removing it from the incoming message queue, so it can be left and accessed at a later stage. RUI_READ removes the message from the queue, so once the application has read the data it must process it.

Note the following when using RUI_BID:

RUI_INIT must complete successfully before this verb is issued.

Only one RUI_BID can be outstanding at any one time.

After RUI_BID has completed successfully, it can be reissued by setting lua_flag1.bid_enable on a subsequent RUI_READ. If the verb is reissued in this way, the application must not free or modify the storage associated with the RUI_BID record.

If a message arrives from the host when RUI_READ and RUI_BID are both outstanding, RUI_READ completes and RUI_BID is left in progress.

Each message that arrives is bid only once. Once RUI_BID has indicated that data is waiting on a particular session flow, the application issues RUI_READ to receive the data. Any subsequent RUI_BID does not report data arriving on that session flow until the message that was bid has been accepted by issuing RUI_READ.

In general, the lua_data_length parameter returned on this verb indicates only the length of data in lua_peek_data, not the total length of data on the waiting message (except when a value of less than 12 is returned). The application should ensure that the data length on RUI_READ that accepts the data is sufficient to contain the message.


RUI_INIT
LUA RUI Verbs	3 of 7

RUI_INIT

Transfers control of the specified LU to the Windows LUA application. RUI_INIT establishes a session between the SSCP and the specified LU.

Note

For 3270 emulator users, an SNA Server extension has been added that allows you to use 3270 LUs, rather than the LUA LUs. For more information, see “Remarks” later in this section.

Syntax

lua_opcode	unsigned short int

lua_prim_rc	unsigned short int

lua_sec_rc	unsigned long int

lua_verb	unsigned short int

lua_verb_length	unsigned short int

lua_luname	unsigned char

lua_encr_decr_option	unsigned char

lua_post_handle	unsigned long int

lua_correlator	unsigned long int

lua_sid	unsigned long int

lua_flag2.async	struct member (unsigned) char

Parameter	Description

lua_opcode	Supplied parameter; LUA_OPCODE_RUI_INIT.

lua_verb	Supplied parameter; LUA_VERB_RUI.

lua_verb_length	Supplied parameter; specifies the length, in bytes, of the LUA VCB. It must contain the length of the verb being issued.

lua_luname	Supplied parameter; specifies the ASCII name of the local LU to be used for the Windows LUA session.

SLI_OPEN and RUI_INIT require this parameter. Other Windows LUA verbs require this parameter only if lua_sid is 0.

This parameter is 8 bytes long; pad on the right with spaces, X'20', if the name is shorter than 8 characters.

lua_encr_decr_option	Supplied parameter; on RUI_INIT only, the following options are supported:

   lua_encr_decr_option = 0

   lua_encr_decr_option  = 128

Values 1 – 127 are not supported.

lua_post_handle	Supplied parameter; for the Windows NT system, if asynchronous notification is to be accomplished by events, lua_post_handle contains the handle of the event to be signaled.

For all other environments, this parameter is reserved and should be set to 0.

lua_correlator	Supplied parameter; is a user-supplied value that links the verb with other user-supplied information. LUA does not use or change this information. This parameter is optional.

lua_sid	Returned parameter; specifies the session ID and is returned by SLI_OPEN and RUI_INIT. Other verbs use this parameter to identify the session used for the command. If other verbs use the lua_luname parameter to identify sessions, set the lua_sid parameter to 0.

lua_flag2.async	Returned parameter; set to 1 if the LUA interface verb completed asynchronously. (Note that RUI_INIT always completes asynchronously unless it returns an error such as LUA_PARAMETER_CHECK).

Return Codes

LUA_OK

Primary return code; the verb executed successfully.

LUA_CANCELED

Primary return code; the verb did not complete successfully because it was canceled by another verb:

LUA_TERMINATED

Secondary return code; RUI_TERM was issued before RUI_INIT had completed.

LUA_PARAMETER_CHECK

Primary return code; the verb did not execute because of a parameter error:

LUA_INVALID_LUNAME

Secondary return code; the lua_luname parameter did not match any LUA LU name or LU pool name in the configuration file.

LUA_INVALID_POST_HANDLE

Secondary return code; for a Windows NT system using events as the asynchronous posting method, the Windows LUA VCB does not contain a valid event handle.

For a Windows version 3.x system, the Windows LUA VCB does not contain the valid procedure address returned by the MakeProcInstance command.

For OS/2, the Windows LUA VCB does not contain a valid semaphore or queue handle, which is needed when the verb completes asynchronously.

LUA_RESERVED_FIELD_NOT_ZERO

Secondary return code; a reserved field in the verb record, or a parameter not used by this verb, was set to a nonzero value.

LUA_VERB_LENGTH_INVALID

Secondary return code; an LUA verb was issued with the value of lua_verb_length unexpected by the LUA.

LUA_STATE_CHECK

Primary return code; the verb did not execute because it was issued in an invalid state:

LUA_DUPLICATE_RUI_INIT

Secondary return code; the lua_luname parameter specified an LU name or LU pool name already in use by this application (or for which this application already has RUI_INIT in progress).

LUA_UNSUCCESSFUL

Primary return code; the verb record supplied was valid, but the verb did not complete successfully:

LUA_COMMAND_COUNT_ERROR

Secondary return code; one of the following occurred:

The verb could not be issued because the application had already reached its maximum number of active sessions. In the Windows environment, an application can have as many as 16 sessions active at any time. In OS/2, an application can have as many as 512 sessions active at any time.

The verb specified the name of an LU pool, or the name of an LU in a pool, but all LUs in the pool are in use.

LUA_ENCR_DECR_LOAD_ERROR

Secondary return code; the verb specified a value for lua_encr_decr_option other than 0 or 128.

LUA_INVALID_PROCESS

Secondary return code; the LU specified by lua_luname is in use by another process.

LUA_LINK_NOT_STARTED

Secondary return code; the connection to the host has not been started; none of the link services it could use are active.

LUA_COMM_SUBSYSTEM_ABENDED

Primary return code; indicates one of the following conditions:

The node used by this conversation encountered an ABEND.

The connection between the TP and the PU 2.1 node has been broken (a LAN error).

The SnaBase at the TP’s computer encountered an ABEND.

LUA_SESSION_FAILURE

Primary return code; a required SNA Server component has terminated:

LUA_LU_COMPONENT_DISCONNECTED

Secondary return code; indicates that the LUA session has failed because of a problem with the link service or with the host LU.

LUA_INVALID_VERB

Primary return code; either the verb code or the operation code, or both, is invalid. The verb did not execute.

LUA_STACK_TOO_SMALL

Primary return code; the stack size of the application is too small to execute the verb. Increase the stack size of your application.

LUA_COMM_SUBSYSTEM_NOT_LOADED

Primary return code; a required component could not be loaded or has terminated while processing the verb. Thus, communication could not take place. Contact the system administrator for corrective action.

LUA_UNEXPECTED_DOS_ERROR

Primary return code; after issuing an operating system call, an unexpected operating system return code was received and is specified in the secondary return code.

Remarks

This verb must be the first LUA verb issued for the session. Until this verb has completed successfully, the only other LUA verb that can be issued for this session is RUI_TERM (which terminates a pending RUI_INIT).

All other verbs issued on this session must identify the session using one of the following parameters from this verb:

The session ID, returned to the application in lua_sid.

The LU name or LU pool name, supplied by the application by the lua_luname parameter.

RUI_INIT completes after an ACTLU message is received from the host. If necessary, the verb waits indefinitely. If an ACTLU has already been received prior to RUI_INIT, LUA sends a NOTIFY to the host to inform it that the LU is ready for use. Note that neither ACTLU nor NOTIFY is visible to the LUA application.

Once RUI_INIT has completed successfully, this session uses the LU for which the session was started. No other LUA session (from this or any other application) can use the LU until RUI_TERM is issued, or until an LUA_SESSION_FAILURE primary return code is received.

Using 3270 LUs

To provide 3270 emulator users the ability to use the EIS configuration call with the RUI API, an SNA Server extension has been added to the RUI. This extension allows you to use 3270 LUs rather than LUA LUs.

To use 3270 LUs:

Set lua_resv56[1] = 1 on RUI_INIT

Note

All other reserved fields must be left blank.

For more information, see the SEPDCREC call in the 3270 Emulator Interface Specification.

Encryption

Session-level cryptography is implemented through CRV requests; RUI application(s) must perform all necessary processing. For all interfaces other than RUI, CRV requests are rejected with a negative response.

For RUI_INIT, the following options are supported:

lua_encr_decr_option = 0

lua_encr_decr_option = 128

Values 1-127 (ACSRENCR and ACSROECR routines) are not supported.

The sending application is responsible for padding data to a multiple of 8 bytes, and for setting the padded data indicator bit in the RH as well as for encryption. The receiving application is responsible for removing the padding after decryption.


RUI_PURGE
LUA RUI Verbs	4 of 7

RUI_PURGE

Cancels a previous RUI_READ.

Syntax

lua_opcode	unsigned short int

lua_prim_rc	unsigned short int

lua_sec_rc	unsigned long int

lua_verb	unsigned short int

lua_verb_length	unsigned short int

lua_luname	unsigned char

lua_sid	unsigned long int

lua_data_ptr	char far *

lua_post_handle	unsigned long int

lua_correlator	unsigned long int

lua_flag2.async	struct member (unsigned) char

Parameter	Description

lua_opcode	Supplied parameter; LUA_OPCODE_RUI_PURGE.

lua_verb	Supplied parameter; LUA_VERB_RUI.

lua_verb_length	Supplied parameter; specifies the length, in bytes, of the LUA VCB. It must contain the length of the verb being issued.

lua_luname	Supplied parameter; specifies the ASCII name of the local LU used by the Windows LUA session.

SLI_OPEN and RUI_INIT require this parameter. Other Windows LUA verbs require this parameter only if lua_sid is 0.

This parameter is 8 bytes long; pad on the right with spaces, X'20', if the name is shorter than 8 characters.

lua_sid	Supplied/returned parameter; specifies the session ID and is returned by SLI_OPEN and RUI_INIT. Other verbs use this parameter to identify the session used for the command. If other verbs use lua_luname to identify sessions, set lua_sid to 0.

lua_data_ptr	Supplied parameter; points to the application data buffer. Both SNA commands and data are placed in this buffer and they can be in an EBCDIC format.

When SLI_RECEIVE or RUI_READ is issued, this parameter points to the location to receive the data from the host.

When SLI_SEND or RUI_WRITE is issued, this parameter points to the location of the application’s data to be sent to the host.

When SLI_PURGE or RUI_PURGE is issued, this parameter points to the location of the SLI_RECEIVE or RUI_READ verb’s VCB that is to be canceled.

lua_data_ptr	When SLI_OPEN is issued, this parameter can be one of the following:

   The LOGON message for the SSCP normal flow when the initialization type is secondary with an unformatted LOGON message.

   The RU for INITSELF. When the initialization type is secondary with INITSELF, the necessary data for the application is provided.

   For all other open types, this field should be set to 0.

This information is provided by the Windows LUA application.

lua_post_handle	Supplied parameter; for the Windows NT system, if asynchronous notification is to be accomplished by events, lua_post_handle contains the handle of the event to be signaled.

For all other environments, this parameter is reserved and should be set to 0.

lua_correlator	Supplied parameter; a user-supplied value that links the verb with other user-supplied information. LUA does not use or change this information. This parameter is optional.

lua_flag2.async	Returned parameter; set to 1 if the LUA interface verb completed asynchronously.

Return Codes

LUA_OK

Primary return code; the verb executed successfully.

LUA_CANCELED

Primary return code; the verb did not complete successfully because it was canceled by another verb:

LUA_TERMINATED

Secondary return code; RUI_TERM was issued while RUI_PURGE was pending.

LUA_PARAMETER_CHECK

Primary return code; the verb did not execute because of a parameter error:

LUA_BAD_DATA_PTR

Secondary return code; the data_ptr parameter was set to null.

LUA_BAD_SESSION_ID

Secondary return code; an invalid value for lua_sid was specified in the VCB.

LUA_INVALID_POST_HANDLE

Secondary return code; for a Windows NT system using events as the asynchronous posting method, the Windows LUA VCB does not contain a valid event handle.

For a Windows version 3.x system, the Windows LUA VCB does not contain the valid procedure address returned by the MakeProcInstance command.

For OS/2, the Windows LUA VCB does not contain a valid semaphore or queue handle, which is needed when the verb completes asynchronously.

LUA_RESERVED_FIELD_NOT_ZERO

Secondary return code; a reserved field in the verb record, or a parameter not used by this verb, was set to a nonzero value.

LUA_VERB_LENGTH_INVALID

Secondary return code; an LUA verb was issued with the value of lua_verb_length unexpected by the LUA.

LUA_STATE_CHECK

Primary return code; the verb did not execute because it was issued in an invalid state:

LUA_NO_RUI_SESSION

Secondary return code; RUI_INIT has not yet completed successfully for the LU name specified on this verb.

LUA_UNSUCCESSFUL

Primary return code; the verb supplied was valid, but the verb did not complete successfully:

LUA_INVALID_PROCESS

Secondary return code; the OS/2 process that issued this verb was not the same process that issued RUI_INIT for this session. Only the process that started a session can issue verbs on that session.

LUA_NO_READ_TO_PURGE

Secondary return code; either lua_data_ptr did not contain a pointer to an RUI_READ VCB, or RUI_READ completed before RUI_PURGE was issued.

LUA_COMM_SUBSYSTEM_ABENDED

Primary return code; indicates one of the following conditions:

The node used by this conversation encountered an ABEND.

The connection between the TP and the PU 2.1 node has been broken (a LAN error).

The SnaBase at the TP’s computer encountered an ABEND.

LUA_SESSION_FAILURE

Primary return code; a required SNA Server component has terminated:

LUA_LU_COMPONENT_DISCONNECTED

Secondary return code; indicates that the LUA session has failed because of a problem with the link service or with the host LU.

LUA_RUI_LOGIC_ERROR

Secondary return code; an internal error was detected within LUA. This error should not occur during normal operation.

LUA_INVALID_VERB

Primary return code; either the verb code or the operation code, or both, is invalid. The verb did not execute.

LUA_STACK_TOO_SMALL

Primary return code; the stack size of the application is too small to execute the verb. Increase the stack size of your application.

LUA_COMM_SUBSYSTEM_NOT_LOADED

Primary return code; a required component could not be loaded or has terminated while processing the verb. Thus, communication could not take place. Contact the system administrator for corrective action.

LUA_UNEXPECTED_DOS_ERROR

Primary return code; after issuing an operating system call, an unexpected operating system return code was received and is specified in the secondary return code.

Remarks

RUI_READ may wait indefinitely if it is sent without using the lua_flag1.nowait (immediate return) option, and no data is available on the specified flow; RUI_PURGE forces the waiting verb to return (with the primary return code LUA_CANCELED).

This verb is used only when RUI_READ has been issued and is pending completion (that is, the primary return code is LUA_IN_PROGRESS).


RUI_READ
LUA RUI Verbs	5 of 7

RUI_READ

Receives responses, SNA commands, and data into a Windows LUA application’s buffer.

Syntax

lua_opcode	unsigned short int

lua_prim_rc	unsigned short int

lua_sec_rc	unsigned long int

lua_verb	unsigned short int

lua_verb_length	unsigned short int

lua_luname	unsigned char

lua_sid	unsigned long int

lua_max_length	unsigned int

lua_data_length	unsigned int

lua_data_ptr	char far *

lua_post_handle	unsigned long int

lua_flag1.bid_enable	struct member (unsigned) char

lua_flag1.nowait	struct member (unsigned) char

lua_flag1.sscp_exp	struct member (unsigned) char

lua_flag1.sscp_norm	struct member (unsigned) char

lua_flag1.lu_exp	struct member (unsigned) char

lua_flag1.lu_norm	struct member (unsigned) char

lua_correlator	unsigned long int

lua_th	struct (unsigned) char

lua_rh	struct (unsigned) char

lua_message_type	unsigned char

lua_flag2.async	struct member (unsigned) char

lua_flag2.bid_enable	struct member (unsigned) char

lua_flag2.sscp_exp	struct member (unsigned) char

lua_flag2.sscp_norm	struct member (unsigned) char

lua_flag2.lu_exp	struct member (unsigned) char

lua_flag2.lu_norm	struct member (unsigned) char

Parameters	Description

lua_opcode	Supplied parameter; LUA_OPCODE_RUI_READ.

lua_verb	Supplied parameter; LUA_VERB_RUI.

lua_verb_length	Supplied parameter; specifies the length, in bytes, of the LUA VCB. It must contain the length of the verb being issued.

lua_luname	Supplied parameter; specifies the ASCII name of the local LU used by the Windows LUA session.

SLI_OPEN and RUI_INIT require this parameter. Other Windows LUA verbs require this parameter only if lua_sid is 0.

This parameter is 8 bytes long; pad on the right with spaces, X'20', if the name is shorter than 8 characters.

lua_sid	Supplied/returned parameter; specifies the session ID and is returned by SLI_OPEN and RUI_INIT. Other verbs use this parameter to identify the session used for the command. If other verbs use lua_luname set lua_sid to 0.

lua_max_length	Supplied parameter; specifies the length of the buffer used to receive the data.

lua_data_length	Returned parameter; specifies the actual length of data to be sent or received.

lua_data_ptr	Supplied parameter; points to the application data buffer. Both SNA commands and data are placed in this buffer and they can be in an EBCDIC format.

When SLI_RECEIVE or RUI_READ is issued, this parameter points to the location to receive the data from the host.

When SLI_SEND or RUI_WRITE is issued, this parameter points to the location of the application’s data to be sent to the host.

When SLI_PURGE or RUI_PURGE is issued, this parameter points to the location of the SLI_RECEIVE or RUI_READ verb’s VCB that is to be canceled.

When SLI_OPEN is issued, this parameter can be one of the following:

   The LOGON message for the SSCP normal flow when the initialization type is secondary with an unformatted LOGON message.

   The RU for INITSELF. When the initialization type is secondary with INITSELF, the necessary data for the application is provided.

   For all other open types, this field should be set to 0.

This information is provided by the Windows LUA application.

lua_post_handle	Supplied parameter; for the Windows NT system, if asynchronous notification is to be accomplished by events, lua_post_handle contains the handle of the event to be signaled.

For all other environments, this parameter is reserved and should be set to 0.

lua_flag1	Supplied parameter.

Set lua_flag1.nowait to 1 to indicate that you want RUI_READ to return immediately whether or not data is available to be read, or set it to 0 if you want the verb to wait for data before returning.

Set lua_flag1.bid_enable to 1 to re-enable the most recent RUI_BID (equivalent to issuing RUI_BID again with exactly the same parameters as before), or set it to 0 if you do not want to re-enable RUI_BID. Note that re-enabling the previous RUI_BID reuses the VCB originally allocated for it, so this VCB must not have been freed or modified.

Set one or more of the following flags to 1 to indicate from which message flow to read data:

   lua_flag1.sscp_exp

   lua_flag1.lu_exp

   lua_flag1.sscp_norm

   lua_flag1.lu_norm

If more than one flag is set, the highest-priority data available is returned. The order of priorities (highest first) is: SSCP expedited, LU expedited, SSCP normal, LU normal. The equivalent flag in the lua_flag2 group is set to indicate from which flow the data was read.

lua_correlator	Supplied parameter; a user-supplied value that links the verb with other user-supplied information. LUA does not use or change this information. This parameter is optional.

lua_th	Returned parameter; contains the SNA TH of the message sent or received. Various subparameters are to be set for write functions and returned for read functions. For a list of subparameters that apply to this parameter, see Appendix B, “Verb Control Block.”

lua_rh	Returned parameter; contains the SNA RH of the message sent or received. It is set for the write function and returned by the read and bid functions. For a list of bit masks that apply to this parameter, see Appendix B, “Verb Control Block.”

lua_message_type 	Returned parameter; specifies the type of SNA message indicated to RUI_READ. Possible values are:

LUA_MESSAGE_TYPE_LU_DATA

LUA_MESSAGE_TYPE_SSCP_DATA

LUA_MESSAGE_TYPE_RQR

lua_message_type	LUA_MESSAGE_TYPE_BID

LUA_MESSAGE_TYPE_BIND

LUA_MESSAGE_TYPE_BIS

LUA_MESSAGE_TYPE_CANCEL

LUA_MESSAGE_TYPE_CHASE

LUA_MESSAGE_TYPE_CLEAR

LUA_MESSAGE_TYPE_CRV

LUA_MESSAGE_TYPE_LUSTAT_LU

LUA_MESSAGE_TYPE_LUSTAT_SSCP

LUA_MESSAGE_TYPE_QC

LUA_MESSAGE_TYPE_QEC

LUA_MESSAGE_TYPE_RELQ

LUA_MESSAGE_TYPE_RTR

LUA_MESSAGE_TYPE_SBI

LUA_MESSAGE_TYPE_SHUTD

LUA_MESSAGE_TYPE_SIGNAL

LUA_MESSAGE_TYPE_SDT

LUA_MESSAGE_TYPE_STSN

LUA_MESSAGE_TYPE_UNBIND

LU_DATA, LUSTAT_LU, LUSTAT_SSCP, and SSCP_DATA are not SNA commands.

lua_flag2	Returned parameter.

Set lua_flag2.async to 1 if the LUA interface verb completed asynchronously.

Set lua_flag2.bid_enable to 1 if RUI_BID was successfully re-enabled, or to 0 if it wasn’t re-enabled.

The lua_flag2 parameter contains flags for messages returned by LUA. One or more of the following flags are set to 1 to indicate on which message flow the date was received:

   lua_flag2.sscp_exp — returned parameter; flag indicates SSCP expedited flow

   lua_flag2.sscp_norm — returned parameter; flag indicates SSCP normal flow

   lua_flag2.lu_exp — returned parameter; flag indicates LU expedited flow

   lua_flag2.lu_norm — returned parameter; flag indicates LU normal flow

Return Codes

LUA_OK

Primary return code; the verb executed successfully.

LUA_CANCELED

Primary return code; the verb did not complete successfully because it was canceled by another verb or by an internal error:

LUA_PURGED

Secondary return code; RUI_READ has been canceled by RUI_PURGE.

LUA_TERMINATED

Secondary return code; RUI_TERM was issued while RUI_READ was pending.

LUA_PARAMETER_CHECK

Primary return code; the verb did not execute because of a parameter error:

LUA_BAD_DATA_PTR

Secondary return code; the data_ptr parameter contained an invalid value.

LUA_BAD_SESSION_ID

Secondary return code; an invalid value for lua_sid was specified in the VCB.

LUA_BID_ALREADY_ENABLED

Secondary return code; lua_flag1.bid_enable was set to re-enable RUI_BID but the previous RUI_BID was still in progress.

LUA_DUPLICATE_READ_FLOW

Secondary return code; the flow flags in the lua_flag1 group specified one or more session flows for which RUI_READ was already outstanding. Only one RUI_READ at a time can be waiting on each session flow.

LUA_INVALID_FLOW

Secondary return code; none of the lua_flag1 flow flags was set. At least one of these flags must be set to 1, to indicate from which flow or flows to read.

LUA_INVALID_POST_HANDLE

Secondary return code; for a Windows NT system using events as the asynchronous posting method, the Windows LUA VCB does not contain a valid event handle.

For a Windows version 3.x system, the Windows LUA VCB does not contain the valid procedure address returned by the MakeProcInstance command.

For OS/2, the Windows LUA VCB does not contain a valid semaphore or queue handle, which is needed when the verb completes asynchronously.

LUA_NO_PREVIOUS_BID_ENABLED

Secondary return code; lua_flag1.bid_enable was set to re-enable RUI_BID, but there was no previous RUI_BID that could be enabled. (See the next section for more information.)

LUA_RESERVED_FIELD_NOT_ZERO

Secondary return code; a reserved field in the verb record, or a parameter not used by this verb was set to a nonzero value.

LUA_VERB_LENGTH_INVALID

Secondary return code; an LUA verb was issued with the value of lua_verb_length unexpected by the LUA.

LUA_STATE_CHECK

Primary return code; the verb did not execute because it was issued in an invalid state:

LUA_NO_RUI_SESSION

Secondary return code; RUI_INIT has not yet completed successfully for the LU name specified on RUI_READ.

LUA_NEGATIVE_RSP

Primary return code; indicates one of the following two cases, which can be distinguished by the secondary return code:

LUA detected an error in the data received from the host. Instead of passing the received message to the application on RUI_READ, LUA discards the message (and the rest of the chain if it is in a chain), and sends a negative response to the host. LUA informs the application on a subsequent RUI_READ or RUI_BID that a negative response was sent.

The LUA application previously sent a negative response to a message in the middle of a chain. LUA has purged subsequent messages in this chain, and is now reporting to the application that all messages from the chain have been received and purged.

LUA_SEC_RC

Secondary return code; this parameter is a nonzero secondary return code containing the sense code sent to the host on the negative response. This indicates that LUA detected an error in the host data, and sent a negative response to the host. See Chapter 2, “Writing LUA Applications,” for information on interpreting the sense code values that may be returned.

A secondary return code of 0 indicates that, following a previous RUI_WRITE of a negative response to a message in the middle of a chain, LUA has now received and discarded all messages from this chain.

LUA_UNSUCCESSFUL

Primary return code; the verb record supplied was valid, but the verb did not complete successfully:

LUA_DATA_TRUNCATED

Secondary return code; the lua_data_length parameter was smaller than the actual length of data received on the message. Only lua_data_length bytes of data were returned to the verb; the remaining data was discarded. Additional parameters are also returned if this secondary return code is obtained.

LUA_NO_DATA

Secondary return code; lua_flag1.nowait was set to indicate immediate return without waiting for data, and no data was currently available on the specified session flow or flows.

LUA_INVALID_PROCESS

Secondary return code; the OS/2 process that issued this verb was not the same process that issued RUI_INIT for this session. Only the process that started a session can issue verbs on that session.

LUA_COMM_SUBSYSTEM_ABENDED

Primary return code; indicates one of the following conditions:

The node used by this conversation encountered an ABEND.

The connection between the TP and the PU 2.1 node has been broken (a LAN error).

The SnaBase at the TP’s computer encountered an ABEND.

LUA_SESSION_FAILURE

Primary return code; a required SNA Server component has terminated:

LUA_LU_COMPONENT_DISCONNECTED

Secondary return code; indicates that the LUA session has failed because of a problem with the link service or with the host LU.

LUA_RUI_LOGIC_ERROR

Secondary return code; an internal error was detected within LUA. This error should not occur during normal operation.

LUA_INVALID_VERB

Primary return code; either the verb code or the operation code, or both, is invalid. The verb did not execute.

LUA_STACK_TOO_SMALL

Primary return code; the stack size of the application is too small to execute the verb. Increase the stack size of your application.

LUA_COMM_SUBSYSTEM_NOT_LOADED

Primary return code; a required component could not be loaded or has terminated while processing the verb. Thus, communication could not take place. Contact the system administrator for corrective action.

LUA_UNEXPECTED_DOS_ERROR

Primary return code; after issuing an operating system call, an unexpected operating system return code was received and is specified in the secondary return code.

Remarks

RUI_INIT must have completed successfully before RUI_READ is issued.

While an existing RUI_READ is pending, you can issue another RUI_READ only if it specifies a different session flow or flows from pending RUI_READ verbs; that is, you cannot have more than one RUI_READ outstanding for the same session flow.

You can specify a particular message flow (LU normal, LU expedited, SSCP normal, or SSCP expedited) from which to read data, or you can specify more than one message flow. You can have multiple RUI_READ verbs outstanding, provided that no two of them specify the same flow.

Data is received by the application on one of four session flows. The four session flows, from highest to lowest priority are:

SSCP expedited

LU expedited

SSCP normal

LU normal

The data flow type that RUI_READ is to process is specified in the lua_flag1 parameter. The application can also specify whether it wants to look at more than one type of data flow. When multiple flow bits are set, the highest priority is received first. When RUI_READ completes processing, lua_flag2 indicates the specific type of flow for which data has been received by the Windows LUA application.

If RUI_BID successfully completes before an RUI_READ is issued, the Windows LUA interface can be instructed to reuse the last RUI_BID verb’s VCB. To do this, issue the RUI_READ with lua_flag1.bid_enable set.

The lua_flag1.bid_enable parameter can be used only if the following are true:

RUI_BID has already been issued successfully and has completed.

The storage allocated for RUI_BID has not been freed or modified.

No other RUI_BID is pending.

When using lua_flag1.bid_enable, the RUI_BID storage must not be freed since the last RUI_BID verb’s VCB is used. Also, when using lua_flag1.bid_enable, the successful completion of RUI_BID will be posted.

If RUI_READ is issued with lua_flag1.nowait when no data is available to receive, LUA_NO_DATA will be the secondary return code set by the Windows LUA interface.

If the data received is longer than lua_max_length, it is truncated; only lua_max_length bytes of data is returned. The primary return code LUA_UNSUCCESSFUL and the secondary return code LUA_DATA_TRUNCATED are also returned.

Once a message has been read using RUI_READ, it is removed from the incoming message queue and cannot be accessed again. (Note that RUI_BID can be used as a nondestructive read; that is, the application can use it to check the type of data available, but the data remains on the incoming queue and does not need to be used immediately.)

Pacing can be used on the primary-to-secondary half-session (this is specified in the host configuration), in order to protect the LUA application from being flooded with messages. If the LUA application is slow to read messages, SNA Server delays the sending of pacing responses to the host in order to slow it down.


RUI_TERM
LUA RUI Verbs	6 of 7

RUI_TERM

Ends both the LU session and the SSCP session for a given LUA LU.

Syntax

lua_opcode	unsigned short int

lua_prim_rc	unsigned short int

lua_sec_rc	unsigned long int

lua_verb	unsigned short int

lua_verb_length	unsigned short int

lua_luname	unsigned char

lua_sid	unsigned long int

lua_post_handle	unsigned long int

lua_correlator	unsigned long int

lua_flag2.async	struct member (unsigned) char

Parameters	Description

lua_opcode	Supplied parameter; LUA_OPCODE_RUI_TERM.

lua_verb	Supplied parameter; LUA_VERB_RUI.

lua_verb_length	Supplied parameter; specifies the length in bytes of the LUA VCB. It must contain the length of the verb being issued.

lua_luname	Supplied parameter; supplies the ASCII name for the local LU to be used for the Windows LUA session.

SLI_OPEN and RUI_INIT require this parameter. Other Windows LUA verbs only require this parameter if lua_sid is 0.

This parameter is 8 bytes long; pad on the right with spaces, X'20', if the name is shorter than 8 characters.

lua_sid	Supplied parameter; provides the session ID and is returned by SLI_OPEN and RUI_INIT. Other verbs use this parameter to identify the session used for the command. If other verbs use lua_luname to identify sessions, set lua_sid to 0.

lua_post_handle	Supplied parameter; for a Windows NT system, if asynchronous notification is to be accomplished by events, lua_post_handle contains the handle of the event to be signaled.

lua_correlator	Supplied parameter; a user-supplied value that links the verb with other user-supplied information. LUA does not use or change this information. This parameter is optional.

lua_flag2.async	Returned parameter; set to 1 if the LUA interface verb completed asynchronously.

Return Codes

LUA_OK

Primary return code; the verb executed successfully.

LUA_PARAMETER_CHECK

Primary return code; the verb did not execute because of a parameter error:

LUA_BAD_SESSION_ID

Secondary return code; an invalid value for lua_sid was specified in the VCB.

LUA_INVALID_POST_HANDLE

Secondary return code; for a Windows NT system, using events as the asynchronous posting method, the Windows LUA VCB does not contain a valid event handle.

For a Windows version 3.x system, the Windows LUA VCB does not contain the valid procedure address returned by the MakeProcInstance command.

For OS/2, the Windows LUA VCB does not contain a valid semaphore or queue handle, which is needed when the verb completes asynchronously.

LUA_RESERVED_FIELD_NOT_ZERO

Secondary return code; a reserved field in the verb record or a parameter not used by this verb was set to a nonzero value.

LUA_VERB_LENGTH_INVALID

Secondary return code; an LUA verb was issued with the value of lua_verb_length unexpected by the LUA.

LUA_STATE_CHECK

Primary return code; the verb did not execute because it was issued in an invalid state:

LUA_NO_RUI_SESSION

Secondary return code; RUI_INIT has not yet completed successfully for the LU name specified on RUI_TERM.

LUA_UNSUCCESSFUL

Primary return code; the verb record supplied was valid, but the verb did not complete successfully:

LUA_COMMAND_COUNT_ERROR

Secondary return code; RUI_TERM was already pending when the verb was issued.

LUA_INVALID_PROCESS

Secondary return code; the OS/2 process that issued this verb was not the same process that issued RUI_INIT for this session. Only the process that started a session can issue verbs on that session.

LUA_COMM_SUBSYSTEM_ABENDED

Primary return code; indicates one of the following conditions:

The node used by this conversation encountered an ABEND.

The connection between the TP and the PU 2.1 node has been broken (a LAN error).

The SnaBase at the TP’s computer encountered an ABEND.

LUA_SESSION_FAILURE

Primary return code; a required SNA Server component has terminated:

LUA_LU_COMPONENT_DISCONNECTED

Secondary return code; indicates that the LUA session has failed because of a problem with the link service or with the host LU.

LUA_RUI_LOGIC_ERROR

Secondary return code; an internal error was detected within LUA. This error should not occur during normal operation.

LUA_INVALID_VERB

Primary return code; either the verb code or the operation code, or both, is invalid. The verb did not execute.

LUA_STACK_TOO_SMALL

Primary return code; the stack size of the application is too small to execute the verb. Increase the stack size of your application.

LUA_COMM_SUBSYSTEM_NOT_LOADED

Primary return code; a required component could not be loaded or has terminated while processing the verb. Thus, communication could not take place. Contact the system administrator for corrective action.

LUA_UNEXPECTED_DOS_ERROR

Primary return code; after issuing an operating system call, an unexpected operating system return code was received and is specified in the secondary return code.

Remarks

This verb can be issued at any time after RUI_INIT has been issued (whether or not it has completed). If any other LUA verb is pending when RUI_TERM is issued, no further processing on the pending verb takes place, and it returns with a primary return code of LUA_CANCELED.

After this verb has completed, no other LUA verb can be issued for this session.


RUI_WRITE
LUA RUI Verbs	7 of 7

RUI_WRITE

Sends an SNA request or response unit from the LUA application to the host, over either the LU session or the SSCP session, and sends responses, SNA commands, and data from a Windows LUA application to the host LU.

Syntax

lua_opcode	unsigned short int

lua_prim_rc	unsigned short int

lua_sec_rc	unsigned long int

lua_verb	unsigned short in

lua_verb_length	unsigned short in

lua_luname	unsigned char

lua_sid	unsigned long int

lua_data_length	unsigned int

lua_data_ptr	char far *

lua_post_handle	unsigned long int

lua_th.snf	struct member (unsigned) char

lua_rh	struct (unsigned) char

lua_flag1.sscp_exp	struct member (unsigned) char

lua_flag1.sscp_norm	struct member (unsigned) char

lua_flag1.lu_exp	struct member (unsigned) char

lua_flag1.lu_norm	struct member (unsigned) char

lua_correlator	unsigned long int

lua_th	struct (unsigned) char

lua_flag2.async	struct member (unsigned) char

lua_flag2.sscp_exp	struct member (unsigned) char

lua_flag2.sscp_norm	struct member (unsigned) char

lua_flag2.lu_exp	struct member (unsigned) char

lua_flag2.lu_norm	struct member (unsigned) char

Parameters	Description

lua_opcode	Supplied parameter; LUA_OPCODE_RUI_WRITE.

lua_verb	Supplied parameter; LUA_VERB_RUI.

lua_verb_length	Supplied parameter; specifies the length, in bytes, of the LUA VCB. It must contain the length of the verb being issued.

lua_luname	Supplied parameter; specifies the ASCII name of the local LU used by the Windows LUA session.

SLI_OPEN and RUI_INIT require this parameter. Other Windows LUA verbs require this parameter if lua_sid is 0.

This parameter is 8 bytes long; pad on the right with spaces, X'20', if the name is shorter than 8 characters.

lua_sid	Supplied/returned parameter; specifies the session ID and is returned by SLI_OPEN and RUI_INIT. Other verbs use this parameter to identify the session used for the command. If other verbs use lua_luname to identify sessions, set lua_sid to 0.

lua_data_length	Supplied parameter; specifies the length of the data being sent or received.

lua_data_ptr	Supplied parameter; points to the application data buffer. Both SNA commands and data are placed in this buffer and they can be in an EBCDIC format.

When SLI_RECEIVE or RUI_READ is issued, this parameter points to the location to receive the data from the host.

When SLI_SEND or RUI_WRITE is issued, this parameter points to the location of the application’s data to be sent to the host.

When SLI_PURGE or RUI_PURGE is issued, this parameter points to the location of the SLI_RECEIVE or RUI_READ verb’s VCB that is to be canceled.

When SLI_OPEN is issued, this parameter can be one of the following:

   The LOGON message for the SSCP normal flow when the initialization type is secondary with an unformatted LOGON message.

   The RU for INITSELF. When the initialization type is secondary with INITSELF, the necessary data for the application is provided.

   For all other open types, this field should be set to 0.

This information is provided by the Windows LUA application.

lua_post_handle	Supplied parameter; for the Windows NT system, if asynchronous notification is to be accomplished by events, lua_post_handle contains the handle of the event to be signaled.

lua_th.snf	Supplied parameter; contains the RU sequence number in the fifth and sixth bytes of lua_th.

lua_rh	Supplied/returned parameter; provides the SNA RH for the message. It is set for RUI_WRITE and returned by RUI_READ and RUI_BID. For the RH for RUI_WRITE, all fields except the queued-response indicator (lua_rh.qri) and pacing indicator (lua_rh.pi) are used. For a list of bit masks that apply to this parameter, see Appendix B, “Verb Control Block.”

lua_flag1	Supplied parameter; set one of the following flags to 1 to indicate  on which message flow the data is to be sent:

   lua_flag1.sscp_exp

   lua_flag1.sscp_norm

   lua_flag1.lu_exp

   lua_flag1.lu_norm

lua_correlator	Supplied parameter; a user-supplied value that links the verb with other user-supplied information. LUA does not use or change this information. This parameter is optional.

lua_th	Returned parameter; contains the SNA TH of the message sent or received. Various subparameters are to be set for RUI_WRITE and returned for RUI_READ. For a list of subparameters that apply to this parameter, see Appendix B, “Verb Control Block.”

lua_flag2	Returned parameter.

Set lua_flag2.async to 1 if the LUA interface verb completed asynchronously.

The lua_flag2 parameter contains flags for messages returned by LUA. One or more of the following flags are set to 1 to indicate on which message flow the data was received:

   lua_flag2.sscp_exp — returned parameter; flag indicates 	SSCP expedited flow.

   lua_flag2.sscp_norm — returned parameter; flag indicates 	SSCP normal flow.

   lua_flag2.lu_exp — returned parameter; flag indicates LU expedited flow.

   lua_flag2.lu_norm —returned  parameter; flag indicates LU normal flow

Return Codes

LUA_OK

Primary return code; the verb executed successfully.

LUA_CANCELED

Primary return code; the verb did not complete successfully because it was canceled by another verb:

LUA_TERMINATED

Secondary return code; the verb was canceled because RUI_TERM was issued for this session.

LUA_PARAMETER_CHECK

Primary return code; the verb did not execute because of a parameter error:

LUA_BAD_DATA_PTR

Secondary return code; the data_ptr parameter contained an invalid value.

LUA_BAD_SESSION_ID

Secondary return code; an invalid value for lua_sid was specified in the VCB.

LUA_DUPLICATE_WRITE_FLOW

Secondary return code; RUI_WRITE was already outstanding for the session flow specified on this verb (the session flow is specified by setting one of the lua_flag1 flow flags to 1). Only one RUI_WRITE at a time can be outstanding on each session flow.

LUA_INVALID_FLOW

Secondary return code; the lua_flag1.sscp_exp flow flag was set, indicating that the message should be sent on the SSCP expedited flow. LUA does not allow applications to send data on this flow.

LUA_INVALID_POST_HANDLE

Secondary return code; for a Windows NT system using events as the asynchronous posting method, the Windows LUA VCB does not contain a valid event handle.

For the Windows version 3.x system, the Windows LUA VCB does not contain the valid procedure address returned by the MakeProcInstance command.

For OS/2, the Windows LUA VCB does not contain a valid semaphore or queue handle, which is needed when the verb completes asynchronously.

LUA_MULTIPLE_WRITE_FLOWS

Secondary return code; more than one of the lua_flag1 flow flags was set to 1. One and only one of these flags must be set to 1, to indicate which session flow the data is to be sent on.

LUA_REQUIRED_FIELD_MISSING

Secondary return code; indicates one of the following cases:

None of the lua_flag1 flow flags was set. One and only one of these flags must be set to 1.

RUI_WRITE was used to send a response, and the response required more data than was supplied.

LUA_RESERVED_FIELD_NOT_ZERO

Secondary return code; a reserved field in the verb record or a parameter not used by this verb was set to a nonzero value.

LUA_VERB_LENGTH_INVALID

Secondary return code; an LUA verb was issued with the value of lua_verb_length unexpected by the LUA.

LUA_STATE_CHECK

Primary return code; the verb did not execute because it was issued in an invalid state:

LUA_MODE_INCONSISTENCY

Secondary return code; the SNA message sent on RUI_WRITE was not valid at this time. This is caused by trying to send data on the LU session before the session is bound. Check the sequence of SNA messages sent.

LUA_NO_RUI_SESSION

Secondary return code; RUI_INIT has not yet completed successfully for the LU name specified on this verb.

LUA_UNSUCCESSFUL

Primary return code; the verb record supplied was valid, but the verb did not complete successfully:

LUA_FUNCTION_NOT_SUPPORTED

Secondary return code; indicates one of the following cases:

The lua_rh.fi bit (format indicator) was set to 1, but the first byte of the supplied RU was not a recognized request code.

The lua_rh.ruc parameter (RU category) specified the network control (NC) category; LUA does not allow applications to send requests in this category.

LUA_INVALID_PROCESS

Secondary return code; the OS/2 process that issued this verb was not the same process that issued RUI_INIT for this session. Only the process that started a session can issue verbs on that session.

LUA_INVALID_SESSION_PARAMETERS

Secondary return code; the application used RUI_WRITE to send a positive response to a BIND message received from the host. However, SNA Server cannot accept the BIND parameters as specified, and has sent a negative response to the host. See Chapter 2, “Writing LUA Applications,” for more information on the BIND profiles accepted by SNA Server.

LUA_RSP_CORRELATION_ERROR

Secondary return code; when using RUI_WRITE to send a response, lua_th.snf (which indicates the sequence number of the received message being responded to) did not contain a valid value.

LUA_RU_LENGTH_ERROR

Secondary return code; the lua_data_length parameter contained an invalid value. When sending data on the LU normal flow, the maximum length is as specified in the BIND received from the host; for all other flows the maximum length is 256 bytes.

Note

Any other secondary return code is an SNA sense code indicating that the supplied SNA data was invalid or could not be sent. See Chapter 2, “Writing LUA Applications,” for information on interpreting the SNA sense codes that can be returned.

LUA_COMM_SUBSYSTEM_ABENDED

Primary return code; indicates one of the following conditions:

The node used by this conversation encountered an ABEND.

The connection between the TP and the PU 2.1 node has been broken (a LAN error).

The SnaBase at the TP’s computer encountered an ABEND.

LUA_SESSION_FAILURE

Primary return code; a required SNA Server component has terminated:

LUA_LU_COMPONENT_DISCONNECTED

Secondary return code; indicates that the LUA session has failed because of a problem with the link service or with the host LU.

LUA_RUI_LOGIC_ERROR

Secondary return code; an internal error was detected within LUA. This error should not occur during normal operation.

LUA_INVALID_VERB

Primary return code; either the verb code or the operation code, or both, is invalid. The verb did not execute.

LUA_STACK_TOO_SMALL

Primary return code; the stack size of the application is too small to execute the verb. Increase the stack size of your application.

LUA_COMM_SUBSYSTEM_NOT_LOADED

Primary return code; a required component could not be loaded or has terminated while processing the verb. Thus, communication could not take place. Contact the system administrator for corrective action.

LUA_UNEXPECTED_DOS_ERROR

Primary return code; after issuing an operating system call, an unexpected operating system return code was received and is specified in the secondary return code.

Remarks

RUI_INIT must be issued successfully before this verb is issued.

When sending an SNA request, all applicable values in the lua_rh must be set. Chaining and bracketing are the responsibility of the application.

When sending a response, the type of response determines the RUI_WRITE information required. For all responses, you must:

Set the selected lua_rh.rri flag to 1.

Provide the sequence number in lua_th.snf for the request to which you are responding.

For multichain message responses, the sequence number of the last received chain element must be used. For a response to a multichain message ending with a CANCEL command, the CANCEL command sequence number is used.

For positive responses that only require the request code, set lua_rh.ri to 0 (indicating that the response is positive) and lua_data_length to 0 (indicating that no data is provided). The request code is filled in by the RUI, using the sequence number provided.

For negative responses, set lua_rh.ri to 1, lua_data_ptr to the SNA sense code address, and lua_data_length to the SNA sense code length (4 bytes). The sequence number is used by the RUI to fill in the request code.

For positive responses to the BIND and STSN commands which require data in the responses, set lua_data_ptr to point to the response and set lua_data_length to the length of the data provided in lua_data_ptr.

While an existing RUI_WRITE is pending, you can issue a second RUI_WRITE only if it specifies a different session flow from the pending RUI_WRITE. That is, you cannot have more than one RUI_WRITE outstanding for the same session flow.

RUI_WRITE can be issued on the SSCP normal flow at any time after a successful RUI_INIT. RUI_WRITE verbs on the LU expedited or LU normal flows are permitted only after a BIND has been received, and must abide by the protocols specified on the BIND.

Note that successful completion of RUI_WRITE indicates that the message was queued successfully to the data link; it does not necessarily indicate that the message was sent successfully, or that the host accepted it.

Pacing may be used on the secondary-to-primary half-session (specified on the BIND), in order to prevent the LUA application from sending more data than the local or remote LU can handle. If this is the case, an RUI_WRITE on the LU normal flow may be delayed by LUA and may take some time to complete.


LUA SLI Verbs
Chapter 4	1 of 9

LUA SLI Verbs

This chapter describes the LUA SLI verbs. It provides the following information for each SLI verb:

Details of the LUA verb control block structure for all SLI verbs.

A description of each SLI verb and its purpose.

Parameters (VCB fields) supplied to and returned by LUA. The description of each parameter includes information on the valid values for that parameter.

Interaction with other verbs.

There are six SLI verbs and two user-defined routines. They are as follows:

SLI_BID

Notifies the SLI application that a message is waiting to be read using SLI_RECEIVE and provides the current status of the session to the Windows LUA application.

SLI_CLOSE

Ends a session opened with SLI_OPEN.

SLI_OPEN

Transfers control of the specified LU to the Windows LUA application and establishes a session between the SSCP and the specified LU, as well as an LU-LU session.

SLI_PURGE

Cancels SLI_RECEIVE verbs issued with a wait condition.

SLI_RECEIVE

Receives responses, SNA commands, and data into the buffer of a Windows LUA application. SLI_RECEIVE also provides the current status of the session to the Windows LUA application.

SLI_SEND

Sends responses, SNA commands, and data from a Windows LUA application to a host LU.

SLI_BIND_ROUTINE

Notifies the Windows LUA application that a BIND request has come from the host and allows the user-supplied routine to examine the request and formulate a response.

SLI_STSN_ROUTINE

Notifies the Windows LUA application that an STSN command has come from the host and allows the user-supplied routine to examine the request and formulate a response.

Cryptography is not defined as part of the Windows LUA standard.

For information about the LUA RUI verbs, see Chapter 3, “LUA RUI Verbs.”


SLI_BID
LUA SLI Verbs	2 of 9

SLI_BID

Notifies the SLI application that a message is waiting to be read using SLI_RECEIVE. SLI_BID also provides the current status of the session to the Windows LUA application.

Syntax

lua_verb	unsigned short int

lua_verb_length	unsigned short int

lua_opcode	unsigned short int

lua_correlator	unsigned long int

lua_luname	unsigned char

lua_sid	unsigned long int

lua_post_handle	unsigned long int

lua_prim_rc	unsigned short int

lua_sec_rc	unsigned long int

lua_data_length	unsigned long int

lua_peek_data	unsigned char (up to 12 bytes)

lua_th	struct (unsigned char)

lua_rh	struct (unsigned char)

lua_message_type	unsigned char

lua_flag2	struct (unsigned char)

Parameter	Description

lua_verb	Supplied parameter; LUA_VERB_SLI.

lua_verb_length	Supplied parameter; specifies the length, in bytes, of the LUA VCB. It must contain the length of the verb being issued.

lua_opcode	Supplied parameter; LUA_OPCODE_SLI_BID.

lua_correlator	Supplied parameter; a user-supplied value that links the verb with other user-supplied information. This parameter is neither examined nor modified by the Windows LUA interface.

lua_luname	Supplied parameter; specifies the ASCII name of the local LU used by the Windows LUA session.

SLI_OPEN and RUI_INIT require this parameter. Other verbs require this parameter only if lua_sid is 0.

This parameter is 8 bytes long; pad on the right with spaces, X'20', if the name is shorter than 8 characters.

lua_sid	Supplied/returned parameter; specifies the session ID and is returned by SLI_OPEN and RUI_INIT. Other verbs use this parameter to identify the session used for the command. If other verbs use lua_luname to identify sessions, set lua_sid to 0.

lua_post_handle	Supplied parameter; for the Windows NT system, if asynchronous notification is to be accomplished via events, lua_post_handle contains the handle of the event to be signaled.

For all other environments, this parameter is reserved and should be set to 0.

lua_data_length	Returned parameter; specifies the length of the data being sent or received.

lua_peek_data	Returned parameter; supplies a preview (up to 12 bytes) of the RU data waiting to be read. The lua_data_length parameter contains the exact length of the data peeked.

lua_th	Returned parameter; supplies the information from the SNA TH of the received message. Various subparameters are to be set for write functions and returned for read functions. See Appendix B, “Verb Control Block,” for a listing of the subparameters associated with this parameter.

lua_rh	Returned parameter; supplies the information from the SNA RH of the received message. It is set for the write function and returned by the read and bid functions. See Appendix B, “Verb Control Block,” for a listing of the bit masks for this parameter.

lua_message_type	Returned parameter; supplies the type of SNA data or command received from the host. The following are possible values:

LUA_MESSAGE_TYPE_LU_DATA

LUA_MESSAGE_TYPE_SSCP_DATA

LUA_MESSAGE_TYPE_RSP

LUA_MESSAGE_TYPE_BID

LUA_MESSAGE_TYPE_BIND

LUA_MESSAGE_TYPE_BIS

LUA_MESSAGE_TYPE_CANCEL

LUA_MESSAGE_TYPE_CHASE

LUA_MESSAGE_TYPE_LUSTAT_LU

LUA_MESSAGE_TYPE_LUSTAT_SSCP

LUA_MESSAGE_TYPE_QC

LUA_MESSAGE_TYPE_QEC

LUA_MESSAGE_TYPE_RELQ

LUA_MESSAGE_TYPE_RTR

LUA_MESSAGE_TYPE_SBI

LUA_MESSAGE_TYPE_SIGNAL

LUA_MESSAGE_TYPE_STSN

The SLI receives and responds to the BIND and STSN requests through the LUA interface extension routines.

LU_DATA, LUSTAT_LU, LUSTAT_SSCP, and SSCP_DATA are not SNA commands.

lua_flag2	Returned parameter; contains bits used as output flags. When the verb is initiated, the parameter should be 0. When the verb completes, bits with no specified value are reserved and set to 0. The following list gives the bit mask for bits that indicate the processed message session and flow:

   lua_flag2.sscp_exp

   lua_flag2.sscp_norm

   lua_flag2.lu_exp

   lua_flag2.lu_norm

Return Codes

LUA_OK

Primary return code; the verb executed successfully:

LUA_SEC_OK

Secondary return code; no additional information exists for LUA_OK.

LUA_PARAMETER_CHECK

Primary return code; the verb did not execute because of a parameter error:

LUA_INVALID_LUNAME

Secondary return code; an invalid lua_luname name was specified.

LUA_BAD_SESSION_ID

Secondary return code; an invalid value for lua_sid was specified in the VCB.

LUA_RESERVED_FIELD_NOT_ZERO

Secondary return code; a reserved parameter for the verb just issued is not set to 0.

LUA_INVALID_POST_HANDLE

Secondary return code; for a Windows NT system using events as the asynchronous posting method, the Windows LUA VCB does not contain a valid event handle.

For the Windows version 3.x system, the LUA VCB does not contain the valid procedure address returned by the MakeProcInstance command.

For OS/2, the LUA VCB does not contain a valid semaphore or queue handle, which is needed when a verb completes asynchronously.

LUA_VERB_LENGTH_INVALID

Secondary return code; an LUA verb was issued with the value of lua_verb_length unexpected by the LUA.

LUA_STATE_CHECK

Primary return code; the verb did not execute because it was issued in an invalid state:

LUA_NO_SLI_SESSION

Secondary return code; a session was not open or was down due to an SLI_CLOSE or session failure when a command was issued.

LUA_SLI_BID_PENDING

Secondary return code; an SLI verb was still active when another SLI_BID was issued. Only one SLI_BID can be active at a time.

LUA_SESSION_FAILURE

Primary return code; an error condition, specified in the secondary return code, caused the session to fail:

LUA_RECEIVED_UNBIND

Secondary return code; the primary LU sent an SNA UNBIND command to the LUA interface when a session was active. As a result, the session was stopped.

LUA_SLI_LOGIC_ERROR

Secondary return code; the LUA interface found an internal error in logic.

LUA_NO_RUI_SESSION

Secondary return code; no session has been initialized for the LUA verb issued, or some verb other than SLI_OPEN was issued before the session was initialized.

LUA_MODE_INCONSISTENCY

Secondary return code; performing this function is not allowed by the current status. The request sent to the half-session component was not executed even though it was understood and supported. This SNA sense code is also an exception request sense code.

LUA_RECEIVER_IN_TRANSMIT_MODE

Secondary return code; either resources needed to handle normal flow data were not available or the state of the half-duplex contention was not received when a normal-flow request was received. The result is a race condition. This SNA sense code is also an exception request sense code.

LUA_LU_COMPONENT_DISCONNECTED

Secondary return code; an LU component is unavailable because it is not connected properly. Make sure that the power is on.

LUA_FUNCTION_NOT_SUPPORTED

Secondary return code; LUA does not support the requested function. A control character, an RU parameter, or a formatted request code may have specified the function. Specific sense code information is in bytes 2 and 3.

LUA_CHAINING_ERROR

Secondary return code; the sequence of the chain indicator settings is in error. An invalid request header or request unit for the receiver’s current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_BRACKET

Secondary return code; the sender failed to enforce the session bracket rules. Note that contention and race conditions are exempt from this error. An invalid request header or request unit for the receiver’s current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_DIRECTION

Secondary return code; while the half-duplex flip-flop state was NOT_RECEIVE, a request for normal flow was received. An invalid request header or request unit for the receiver’s current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_DATA_TRAFFIC_QUIESCED

Secondary return code; a DFC or FMD request was received from a half-session that sent either a SHUTC command or QC command, and the DFC or FMD request has not responded to a RELQ command. An invalid request header or request unit for the receiver’s current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_NO_BEGIN_BRACKET

Secondary return code; the receiver has already sent a positive response to a BIS command when a BID or an FMD request specifying BBI=BB was received. An invalid request header or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_IMMEDIATE_REQUEST_MODE_ERROR

Secondary return code; the request violated the immediate request mode protocol. An invalid header request or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_QUEUED_RESPONSE_ERROR

Secondary return code; the request violated the queued response protocol. An invalid header request or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_ERP_SYNC_EVENT_ERROR

Secondary return code; a violation of the ERP synchronous event protocol occurred. An invalid header request or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_RSP_CORRELATION_ERROR

Secondary return code; a response was sent that does not correspond to a previously received request or a response was received that does not correspond to a previously sent request.

LUA_RSP_PROTOCOL_ERROR

Secondary return code; a violation of the response protocol was found in the response received from the primary half-session.

LUA_BB_NOT_ALLOWED

Secondary return code; the begin bracket indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_EB_NOT ALLOWED

Secondary return code; the end bracket indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_EXCEPTION_RSP_NOT_ALLOWED

Secondary return code; when an exception response was not allowed, one was requested. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_DEFINITE_RSP_NOT_ALLOWED

Secondary return code; when a definite response was not allowed, one was requested. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_CD_NOT_ALLOWED

Secondary return code; the change-direction indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_NO_RESPONSE_NOT_ALLOWED

Secondary return code; a request other than an EXR contained a “no response.” The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_CHAINING_NOT_SUPPORTED

Secondary return code; the chaining indicators were incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_BRACKETS_NOT_SUPPORTED

Secondary return code; the bracket indicators were incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_CD_NOT_SUPPORTED

Secondary return code; the change-direction indicator was set, but LUA does not support change-direction for this situation. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_USE_OF_FI

Secondary return code; the format indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_ALTERNATE_CODE_NOT_SUPPORTED

Secondary return code; the code selection indicator was set, but LUA does not support code selection for this session. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_RU_CATEGORY

Secondary return code; the request unit category indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_REQUEST_CODE

Secondary return code; the request code was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_SPEC_OF_SDI_RTI

Secondary return code; the sense-data-included indicator (SDI) and the response-type-indicator (RTI) were not specified correctly on a response. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_DR1I_DR2I-ERI

Secondary return code; the definite response 1 indicator (DR1I), the definite response 2 indicator (DR2I), and the exception response indicator (ERI) were specified incorrectly. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_USE_OF QRI

Secondary return code; the queued response indicator (QRI) was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_USE_OF_EDI

Secondary return code; the enciphered data indicator (EDI) was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_USE_OF_PDI

Secondary return code; the padded data indicator (PDI) was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_UNSUCCESSFUL

Primary return code; the verb record supplied was valid, but the verb did not complete successfully:

LUA_VERB_RECORD_SPANS_SEGMENTS

Secondary return code; the LUA VCB length parameter plus the segment offset is beyond the segment end.

LUA_NOT_ACTIVE

Secondary return code; LUA was not active within SNA Server when an LUA verb was issued.

LUA_INVALID_PROCESS

Secondary return code; the session for which an LUA verb was issued is unavailable because another process owns the session.

LUA_LU_INOPERATIVE

Secondary return code; a severe error occurred while attempting to stop the session. This LU is unavailable for any LUA requests until an ACTLU is received from the host.

LUA_RECEIVE_CORRELATION_TABLE_FULL

Secondary return code; the session receive correlation table for the flow requested reached its capacity.

LUA_NEGATIVE_RESPONSE

Primary return code; either LUA sent a negative response to a message received from the primary LU because an error was found in the message, or the application responded negatively to a chain for which the end-of-chain has arrived.

LUA_FUNCTION_NOT_SUPPORTED

Secondary return code; the LUA does not support the requested function. A control character, an RU parameter, or a formatted request code may have specified the function. Specific sense code information is in bytes 2 and 3.

LUA_DATA_TRAFFIC_RESET

Secondary return code; a half-session of an active session but with inactive data traffic received a normal flow DFC or FMD request. An invalid request header or request unit for the receiver’s current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_DATA_TRAFFIC_NOT_RESET

Secondary return code; while the data traffic state was not reset, the session control request was received. An invalid request header or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_SC_PROTOCOL_VIOLATION

Secondary return code; a violation of the session control (SC) protocol occurred. A request (that is permitted only after an SC request and a positive response to that request have been successfully exchanged) was received before the required exchange. Byte 4 of the sense data contains the request code. No user data exists for this sense code. An invalid header request or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_INVALID_SC_OR_NC_RH

Secondary return code; the RH of an SC or NC request was invalid.

LUA_PACING_NOT_SUPPORTED

Secondary return code; the request contained a pacing indicator when support of pacing for this session does not exist for the receiving half-session or boundary function half-session. The BIND options chosen previously or the architectural rules were violated by lua_rh values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_NAU_INOPERATIVE

Secondary return code; the network addressable unit (NAU) is not able to process responses or requests. Delivery to the receiver could not take place for one of the following reasons:

A path information unit error

A path outage

An invalid sequence of requests for activation

If a path error is received during an active session, that usually means there is no longer a valid path to the session partner.

LUA_CANCELED

Primary return code; the secondary return code gives the reason for canceling the command:

LUA_TERMINATED

Secondary return code; the session was terminated when a verb was pending. The verb process has been canceled.

LUA_IN_PROGRESS

Primary return code; an asynchronous command was received but is not completed.

LUA_STATUS

Primary return code; the secondary return code contains SLI status information for the application:

LUA_READY

Secondary return code; following a NOT_READY status, this status is issued to notify you that the SLI is ready to process commands.

LUA_NOT_READY

Secondary return code; an SNA UNBIND type X'02' command was received, which means a new BIND is coming.

If the UNBIND type X'02' is received after the beginning SLI_OPEN is complete, the session is suspended until a BIND, optional CRV and STSN, and SDT flows are received. These routines are re-entrant because they have to be called again. The session resumes after the SLI processes the SDT command.

If the UNBIND type X'02' is received while SLI_OPEN is still processing, the primary return code is session-failure, not status. Or, the receipt of an SNA CLEAR caused the suspension. Receipt of an SNA SDT will cause the session to resume.

LUA_INIT_COMPLETE

Secondary return code; the LUA interface initialized the session while SLI_OPEN was processing. LUA applications that issue SLI_OPEN with the lua_open_type_prim_sscp parameter receive this status on SLI_RECEIVE or SLI_BID.

LUA_SESSION_END_REQUESTED

Secondary return code; the LUA interface received an SNA shutdown command (SHUTD) from the host, which means the host is ready to shut down the session.

LUA_COMM_SUBSYSTEM_ABENDED

Primary return code; indicates one of the following conditions:

The node used by this conversation encountered an ABEND.

The connection between the TP and the PU 2.1 node has been broken (a LAN error).

The SnaBase at the TP’s computer encountered an ABEND.

LUA_COMM_SUBSYSTEM_NOT_LOADED

Primary return code; a required component could not be loaded or has terminated while processing the verb. Thus, communication could not take place. Contact the system administrator for corrective action.

LUA_INVALID_VERB_SEGMENT

Primary return code; the VCB extended beyond the end of the data segment.

LUA_UNEXPECTED_DOS_ERROR

Primary return code; after issuing an operating system call, an unexpected operating system return code was received and is specified in the secondary return code.

LUA_STACK_TOO_SMALL

Primary return code; the stack size of the application is too small to execute the verb. Increase the stack size of your application.

LUA_INVALID_VERB

Primary return code; either the verb code or the operation code, or both, is invalid. The verb did not execute.

Remarks

SLI_BID:

Notifies a Windows LUA application that a message is waiting to be read.

Provides the current session status.

Provides a preview of the next message that will be read by SLI_RECEIVE.

This preview contains a maximum of 12 bytes of information (peek data) that enables the Windows LUA application to define its processing strategy for the data.

To use SLI_BID within a Windows LUA application, issue SLI_BID. When the verb completes, it may be reactivated in the following two ways:

Reissue SLI_BID.

Issue SLI_RECEIVE with lua_flag1_bid_enable set to 1. This issues an SLI_BID that uses the most recently accepted address for the VCB and establishes the active bid.

Each session can have only one SLI_BID at a time.

If multiple messages are available when a Windows LUA application issues SLI_BID, the data flow with the highest priority is returned. The order in which the data can be returned is as follows:

SSCP expedited

LU expedited

SSCP normal

LU normal

If SLI_RECEIVE has flags set to read more than one type of message flow, the data actually returned by SLI_BID might be for a flow different than the one for which you actually receive data via SLI_RECEIVE. This situation occurs when higher priority data arrives from the host after SLI_BID completes processing, but before SLI_RECEIVE is issued.

To ensure that SLI_RECEIVE reads the data, the SLI_BID returned specifies the flow that matches lua_flag2 returned by the completed SLI_BID.

Session Status Return Codes

If LUA_STATUS is the primary return code, the secondary return code may be LUA_READY, LUA_NOT_READY, LUA_SESSION_END_REQUESTED, or LUA_INIT_COMPLETE. In addition, if LUA_STATUS is the primary return code, the following parameters are used:

lua_sec_rc

lua_sid

LUA_READY is returned after LUA_NOT_READY status and indicates that the SLI is again ready to perform all commands.

LUA_NOT_READY indicates that the SLI session is suspended because the SLI has received either an SNA CLEAR command or an SNA UNBIND command with an X'02' UNBIND type (UNBIND with BIND forthcoming). Depending on what caused the suspension, the session can be reactivated as follows:

When the suspension is caused by an SNA CLEAR, receiving an SNA SDT reactivates the session.

When an SNA UNBIND type BIND forthcoming causes suspension of the session and the SLI_OPEN that opened the session is completed, the session is suspended until the SLI receives a BIND and SDT command. The session can also optionally receive an STSN command. As a result, user-supplied routines issued with the initial SLI_OPEN must be re-entered because they will be recalled.

The application can send SSCP data after a CLEAR or UNBIND type BIND forthcoming arrives and before the NOT READY status is read. The application can send and receive SSCP data after reading a NOT READY.

When an SNA UNBIND type BIND forthcoming arrives before completion of the SLI_OPEN that opened the session, LUA_SESSION_FAILURE (not LUA_STATUS) is the primary return code.

LUA_SESSION_END_REQUESTED indicates that the application received an SNA SHUTD from the host. The Windows LUA application should issue SLI_CLOSE to close the session when convenient.

LUA_INIT_COMPLETE is returned only when lua_init_type for SLI_OPEN is LUA_INIT_TYPE_PRIM_SSCP. The status means that SLI_OPEN has been processed sufficiently to allow SSCP data to now be sent or received.

Exception Requests

If a host application request unit is converted into an EXR, sense data will be returned. When an SLI_BID completes with the following returned verb parameters set as shown, an EXR conversion occurs:

Parameter	Set to

lua_prim_rc	OK (X'0000')

lua_sec_rc	OK (X'00000000')

lua_rh.rri	bit off (request unit)

lua_rh.sdi	bit on (includes sense data)

Of the seven bytes of data in lua_peek_data, bytes 0 through 3 define the error detected. The following table indicates possible sense data and the values of bytes 0 through 3.

Sense data	Value of bytes 0 - 3
LUA_MODE_INCONSISTENCY	X08090000
LUA_BRACKET_RACE_ERROR	X080B0000
LUA_BB_REJECT_NO_RTR	X08130000
LUA_RECEIVER_IN_TRANSMIT_MODE	X081B0000
LUA_CRYPTOGRAPHY_FUNCTION_INOP	X08480000
LUA_SYNC_EVENT_RESPONSE	X10010000
LUA_RU_DATA_ERROR	X10020000
LUA_RU_LENGTH_ERROR	X10020000
LUA_INCORRECT_SEQUENCE_NUMBER	X20010000
The information returned to bytes 3 through 6 in lua_peek_data is determined by the first 3 bytes of the initial request unit that caused the error.


SLI_CLOSE
LUA SLI Verbs	3 of 9

SLI_CLOSE

Ends a session opened with SLI_OPEN. The LU-LU and LU-SSCP resources are released.

Syntax

lua_verb	unsigned short int

lua_verb_length	unsigned short int

lua_opcode	unsigned short int

lua_correlator	unsigned long int

lua_luname	unsigned char

lua_sid	unsigned long int

lua_post_handle	unsigned long int

lua_flag1.close_abend	struct (unsigned char)

lua_prim_rc	unsigned short int

lua_sec_rc	unsigned long int

lua_flag2.async	struct (unsigned char)

Parameter	Description

lua_verb	Supplied parameter; LUA_VERB_SLI.

lua_verb_length	Supplied parameter; specifies the length, in bytes, of the LUA VCB. It must contain the length of the verb being issued.

lua_opcode	Supplied parameter; LUA_OPCODE_SLI_CLOSE.

lua_correlator	Supplied parameter; a user-supplied value that links the verb with other user-supplied information. This parameter is neither examined nor modified by the Windows LUA interface.

lua_luname	Supplied parameter; specifies the ASCII name of the local LU used by the Windows LUA session.

SLI_OPEN and RUI_INIT require this parameter. Other verbs require this parameter if lua_sid is 0.

This parameter is 8 bytes long; pad on the right with spaces, X'20', if the name is shorter than 8 characters.

lua_sid	Supplied parameter; specifies the session ID and is returned by SLI_OPEN and RUI_INIT. Other verbs use this parameter to identify the session used for the command. If other verbs use lua_luname to identify sessions, set lua_sid to 0.

lua_post_handle	Supplied parameter; for the Windows NT system, if asynchronous notification is to be accomplished by events, lua_post_handle contains the handle of the event to be signaled.

lua_flag1.close_abend	Supplied parameter; used by SLI_CLOSE to specify whether the session is to be closed immediately (ON) or closed normally (OFF). For verbs other than SLI_CLOSE, this flag must be off.

lua_flag2.async	Returned parameter; set to 1 if the LUA interface verb completed asynchronously.

Return Codes

LUA_OK

Primary return code; the verb executed successfully:

LUA_SEC_OK

Secondary return code; no additional information exists for LUA_OK.

LUA_PARAMETER_CHECK

Primary return code; the verb did not execute because of a parameter error:

LUA_INVALID_LUNAME

Secondary return code; an invalid lua_luname was specified.

LUA_BAD_SESSION_ID

Secondary return code; an invalid value for lua_sid was specified in the VCB.

LUA_RESERVED_FIELD_NOT_ZERO

Secondary return code; a reserved parameter for the verb just issued is not set to 0.

LUA_INVALID_POST_HANDLE

Secondary return code; for a Windows NT system using events as the asynchronous posting method, the Windows LUA VCB does not contain a valid event handle.

For the Windows version 3.x system, the LUA VCB does not contain the valid procedure address returned by the MakeProcInstance command.

For OS/2, the LUA VCB does not contain a valid semaphore or queue handle, which is needed when a verb completes asynchronously.

LUA_VERB_LENGTH_INVALID

Secondary return code; an LUA verb was issued with a value for lua_verb_length unexpected by the LUA.

LUA_STATE_CHECK

Primary return code; the verb did not execute because it was issued in an invalid state:

LUA_NO_SLI_SESSION

Secondary return code; a session was not open or was down due to an SLI_CLOSE or session failure when a command was issued.

LUA_CLOSE_PENDING

Secondary return code; one of the following has occurred:

A CLOSE_ABEND was still pending when another CLOSE_ABEND was issued. You can issue a CLOSE_ABEND if a CLOSE_NORMAL is pending.

Either a CLOSE_ABEND or a CLOSE_NORMAL was still pending when a CLOSE_NORMAL was issued.

LUA_SESSION_FAILURE

Primary return code; an error condition, specified in the secondary return code, caused the session to fail:

LUA_NOT_ACTIVE

Secondary return code; LUA was not active within SNA Server when an LUA verb was issued.

LUA_UNEXPECTED_SNA_SEQUENCE

Secondary return code; unexpected data or commands were received from the host while SLI_OPEN was processing.

LUA_NEGATIVE_RSP_CHASE

Secondary return code; a negative response to an SNA CHASE command from the host was received by the LUA interface while SLI_CLOSE was being processed. SLI_CLOSE continued processing to stop the session.

LUA_NEGATIVE_RSP_SHUTC

Secondary return code; a negative response to an SNA SHUTC command from the host was received by the SLI while SLI_CLOSE was still being processed. SLI_CLOSE continued processing to stop the session.

LUA_NEGATIVE_RSP_SHUTD

Secondary return code; a negative response to an SNA RSHUTD command from the host was received by the LUA interface while SLI_CLOSE was still being processed. SLI_CLOSE continued processing to stop the session.

LUA_RECEIVED_UNBIND

Secondary return code; the primary LU sent an SNA UNBIND command to the LUA interface when a session was active. As a result, the session was stopped.

LUA_NO_RUI_SESSION

Secondary return code; no session has been initialized for the LUA verb issued, or some verb other than SLI_OPEN was issued before the session was initialized.

LUA_LU_COMPONENT_DISCONNECTED

Secondary return code; an LU component is unavailable because it is not connected properly. Make sure that the power is on.

LUA_IN_PROGRESS

Primary return code; an asynchronous command was received but is not completed.

LUA_COMM_SUBSYSTEM_ABENDED

Primary return code; indicates one of the following conditions:

The node used by this conversation encountered an ABEND.

The connection between the TP and the PU 2.1 node has been broken (a LAN error).

The SnaBase at the TP’s computer encountered an ABEND.

LUA_COMM_SUBSYSTEM_NOT_LOADED

Primary return code; a required component could not be loaded or has terminated while processing the verb. Thus, communication could not take place. Contact the system administrator for corrective action.

LUA_INVALID_VERB_SEGMENT

Primary return code; the VCB extended beyond the end of the data segment.

LUA_UNEXPECTED_DOS_ERROR

Primary return code; after issuing an operating system call, an unexpected operating system return code was received and is specified in the secondary return code.

LUA_STACK_TOO_SMALL

Primary return code; the stack size of the application is too small to execute the verb. Increase the stack size of your application.

LUA_INVALID_VERB

Primary return code; either the verb code or the operation code, or both, is invalid. The verb did not execute.

Remarks

There are two types of SLI_CLOSE: normal and ABEND. For a normal close, lua_flag1.close_abend is set to 0. The sequence for a normal close can be initiated either as primary (host-initiated) or secondary (requested by a Windows LUA application). During a primary normal close, the Windows LUA interface:

Reads the SHUTD command and posts the SESSION_END REQUESTED status to the application.

Writes the CHASE command (if necessary).

Reads and processes the CHASE command response (if necessary).

Writes the shutdown complete (SHUTC) command.

Reads and processes the SHUTC command response.

Reads and processes the CLEAR command (if necessary).

Writes the CLEAR command response (if necessary).

Reads and processes the UNBIND command.

Writes the UNBIND command response.

Stops the session.

During a secondary normal close, the Windows LUA interface:

Writes the RSHUTD command.

Reads and processes the RSHUTD command response.

Reads and processes the CLEAR command (if necessary).

Writes the CLEAR command response (if necessary).

Reads and processes the UNBIND command.

Writes the UNBIND command response.

Stops the session.

For an ABEND close, lua_flag1.close_abend is set to 1, which directs the Windows LUA interface to close the session immediately. After SLI_CLOSE starts processing, the LU-LU connection is terminated and the SSCP is informed that the LU is not capable of sustaining a session.


SLI_OPEN
LUA SLI Verbs	4 of 9

SLI_OPEN

Transfers control of the specified LU to the Windows LUA application. SLI_OPEN establishes a session between the SSCP and the specified LU, as well as an LU-LU session.

Syntax

lua_verb	unsigned short int

lua_verb_length	unsigned short int

lua_opcode	unsigned short int

lua_correlator	unsigned long int

lua_luname	unsigned char

lua_data_length	unsigned int

lua_data_ptr	char far *

lua_post_handle	unsigned long int

lua_encr_decr_option	unsigned char

lua_init_type	unsigned char

lua_wait	unsigned short int

lua_extension_list_offset	unsigned short int

lua_routine_type	unsigned char

lua_module_name	unsigned char

lua_procedure_name	unsigned char

lua_prim_rc	unsigned short int

lua_sec_rc	unsigned long int

lua_sid	unsigned long int

lua_flag2.async	struct (unsigned char)

Parameter	Description

lua_verb	Supplied parameter; LUA_VERB_SLI.

lua_verb_length	Supplied parameter; specifies the length, in bytes, of the LUA VCB. It must contain the length of the verb being issued.

lua_opcode	Supplied parameter; LUA_OPCODE_SLI_OPEN.

lua_correlator	Supplied parameter; a user-supplied value that links the verb with other user-supplied information. This parameter is neither examined nor modified by the Windows LUA interface.

lua_luname	Supplied parameter; specifies the ASCII name of the local LU used by the Windows LUA session.

SLI_OPEN and RUI_INIT require this parameter. Other verbs require this parameter only if lua_sid is 0.

This parameter is 8 bytes long; pad on the right with spaces, X'20', if the name is shorter than 8 characters.

lua_data_length	Supplied parameter; supplies the actual length of the data being sent or received.

lua_data_ptr	Supplied parameter; points to the application data buffer. Both SNA commands and data are placed in this buffer and they can be in an EBCDIC format.

When SLI_RECEIVE or RUI_READ is issued, this parameter points to the location to receive the data from the host.

When SLI_SEND or RUI_WRITE is issued, this parameter points to the location of the application’s data to be sent to the host.

When SLI_PURGE or RUI_PURGE is issued, this parameter points to the location of the SLI_RECEIVE or RUI_READ verb’s VCB that is to be canceled.

When SLI_OPEN is issued, this parameter can be one of the following:

   The LOGON message for the SSCP normal flow when the initialization type is secondary with an unformatted LOGON message.

   The RU for INITSELF. When the initialization type is secondary with INITSELF, the necessary data for the application is provided.

   For all other open types, this field should be set to 0.

This information is provided by the Windows LUA application.

lua_post_handle	Supplied parameter; for the Windows NT system, if asynchronous notification is to be accomplished by events, lua_post_handle contains the handle of the event to be signaled.

For all other environments, this parameter is reserved and should be set to 0.

lua_encr_decr_option	Cryptography is not supported in the Windows LUA standard.

lua_wait	Supplied parameter; provides the number of seconds the Windows LUA interface is to wait before retrying the transmission of the INITSELF or the LOGON message after the host sends any one of these messages:

   A negative response and the secondary return code is one of the following:
RESOURCE_NOT_AVAILABLE (X'08010000')
SESSION_LIMIT_EXCEEDED (X'08050000')
SESSION_SERVICE_PATH_ERROR (X'087D0000')

Note that SLI_OPEN terminates with error if lua_wait is set to 0 and one of the above occurs.

   A network services procedure error (NSPE) message.

   A NOTIFY command, which indicates a procedure error.

lua_extension_list_offset	Supplied parameter; specifies the offset from the start of the VCB to the extension list of user-supplied DLLs. The value must be the beginning of a word boundary unless there is no extension list. In this case, the value must be set to 0.

lua_routine_type	Supplied parameter; specifies the type of routine. Valid entries are lua_routine_type_bind, lua_routine_type_stsn, and lua_routine_type_end.

lua_module_name	Supplied parameter; provides the user-supplied ASCII module name, up to eight characters long, with the remaining bytes set to X'00'.

lua_procedure_name	Supplied parameter; provides the user-supplied DLL procedure name in ASCII, up to 32 characters long, with the remaining bytes set to X'00'.

lua_sid	Returned parameter; specifies the session ID and is returned by SLI_OPEN and RUI_INIT. Other verbs use this parameter to identify the session used for the command. If other verbs use lua_luname to identify sessions, set lua_sid to 0.

lua_flag2.async	Returned parameter; set to 1 if the LUA interface verb completed asynchronously.

Return Codes

LUA_OK

Primary return code; the verb executed successfully:

LUA_SEC_OK

Secondary return code; no additional information exists for LUA_OK.

LUA_PARAMETER_CHECK

Primary return code; the verb did not execute because of a parameter error:

LUA_INVALID_LUNAME

Secondary return code; an invalid lua_luname name was specified.

LUA_BAD_SESSION_ID

Secondary return code; an invalid value for lua_sid was specified in the VCB.

LUA_BAD_DATA_PTR

Secondary return code; the lua_data_ptr parameter either does not contain a valid pointer or does not point to a read/write segment and supplied data is required.

LUA_DATA_SEGMENT_LENGTH_ERROR

Secondary return code; one of the following occurred:

The supplied data segment for SLI_RECEIVE or SLI_SEND is not a read/write data segment as required.

The supplied data segment for SLI_RECEIVE is not as long as that provided in lua_max_length.

The supplied data segment for SLI_SEND is not as long as that provided in lua_data_length.

LUA_RESERVED_FIELD_NOT_ZERO

Secondary return code; a reserved parameter for the verb just issued is not set to 0.

LUA_INVALID_POST_HANDLE

Secondary return code; for a Windows NT system using events as the asynchronous posting method, the Windows LUA VCB does not contain a valid event handle.

For the Windows version 3.x system, the LUA VCB does not contain the valid procedure address returned by the MakeProcInstance command.

For OS/2, the LUA VCB does not contain a valid semaphore or queue handle, which is needed when a verb completes asynchronously.

LUA_VERB_LENGTH_INVALID

Secondary return code; an LUA verb was issued with a value for lua_verb_length unexpected by the LUA.

LUA_INVALID_OPEN_INIT_TYPE

Secondary return code; the value in the lua_init_type contained in SLI_OPEN is invalid.

LUA_INVALID_OPEN_DATA

Secondary return code; the lua_init_type for the SLI_OPEN issued is set to LUA_INIT_TYPE_SEC_IS when the buffer for data does not have a valid INITSELF command.

LUA_INVALID_OPEN_ROUTINE_TYPE

Secondary return code; the lua_open_routine_type for the SLI_OPEN list of extension routines is invalid.

LUA_DATA_LENGTH_ERROR

Secondary return code; the application did not provide user-supplied data required by the verb issued. Note that when SLI_SEND is issued for an SNA LUSTAT command, status (in 4 bytes) is required, and that when SLI_OPEN is issued with secondary initialization, data is required.

LUA_INVALID_SLI_ENCR_OPTION

Secondary return code; the lua_encr_decr_option parameter was set to 128 in SLI_OPEN, which is not supported for the encryption/decryption processing option.

LUA_STATE_CHECK

Primary return code; the verb did not execute because it was issued in an invalid state:

LUA_NOT_ACTIVE

Secondary return code; LUA was not active within SNA Server when an LUA verb was issued.

LUA_UNEXPECTED_SNA_SEQUENCE

Secondary return code; unexpected data or commands were received from the host while SLI_OPEN was processing.

LUA_NEG_RSP_FROM_BIND_ROUTINE

Secondary return code; the user-supplied SLI_BIND routine responded negatively to the BIND. SLI_OPEN ended unsuccessfully.

LUA_NEG_RSP_FROM_STSN_ROUTINE

Secondary return code; the user-supplied SLI STSN routine responded negatively to the STSN. SLI_OPEN ended unsuccessfully.

LUA_PROCEDURE_ERROR

Secondary return code; a host procedure error is indicated by the receipt of an NSPE or NOTIFY message. The return code is posted to SLI_OPEN when the retry option is not used. To use the reset option, set lua_wait to a value other than 0. The LOGON or INITSELF command will be retried until the host is ready or until you issue SLI_CLOSE.

LUA_RECEIVED_UNBIND

Secondary return code; the primary LU sent an SNA UNBIND command to the LUA interface when a session was active. As a result, the session was stopped.

LUA_SLI_LOGIC_ERROR

Secondary return code; the LUA interface found an internal error in logic.

LUA_NO_RUI_SESSION

Secondary return code; no session has been initialized for the LUA verb issued, or some verb other than SLI_OPEN was issued before the session was initialized.

LUA_RESOURCE_NOT_AVAILABLE

Secondary return code; the logical unit, physical unit, link, or link station specified in the request unit is unavailable. This return code is posted to SLI_OPEN when a resource is unavailable unless you use the retry option.

To use the retry option, set lua_wait to a value other than 0. The LOGON or INITSELF command will be retried until the host is ready or until you issue SLI_CLOSE.

LUA_SESSION_LIMIT_EXCEEDED

Secondary return code; the session requested was not activated because an NAU is at its session limit. This SNA sense code applies to the following requests: BID, CINIT, INIT, and ACTDRM.

The code will be posted to SLI_OPEN when an NAU is at its limit, unless you use the RETRY option.

To use the reset option, set lua_wait to a value other than 0. The LOGON or INITSELF command will be retried until the host is ready or until you issue SLI_CLOSE.

LUA_LU_COMPONENT_DISCONNECTED

Secondary return code; an LU component is unavailable because it is not connected properly. Make sure that the power is on.

LUA_NEGOTIABLE_BIND_ERROR

Secondary return code; a negotiable BIND was received, which is only allowed by the SLI when a user-supplied SLI_BIND routine is provided with SLI_OPEN.

LUA_BIND_FM_PROFILE_ERROR

Secondary return code; only file management header profiles 3 and 4 are supported by the LUA interface. A file management profile other than 3 or 4 was found on the BIND.

LUA_BIND_TS_PROFILE_ERROR

Secondary return code; only transmission service (TS) profile 3 and 4 are supported by the LUA interface. A TS other than 3 or 4 was found on the BIND.

LUA_BIND_LU_TYPE_ERROR

Secondary return code; only LU 0, LU 1, LU 2, and LU 3 are supported by LUA. An LU other than 0, 1, 2, or 3 was found.

LUA_SSCP_LU_SESSION_NOT_ACTIVE

Secondary return code; the required SSCP-LU is inactive. Specific sense code information is in bytes 2 and 3. Valid settings are X'0000', X'0001', X'0002', X'0003', and X'0004'.

LUA_SESSION_SERVICES_PATH_ERROR

Secondary return code; a request for session services cannot be rerouted to an SSCP-SSCP session path. Specific sense code information in bytes 2 and 3 gives more information about why the request cannot be rerouted.

LUA_UNSUCCESSFUL

Primary return code; the verb record supplied was valid but the verb did not complete successfully:

LUA_VERB_RECORD_SPANS_SEGMENTS

Secondary return code; the LUA VCB length parameter plus the segment offset is beyond the segment end.

LUA_SESSION_ALREADY_OPEN

Secondary return code; a session is already open for the LU name specified in SLI_OPEN.

LUA_INVALID_PROCESS

Secondary return code; the session for which an LUA verb was issued is unavailable because another process owns the session.

LUA_LINK_NOT_STARTED

Secondary return code; the LUA was not able to activate the data link during initialization of the session.

LUA_INVALID_ADAPTER

Secondary return code; the configuration for the data link control (DLC) is in error, or the configuration file is corrupted.

LUA_ENCR_DECR_LOAD_ERROR

Secondary return code; an unexpected return code was received from the OS/2 DosLoadModule function while attempting to load the user-provided encryption or decryption dynamic link module.

LUA_ENCR_DECR_PROC_ERROR

Secondary return code; an unexpected return code was received from the OS/2 DosGetProcAddr function while attempting to get the procedure address within the user-provided encryption or decryption dynamic link module.

LUA_NEG_NOTIFY_RSP

Secondary return code; the SSCP responded negatively to a NOTIFY request issued indicating that the secondary LU was capable of a session. The half-session component that received the request understood and supported the request but could not execute it.

LUA_LU_INOPERATIVE

Secondary return code; a severe error occurred while the SLI was attempting to stop the session. This LU is unavailable for any LUA requests until an ACTLU is received from the host.

LUA_CANCELED

Primary return code; the secondary return code gives the reason for canceling the command:

LUA_TERMINATED

Secondary return code; the session was terminated when a verb was pending. The verb process was canceled.

LUA_IN_PROGRESS

Primary return code; an asynchronous command was received but is not completed.

LUA_COMM_SUBSYSTEM_ABENDED

Primary return code; indicates one of the following conditions:

The node used by this conversation encountered an ABEND.

The connection between the TP and the PU 2.1 node has been broken (a LAN error).

The SnaBase at the TP’s computer encountered an ABEND.

LUA_COMM_SUBSYSTEM_NOT_LOADED

Primary return code; a required component could not be loaded or has terminated while processing the verb. Thus, communication could not take place. Contact the system administrator for corrective action.

LUA_INVALID_VERB_SEGMENT

Primary return code; the VCB extended beyond the end of the data segment.

LUA_UNEXPECTED_DOS_ERROR

Primary return code; after issuing an operating system call, an unexpected operating system return code was received and is specified in the secondary return code.

LUA_STACK_TOO_SMALL

Primary return code; the stack size of the application is too small to execute the verb. Increase the stack size of your application.

LUA_INVALID_VERB

Primary return code; either the verb code or the operation code, or both, is invalid. The verb did not execute.

Remarks

For each SLI_OPEN, the Windows LUA interface:

Starts the communication session.

Reads and verifies a BIND command from the host, and passes it to the application if a BIND extension routine is supplied.

Writes a BIND response.

Reads and processes the STSN command and passes it to the application if a BIND extension is supplied (if necessary).

Writes the STSN response (if necessary).

Reads the CRV command (if necessary).

Writes the CRV response (if necessary).

Reads and processes the SDT command.

Writes the SDT response.

The Windows LUA interface does the following additional functions for sessions that issue SLI_OPEN with the open type set to LUA_INIT_TYPE_SEC_IS or LUA_INIT_TYPE_SEC_LOG:

Writes an INITSELF or an unformatted LOGON message.

Reads and processes an INITSELF response or LOGON message response.

All SNA message traffic is administered by SLI_OPEN through the SDT command response.

To choose a certain LU configured for Windows LUA, the application sets lua_luname to the LU name in ASCII, padded with trailing spaces if necessary.

When SLI_OPEN is posted with LUA_OK in the lua_prim_rc parameter, SLI_OPEN successfully completed and the LU-LU data-flow session was established. The application can now issue SLI_BID, SLI_CLOSE, SLI_PURGE, SLI_RECEIVE, and SLI_SEND.

When SLI_OPEN is posted with a primary return code other than LUA_OK or LUA_IN_PROGRESS, the command did not successfully establish a session.

When using SLI_OPEN, a Windows LUA application must provide a session initialization type. Valid types are:

Secondary with INITSELF

Secondary with an unformatted LOGON message

Primary waiting for a BIND command

Primary with SSCP access

Each of these session initialization types is described in the following sections.

Secondary with INITSELF

To initialize a session by having the secondary issue an INITSELF command, set lua_init_type to LUA_INIT_TYPE_SEC_IS. When this type of session initialization is chosen, the application has to format and provide the INITSELF command. The address of the INITSELF command is specified by lua_data_ptr. The actual length of the INITSELF command is specified by lua_data_length.

Secondary with an Unformatted LOGON Message

To initialize a session by having the secondary issue an unformatted LOGON message, set lua_init_type to LUA_INIT_TYPE_SEC_LOG. The length of the user’s EBCDIC LOGON message is then specified in lua_data_length. The address of the user’s EBCDIC LOGON message length is specified by lua_data_ptr.

Primary Waiting for a BIND Command

To initialize a session by having the secondary wait for the primary to issue a BIND and SDT, set lua_init_type to LUA_INIT_TYPE_PRIM. Until the host begins a session with the Windows LUA application using the BIND command followed by an SDT command, the SLI_OPEN issued stays IN_PROGRESS.

Primary with SSCP Access

To initialize a session by having the SLI wait for a BIND and SDT but allow SSCP access, set lua_init_type to LUA_INIT_TYPE_PRIM_SSCP. Rather than sending commands to the host to begin a session, the SLI allows the Windows LUA application to issue SLI_SEND and SLI_RECEIVE for the SSCP normal flow only. This allows the INITSELF commands or LOGON messages and responses to be transmitted between the Windows LUA application and the host. The application can have more than one INITSELF and LOGON message. For this type of session only, other SLI verbs can be issued before SLI_OPEN completes. To obtain the INIT_COMPLETE status, the application must first issue SLI_OPEN, and then issue either SLI_BID or SLI_RECEIVE. The INIT_COMPLETE status notifies the application that the SLI_SEND and SLI_RECEIVE verbs for SSCP normal flow data can be issued.

BIND, CRV, and STSN Routines

For BIND and STSN routines supplied by the application, the names of DLLs and the entry points for procedures are passed in the SLI_OPEN verb’s VCB. During SLI_OPEN, the BIND and STSN routines are called if the appropriate SNA request is received. When a BIND routine is not supplied by the application, the SLI performs a minimal check of the BIND commands and responds as necessary. If no STSN routine is supplied and an STSN request arrives, a positive response is issued by the SLI. If a CRV request arrives, a negative response is issued by the SLI.

Names for BIND and STSN routines are provided as extensions of the SLI_OPEN verb’s VCB. The lua_extension_list_offset parameter provides the offset from the start of the VCB to the first name in the extension list.

Recovering from SESSION_FAILURE

If the SLI_OPEN completes with the primary return code of SESSION_FAILURE, the Windows LUA interface allows you to reissue SLI_OPEN without issuing SLI_CLOSE.

Ending a Pending SLI_OPEN

To end a pending SLI_OPEN, issue SLI_CLOSE with lua_flag2.close_abend set to on.


SLI_PURGE
LUA SLI Verbs	5 of 9

SLI_PURGE

Cancels SLI_RECEIVE verbs issued with a wait condition.

Syntax

lua_verb	unsigned short int

lua_verb_length	unsigned short int

lua_opcode	unsigned short int

lua_correlator	unsigned long int

lua_luname	unsigned char

lua_sid	unsigned long int

lua_data_ptr	char far *

lua_post_handle	unsigned long int

lua_prim_rc	unsigned short int

lua_sec_rc	unsigned long int

lua_flag2.async	struct (unsigned char)

Parameter	Description

lua_verb	Supplied parameter; LUA_VERB_SLI.

lua_verb_length	Supplied parameter; specifies the length, in bytes, of the LUA VCB. It must contain the length of the verb being issued.

lua_opcode	Supplied parameter; LUA_OPCODE_SLI_PURGE.

lua_correlator	Supplied parameter; a user-supplied value that links the verb with other user-supplied information. This parameter is neither examined nor modified by the Windows LUA interface.

lua_luname	Supplied parameter; specifies the ASCII name of the local LU used by the Windows LUA session.

SLI_OPEN and RUI_INIT require this parameter. Other verbs require this parameter only if lua_sid is 0.

This parameter is 8 bytes long; pad on the right with spaces, X'20', if the name is shorter than 8 characters.

lua_sid	Supplied/returned parameter; specifies the session ID and is returned by SLI_OPEN and RUI_INIT. Other verbs use this parameter to identify the session used for the command. If other verbs use lua_luname to identify sessions, set lua_sid to 0.

lua_data_ptr	When SLI_SEND or RUI_WRITE is issued, this parameter points to the location of the application’s data to be sent to the host.

When SLI_PURGE or RUI_PURGE is issued, this parameter points to the location of the SLI_RECEIVE or RUI_READ verb’s VCB that is to be canceled.

When SLI_OPEN is issued, this parameter can be one of the following:

   The LOGON message for the SSCP normal flow when the initialization type is secondary with an unformatted LOGON message.

   The RU for INITSELF. When the initialization type is secondary with INITSELF, the necessary data for the application program is provided.

   For all other open types, this field should be set to 0.

This information is provided by the Windows LUA application.

lua_post_handle	Supplied parameter; for the Windows NT system, if asynchronous notification is to be accomplished via events, lua_post_handle contains the handle of the event to be signaled.

For all other environments, this parameter is reserved and should be set to 0.

lua_flag2.async	Returned parameter; set to 1 if the LUA interface verb completed asynchronously.

Return Codes

LUA_OK

Primary return code; the verb executed successfully:

LUA_SEC_OK

Secondary return code; no additional information exists for LUA_OK.

LUA_PARAMETER_CHECK

Primary return code; the verb did not execute because of a parameter error:

LUA_INVALID_LUNAME

Secondary return code; an invalid lua_luname was specified.

LUA_BAD_SESSION_ID

Secondary return code; an invalid value for lua_sid was specified in the VCB.

LUA_BAD_DATA_PTR

Secondary return code; the lua_data_ptr parameter either does not contain a valid pointer or does not point to a read/write segment and supplied data is required.

LUA_RESERVED_FIELD_NOT_ZERO

Secondary return code; a reserved parameter for the verb just issued is not set to 0.

LUA_INVALID_POST_HANDLE

Secondary return code; for the Windows NT system using events as the asynchronous posting method, the Windows LUA VCB does not contain a valid event handle.

For the Windows version 3.x system, the LUA VCB does not contain the valid procedure address returned by the MakeProcInstance command.

For OS/2, the LUA VCB does not contain a valid semaphore or queue handle, which is needed when a verb completes asynchronously.

LUA_VERB_LENGTH_INVALID

Secondary return code; an LUA verb was issued with a value for lua_verb_length unexpected by the LUA.

LUA_STATE_CHECK

Primary return code; the verb did not execute because it was issued in an invalid state:

LUA_NO_SLI_SESSION

Secondary return code; a session was not open or was down due to an SLI_CLOSE or session failure when a command was issued.

LUA_NO_RECEIVE_TO_PURGE

Secondary return code; no SLI_RECEIVE was outstanding when you issued SLI_PURGE. One of two situations caused the problem:

SLI_RECEIVE completed before SLI_PURGE finished processing.You can change the application to take care of this problem because it is not an error condition.

The lua_data_ptr parameter does not correctly point to the 	SLI_RECEIVE you want to purge.

LUA_SLI_PURGE_PENDING

Secondary return code; an SLI_PURGE was still active when another SLI_PURGE was issued. Only one SLI_PURGE can be active at a time.

LUA_SESSION_FAILURE

Primary return code; an error condition, specified in the secondary return code, caused the session to fail:

LUA_RECEIVED_UNBIND

Secondary return code; the primary LU sent an SNA UNBIND command to the LUA interface when a session was active. As a result, the session was stopped.

LUA_LU_COMPONENT_DISCONNECTED

Secondary return code; an LU component is unavailable because it is not connected properly. Make sure that the power is on.

LUA_UNSUCCESSFUL

Primary return code; the verb record supplied was valid but the verb did not complete successfully:

LUA_VERB_RECORD_SPANS_SEGMENTS

Secondary return code; the LUA VCB length parameter plus the segment offset is beyond the segment end.

LUA_NOT_ACTIVE

Secondary return code; LUA was not active within SNA Server when an LUA verb was issued.

LUA_NOT_READY

Secondary return code; one of the following caused the SLI session to be temporarily suspended:

An SNA UNBIND type X'02' command was received, which indicates a new BIND is coming. If the UNBIND type X'02' is received after the beginning SLI_OPEN is complete, the session is suspended until a BIND, optional CRV and STSN, and SDT flows are received. These routines are re-entrant because they have to be called again. The session resumes after the SLI processes the SDT command. If the UNBIND type X'02' is received while the SLI_OPEN is still processing, the primary return code is SESSION_FAILURE, not LUA_STATUS.

The receipt of an SNA CLEAR caused the suspension. Receipt of an SNA SDT will cause the session to resume.

LUA_INVALID_PROCESS

Secondary return code; the session for which an RUI verb was issued is unavailable because another OS/2 process owns the session.

LUA_LU_INOPERATIVE

Secondary return code; a severe error occurred while the RUI was attempting to stop the session. This LU is unavailable for any LUA requests until an ACTLU is received from the host.

LUA_CANCELED

Primary return code; the secondary return code gives the reason for canceling the command:

LUA_TERMINATED

Secondary return code; the session was terminated when a verb was pending. The verb process was canceled.

LUA_IN_PROGRESS

Primary return code; an asynchronous command was received but is not completed.

LUA_COMM_SUBSYSTEM_ABENDED

Primary return code; indicates one of the following conditions:

The node used by this conversation encountered an ABEND.

The connection between the TP and the PU 2.1 node has been broken (a LAN error).

The SnaBase at the TP’s computer encountered an ABEND.

LUA_COMM_SUBSYSTEM_NOT_LOADED

Primary return code; a required component could not be loaded or has terminated while processing the verb. Thus, communication could not take place. Contact the system administrator for corrective action.

LUA_INVALID_VERB_SEGMENT

Primary return code; the VCB extended beyond the end of the data segment.

LUA_UNEXPECTED_DOS_ERROR

Primary return code; after issuing an operating system call, an unexpected operating system return code was received and is specified in the secondary return code.

LUA_STACK_TOO_SMALL

Primary return code; the stack size of the application is too small to execute the verb. Increase the stack size of your application.

LUA_INVALID_VERB

Primary return code; either the verb code or the operation code, or both, is invalid. The verb did not execute.

Remarks

SLI_PURGE cancels SLI_RECEIVE commands with a wait condition.

Typically, SLI_PURGE is issued if SLI_RECEIVE takes too long to complete. To cancel an SLI_RECEIVE, lua_data_ptr has to point to the SLI_RECEIVE VCB to cancel. The primary return code of the SLI_RECEIVE will be set to LUA_CANCELED when SLI_PURGE succeeds in canceling SLI_RECEIVE.


SLI_RECEIVE
LUA SLI Verbs	6 of 9

SLI_RECEIVE

Receives responses, SNA commands, and data into a Windows LUA application’s buffer. SLI_RECEIVE also provides the current status of the session to the Windows LUA application.

Syntax

lua_verb	unsigned short int

lua_verb_length	unsigned short int

lua_opcode	unsigned short int

lua_correlator	unsigned long int

lua_luname	unsigned char

lua_sid	unsigned long int

lua_max_length	unsigned int

lua_data_ptr	char far *

lua_post_handle	unsigned long int

lua_flag1.bid_enable	struct (unsigned char)

lua_flag1.nowait	struct (unsigned char)

lua_flag1.sscp_exp	struct (unsigned char)

lua_flag1.sscp_norm	struct (unsigned char)

lua_flag1.lu_exp	struct (unsigned char)

lua_flag1.lu_norm	struct (unsigned char)

lua_prim_rc	unsigned short int

lua_sec_rc	unsigned long int

lua_data_length	unsigned long int

lua_th	struct (unsigned char)

lua_rh	struct (unsigned char)

lua_message_type	unsigned char

lua_flag2.async	struct (unsigned char)

lua_flag2.sscp_exp	struct (unsigned char)

lua_flag2.sscp_norm	struct (unsigned char)

lua_flag2.lu_exp	struct (unsigned char)

lua_flag2.lu_norm	struct (unsigned char)

Parameter	Description

lua_verb	Supplied parameter; LUA_VERB_SLI.

lua_verb_length	Supplied parameter; specifies the length, in bytes, of the LUA VCB. It must contain the length of the verb being issued.

lua_opcode	Supplied parameter; LUA_OPCODE_SLI_RECEIVE.

lua_correlator	Supplied parameter; a user-supplied value that links the verb with other user-supplied information. This parameter is neither examined nor modified by the Windows LUA interface.

lua_luname	Supplied parameter; specifies the ASCII name for the local LU to be used for the Windows LUA session.

SLI_OPEN and RUI_INIT require this parameter. Other Windows LUA verbs require this parameter only if the lua_sid is 0.

This parameter is 8 bytes long; pad on the right with spaces, X'20', if the name is shorter than 8 characters.

lua_sid	Supplied/returned parameter; specifies the session ID and is returned by SLI_OPEN and RUI_INIT. Other verbs use this parameter to identify the session used for the command. If other verbs use lua_luname to identify sessions, set lua_sid to 0.

lua_max_length	Supplied parameter; specifies the length of the buffer that is used to receive data.

lua_data_ptr	Supplied parameter; points to the application data buffer. Both SNA commands and data are placed in this buffer and they can be in an EBCDIC format.

When SLI_RECEIVE or RUI_READ is issued, this parameter points to the location to receive the data from the host.

When SLI_SEND or RUI_WRITE is issued, this parameter points to the location of the application’s data to be sent to the host.

When SLI_PURGE or RUI_PURGE is issued, this parameter points to the location of the SLI_RECEIVE or RUI_READ verb’s VCB that is to be canceled.

When SLI_OPEN is issued, this parameter can be one of the following:

   The LOGON message for the SSCP normal flow when the initialization type is secondary with an unformatted LOGON message.

   The RU for INITSELF. When the initialization type is secondary with INITSELF, the necessary data for the application is provided.

   For all other open types, this field should be set to 0.

This information is provided by the Windows LUA application.

lua_post_handle	Supplied parameter; for the Windows NT system, if asynchronous notification is to be accomplished by events, lua_post_handle contains the handle of the event to be signaled.

lua_flag1.bid_enable	Supplied parameter; used by SLI_RECEIVE and RUI_READ to indicate that the previous SLI_BID or RUI_BID is to be reused and reactivated. For verbs other than SLI_RECEIVE and RUI_READ, this flag must be set to off.

lua_flag1.nowait	Supplied parameter; used by SLI_RECEIVE and RUI_READ to specify that the verbs should be posted with the NO_DATA return code when no data is available to read. For verbs other than SLI_RECEIVE and RUI_READ, this flag must be set to off.

lua_flag1.sscp_exp	Supplied parameter; flag indicates SSCP expedited flow.

lua_flag1.sscp_norm	Supplied parameter; flag indicates SSCP normal flow.

lua_flag1.lu_exp	Supplied parameter; flag indicates LU expedited flow.

lua_flag1.lu_norm	Supplied parameter; flag indicates LU normal flow.

lua_data_length	Returned parameter; specifies the length of the data being sent or received.

lua_th	Returned parameter; supplies the information from the SNA TH of the received message. Various subparameters are to be set for write functions and returned for read functions. For a list of the subparameters that apply to this parameter, see Appendix B, “Verb Control Block.”

lua_rh	Returned parameter; supplies the information from the SNA RH of the received message. It is set for the write function and returned by the read and bid functions. For a list of the bit masks that apply to this parameter, see Appendix B, “Verb Control Block.”

lua_message_type 	Returned parameter; supplies the type of SNA data or command received from the host. Possible values are as follows:

LUA_MESSAGE_TYPE_LU_DATA

LUA_MESSAGE_TYPE_SSCP_DATA

LUA_MESSAGE_TYPE_RSP

LUA_MESSAGE_TYPE_BID

LUA_MESSAGE_TYPE_BIND

LUA_MESSAGE_TYPE_BIS

LUA_MESSAGE_TYPE_CANCEL

LUA_MESSAGE_TYPE_CHASE

LUA_MESSAGE_TYPE_LUSTAT_LU

lua_message_type	LUA_MESSAGE_TYPE_LUSTAT_SSCP

LUA_MESSAGE_TYPE_QC

LUA_MESSAGE_TYPE_QEC

LUA_MESSAGE_TYPE_RELQ

LUA_MESSAGE_TYPE_RTR

LUA_MESSAGE_TYPE_SBI

LUA_MESSAGE_TYPE_SIGNAL

LUA_MESSAGE_TYPE_STSN

The SLI receives and responds to the BIND and STSN requests through the LUA interface extension routines.

LU-DATA, LUSTAT_LU, LUSTAT_SSCP, and SSCP_DATA are not SNA commands.

lua_flag2.async	Returned parameter; set to 1 if the LUA interface verb completed asynchronously.

lua_flag2.sscp_exp	Returned parameter; flag indicates SSCP expedited flow.

lua_flag2.sscp_norm	Returned parameter; flag indicates SSCP normal flow.

lua_flag2.lu_exp	Returned parameter; flag indicates LU expedited flow.

lua_flag2.lu_norm	Returned parameter; flag indicates LU normal flow.

Return Codes

LUA_OK

Primary return code; the verb executed successfully:

LUA_SEC_OK

Secondary return code; no additional information exists for LUA_OK.

LUA_PARAMETER_CHECK

Primary return code; the verb did not execute because of a parameter error:

LUA_INVALID_LUNAME

Secondary return code; an invalid lua_luname was specified.

LUA_BAD_SESSION_ID

Secondary return code; an invalid value for lua_sid was specified in the VCB.

LUA_BAD_DATA_PTR

Secondary return code; the lua_data_ptr parameter either does not contain a valid pointer or does not point to a read/write segment and supplied data is required.

LUA_RESERVED_FIELD_NOT_ZERO

Secondary return code; a reserved parameter for the verb just issued is not set to 0.

LUA_INVALID_POST_HANDLE

Secondary return code; for a Windows NT system using events as the asynchronous posting method, the Windows LUA VCB does not contain a valid event handle.

For the Windows version 3.x system, the LUA VCB does not contain the valid procedure address returned by the MakeProcInstance command.

For OS/2, the LUA VCB does not contain a valid semaphore or queue handle, which is needed when a verb completes asynchronously.

LUA_BID_VERB_SEGMENT_ERROR

Secondary return code; the buffer with the SLI_BID VCB was released before the SLI_RECEIVE with lua_flag1.bid_enable set to 1 was issued.

LUA_NO_PREVIOUS_BID_ENABLED

Secondary return code; SLI_BID was not issued prior to issuing SLI_RECEIVE with lua_flag1.bid_enable.

LUA_BID_ALREADY_ENABLED

Secondary return code; SLI_RECEIVE was issued with lua_flag1.bid_enable when SLI_BID was already active.

LUA_INVALID_FLOW

Secondary return code; the lua_flag1 flow flags were set incorrectly when a verb was issued:

When issuing SLI_SEND to send an SNA response, set only one lua_flag1 flow flag.

When issuing SLI_RECEIVE, set at least one lua_flag1 flow flag.

LUA_VERB_LENGTH_INVALID

Secondary return code; an LUA verb was issued with a value for lua_verb_length unexpected by the LUA.

LUA_STATE_CHECK

Primary return code; the verb did not execute because it was issued in an invalid state:

LUA_NO_SLI_SESSION

Secondary return code; a session was not open or was down due to an SLI_CLOSE or session failure when a command was issued.

LUA_RECEIVE_ON_FLOW_PENDING

Secondary return code; an SLI_RECEIVE was still outstanding when this application issued another SLI_RECEIVE for an SNA flow.

LUA_SESSION_FAILURE

Primary return code; an error condition, specified in the secondary return code, caused the session to fail:

LUA_RUI_WRITE_FAILURE

Secondary return code; an unexpected error was posted to the SLI by RUI_WRITE.

LUA_RECEIVED_UNBIND

Secondary return code; the primary LU sent an SNA UNBIND command to the LUA interface when a session was active. As a result, the session was stopped.

LUA_SLI_LOGIC_ERROR

Secondary return code; the LUA interface found an internal error in logic.

LUA_NO_RUI_SESSION

Secondary return code; no session has been initialized for the LUA verb issued or some verb other than SLI_OPEN was issued before the session was initialized.

LUA_MODE_INCONSISTENCY

Secondary return code; performing this function is not allowed by the current status. The request sent to the half-session component was not executed even though it was understood and supported. This SNA sense code is also an exception request sense code.

LUA_RECEIVER_IN_TRANSMIT_MODE

Secondary return code; either resources needed to handle normal flow data were not available or the state of the half-duplex contention was not received when a normal-flow request was received. The result is a race condition. This SNA sense code is also an exception request sense code.

LUA_LU_COMPONENT_DISCONNECTED

Secondary return code; an LU component is unavailable because it is not connected properly. Make sure that the power is on.

LUA_FUNCTION_NOT_SUPPORTED

Secondary return code; LUA does not support the requested function. A control character, an RU parameter, or a formatted request code may have specified the function. Specific sense code information is in bytes 2 and 3.

LUA_CHAINING_ERROR

Secondary return code; the sequence of the chain indicator settings is in error. An invalid request header or request unit for the receiver’s current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_BRACKET

Secondary return code; the sender failed to enforce the session bracket rules. Note that contention and race conditions are exempt from this error. An invalid request header or request unit for the receiver’s current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_DIRECTION

Secondary return code; while the half-duplex flip-flop state was NOT_RECEIVE, a request for normal flow was received. An invalid request header or request unit for the receiver’s current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_DATA_TRAFFIC_QUIESCED

Secondary return code; a DFC or FMD request was received from a half-session that sent either a SHUTC command or QC command, and the DFC or FMD request has not responded to a RELQ command. An invalid request header or request unit for the receiver’s current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_NO_BEGIN_BRACKET

Secondary return code; the receiver has already sent a positive response to a BIS command when a BID or an FMD request specifying BBI=BB was received. An invalid request header or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_IMMEDIATE_REQUEST_MODE_ERROR

Secondary return code; the request violated the immediate request mode protocol. An invalid header request or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_QUEUED_RESPONSE_ERROR

Secondary return code; the request violated the queued response protocol. An invalid header request or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_ERP_SYNC_EVENT_ERROR

Secondary return code; a violation of the ERP synchronous event protocol occurred. An invalid header request or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_RSP_CORRELATION_ERROR

Secondary return code; a response was sent that does not correspond to a previously received request or a response was received that does not correspond to a previously sent request.

LUA_RSP_PROTOCOL_ERROR

Secondary return code; a violation of the response protocol was found in the response received from the primary half-session.

LUA_BB_NOT_ALLOWED

Secondary return code; the begin bracket indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_EB_NOT ALLOWED

Secondary return code; the end bracket indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_EXCEPTION_RSP_NOT_ALLOWED

Secondary return code; when an exception response was not allowed, one was requested. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_DEFINITE_RSP_NOT_ALLOWED

Secondary return code; when a definite response was not allowed, one was requested. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_CD_NOT_ALLOWED

Secondary return code; the change-direction indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_NO_RESPONSE_NOT_ALLOWED

Secondary return code; a request other than an EXR contained a NO RESPONSE. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_CHAINING_NOT_SUPPORTED

Secondary return code; the chaining indicators were incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_BRACKETS_NOT_SUPPORTED

Secondary return code; the bracket indicators were incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_CD_NOT_SUPPORTED

Secondary return code; the change-direction indicator was set, but LUA does not support change-direction for this situation. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_USE_OF_FI

Secondary return code; the format indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_ALTERNATE_CODE_NOT_SUPPORTED

Secondary return code; the code selection indicator was set, but LUA does not support code selection for this session. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_RU_CATEGORY

Secondary return code; the request unit category indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_REQUEST_CODE

Secondary return code; the request code was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_SPEC_OF_SDI_RTI

Secondary return code; the SDI and the RTI were not specified correctly on a response. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_DR1I_DR2I-ERI

Secondary return code; the DR1I, the DR2I, and the ERI were specified incorrectly. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_USE_OF QRI

Secondary return code; the queued response indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_USE_OF_EDI

Secondary return code; the EDI was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_USE_OF_PDI

Secondary return code; the PDI was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_UNSUCCESSFUL

Primary return code; the verb record supplied was valid but the verb did not complete successfully:

LUA_DATA_TRUNCATED

Secondary return code; the data was truncated because the data received was longer than the buffer length specified in lua_max_length.

LUA_DATA_SEGMENT_LENGTH_ERROR

Secondary return code; one of the following has occurred:

The supplied data segment for SLI_RECEIVE or SLI_SEND is not a read/write data segment as required.

The supplied data segment for SLI_RECEIVE is not as long as that provided in lua_max_length.

The supplied data segment for SLI_SEND is not as long as that provided the lua_data_length.

LUA_NO_DATA

Secondary return code; no data was available to read when SLI_RECEIVE containing a no wait parameter was issued.

LUA_VERB_RECORD_SPANS_SEGMENTS

Secondary return code; the LUA VCB length parameter plus the segment offset is beyond the segment end.

LUA_NOT_ACTIVE

Secondary return code; LUA was not active within SNA Server when an LUA verb was issued.

LUA_NOT_READY

Secondary return code; one of the following has caused the SLI session to be temporarily suspended:

An SNA UNBIND type X'02' command was received, which indicates a new BIND is coming. If the UNBIND type X'02' is received after the beginning SLI_OPEN is complete, the session is suspended until a BIND, optional CRV and STSN, and SDT flows are received. These routines are re-entrant because they have to be called again. The session resumes after the SLI processes the SDT command. If the UNBIND type X'02' is received while the SLI_OPEN is still processing, the primary return code is LUA_SESSION_FAILURE, not LUA_STATUS.

The receipt of an SNA CLEAR caused the suspension. Receipt of an SNA SDT will cause the session to resume.

LUA_SLI_LOGIC_ERROR

Secondary return code; the LUA interface found an internal error in logic.

LUA_INVALID_PROCESS

Secondary return code; the session for which an LUA verb was issued is unavailable because another OS/2 process owns the session.

LUA_LU_INOPERATIVE

Secondary return code; a severe error occurred while the LUA was attempting to stop the session. This LU is unavailable for any LUA requests until an ACTLU is received from the host.

LUA_RECEIVE_CORRELATION_TABLE_FULL

Secondary return code; the session receive correlation table for the flow requested reached its capacity.

LUA_NEGATIVE_RESPONSE

Primary return code; either the LUA sent a negative response to a message received from the primary LU because an error was found in the message, or the application responded negatively to a chain for which the end-of-chain has arrived:

LUA_MODE_INCONSISTENCY

Secondary return code; performing this function is not allowed by the current status. The request sent to the half-session component was not executed even though it was understood and supported. This SNA sense code is also an exception request sense code.

LUA_FUNCTION_NOT_SUPPORTED

Secondary return code; the LUA does not support the requested function. A control character, an RU parameter, or a formatted request code may have specified the function. Specific sense code information is in bytes 2 and 3.

LUA_DATA_TRAFFIC_RESET

Secondary return code; a half-session of an active session but with inactive data traffic received a normal flow DFC or FMD request. An invalid request header or request unit for the receiver’s current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_DATA_TRAFFIC_NOT_RESET

Secondary return code; while the data traffic state was not reset, the session control request was received. An invalid request header or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_SC_PROTOCOL_VIOLATION

Secondary return code; a violation of SC protocol occurred. A request (that is permitted only after an SC request and a positive response to that request have been successfully exchanged) was received before the required exchange. Byte 4 of the sense data contains the request code. No user data exists for this sense code. An invalid header request or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_INVALID_SC_OR_NC_RH

Secondary return code; the RH of an SC or NC request was invalid.

LUA_PACING_NOT_SUPPORTED

Secondary return code; the request contained a pacing indicator when support of pacing for this session does not exist for the receiving half-session or boundary function half-session. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_NAU_INOPERATIVE

Secondary return code; the network addressable unit is not able to process responses or requests. Delivery to the receiver could not take place for one of the following reasons:

A path information unit error

A path outage

An invalid sequence of requests for activation

If a path error is received during an active session, it usually means there is no longer a valid path to the session partner.

LUA_CANCELED

Primary return code; the secondary return code gives the reason for canceling the command:

LUA_PURGED

Secondary return code; SLI_PURGE was issued and canceled SLI_RECEIVE.

LUA_NO_SLI_SESSION

Secondary return code; a session was not open or was down due to an SLI_CLOSE or session failure when a command was issued.

LUA_CANCEL_COMMAND_RECEIVED

Secondary return code; the host sent an SNA CANCEL command to cancel the data chain currently being received by SLI_RECEIVE.

LUA_TERMINATED

Secondary return code; the session was terminated when a verb was pending. The verb process has been canceled.

LUA_IN_PROGRESS

Primary return code; an asynchronous command was received but is not completed.

LUA_STATUS

Primary return code; the secondary return code contains SLI status information for the application:

LUA_READY

Secondary return code; following a NOT READY status, this status is issued to notify you that the SLI is ready to process commands.

LUA_NOT_READY

Secondary return code; the SLI session is temporarily suspended for the following reason:

An SNA UNBIND type X'02' command was received, which means a new BIND is coming. If the UNBIND type X'02' is received after the beginning SLI_OPEN is complete, the session is suspended until a BIND, optional CRV and STSN, and SDT flows are received. These routines are re-entrant because they have to be called again. The session resumes after the SLI processes the SDT command. If the UNBIND type X'02' is received while the SLI_OPEN is still processing, the primary return code is session-failure, not status.

The receipt of an SNA CLEAR caused the suspension. Receipt of an SNA SDT will cause the session to resume.

LUA_INIT_COMPLETE

Secondary return code; the LUA interface initialized the session while SLI_OPEN was processing. LUA applications that issue SLI_OPEN with lua_open_type_prim_sscp receive this status on SLI_RECEIVE or SLI_BID.

LUA_SESSION_END_REQUESTED

Secondary return code; the LUA interface received an SNA SHUTD from the host, which means the host is ready to shut down the session.

LUA_COMM_SUBSYSTEM_ABENDED

Primary return code; indicates one of the following conditions:

The node used by this conversation encountered an ABEND.

The connection between the TP and the PU 2.1 node has been broken (a LAN error).

The SnaBase at the TP’s computer encountered an ABEND.

LUA_COMM_SUBSYSTEM_NOT_LOADED

Primary return code; a required component could not be loaded or has terminated while processing the verb. Thus, communication could not take place. Contact the system administrator for corrective action.

LUA_INVALID_VERB_SEGMENT

Primary return code; the VCB extended beyond the end of the data segment.

LUA_UNEXPECTED_DOS_ERROR

Primary return code; after issuing an operating system call, an unexpected operating system return code was received and is specified in the secondary return code.

LUA_STACK_TOO_SMALL

Primary return code; the stack size of the application is too small to execute the verb. Increase the stack size of your application.

LUA_INVALID_VERB

Primary return code; either the verb code or the operation code, or both, is invalid. The verb did not execute.

Remarks

SLI_RECEIVE receives responses, SNA commands, and request unit data from the host. SLI_RECEIVE also provides the status of the session to the Windows LUA application. An SLI_OPEN request must complete before SLI_RECEIVE can be issued. However, if SLI_OPEN is issued with lua_init_type set to LUA_INIT_TYPE_PRIM_SSCP, an SLI_RECEIVE over the SSCP normal flow may be issued as soon as SLI_OPEN returns an IN_PROGRESS.

Data is received by the application in one of four session flows. The four session flows, from highest to lowest priority are:

SSCP expedited

LU expedited

SSCP normal

LU normal

The data flow type that SLI_RECEIVE will process is specified in lua_flag1. The application can also specify whether it wants to look at more than one type of data flow. When multiple flow bits are set, the highest priority is received first. When SLI_RECEIVE completes processing, lua_flag2 indicates the specific type of flow for which data has been received by the Windows LUA application.

If SLI_BID successfully completes before SLI_RECEIVE is issued, the Windows LUA interface can be instructed to reuse the last SLI_BID verb’s VCB. To do this, issue SLI_RECEIVE with lua_flag1.bid_enable set.

When using lua_flag1.bid_enable, the SLI_BID storage must not be freed since the last SLI_BID verb’s VCB is used. Also, when using lua_flag1.bid_enable, the successful completion of SLI_BID will be posted.

If SLI_RECEIVE is issued with lua_flag1.nowait when no data is available to receive, LUA_NO_DATA will be the secondary return code set by the Windows LUA interface.

Session Status Return Codes

If LUA_STATUS is the primary return code, the secondary return code may be LUA_READY, LUA_NOT_READY, LUA_SESSION_END_REQUESTED, or LUA_INIT_COMPLETE. In addition, if LUA_STATUS is the primary return code, the following parameters are used:

lua_sec_rc

lua_sid

LUA_READY is returned after an LUA_NOT_READY status and indicates that the SLI is again ready to perform all commands.

LUA_NOT_READY indicates that the SLI session is suspended because the SLI has received either an SNA CLEAR command or an SNA UNBIND command with an X'02' UNBIND type (UNBIND with BIND forthcoming). Depending on what caused the suspension, the session can be reactivated as follows:

When the suspension is caused by an SNA CLEAR, receiving an SNA SDT reactivates the session.

When an SNA UNBIND type BIND forthcoming causes suspension of the session and the SLI_OPEN that opened the session is completed, the session is suspended until the SLI receives a BIND and SDT command. The session can also optionally receive an STSN command. As a result, user-supplied routines issued with the initial SLI_OPEN must be re-entered because they will be recalled.

The application can send SSCP data after a CLEAR or UNBIND type BIND forthcoming arrives and before the NOT READY status is read. The application can send and receive SSCP data after reading a NOT READY.

When an SNA UNBIND type BIND forthcoming arrives before completion of the SLI_OPEN that opened the session, LUA_SESSION_FAILURE (not LUA_STATUS) is the primary return code.

LUA_SESSION_END_REQUESTED indicates that the application received an SNA SHUTD from the host. The Windows LUA application should issue SLI_CLOSE to close the session when convenient.

LUA_INIT_COMPLETE is returned only when lua_init_type for SLI_OPEN is LUA_INIT_TYPE_PRIM_SSCP. The status means that the SLI_OPEN has been processed sufficiently to allow SSCP data to now be sent or received.

Exception Requests

If a host application request unit is converted into an EXR, sense data will be returned. When SLI_BID completes with the following returned verb parameters set as shown, an EXR conversion occurs:

Parameter	Set to

lua_prim_rc	OK (X'0000')

lua_sec_rc	OK (X'00000000')

lua_rh.rri	bit off (request unit)

lua_rh.sdi	bit on (includes sense data)

Of the 7 bytes of data in lua_peek_data, bytes 0 through 3 define the error detected. The following table indicates possible sense data and the values of bytes 0 through 3.

Sense data	Value of bytes 0 – 3
LUA_MODE_INCONSISTENCY	X08090000
LUA_BRACKET_RACE_ERROR	X080B0000
LUA_BB_REJECT_NO_RTR	X08130000
LUA_RECEIVER_IN_TRANSMIT_MODE	X081B0000
LUA_CRYPTOGRAPHY_FUNCTION_INOP	X08480000
LUA_SYNC_EVENT_RESPONSE	X10010000
LUA_RU_DATA_ERROR	X10020000
LUA_RU_LENGTH_ERROR	X10020000
LUA_INCORRECT_SEQUENCE_NUMBER	X20010000
The information returned to bytes 3 through 6 in lua_peek_data is determined by the first 3 bytes of the initial request unit that caused the error.


SLI_SEND
LUA SLI Verbs	7 of 9

SLI_SEND

Sends responses, SNA commands, and data from a Windows LUA application to a host LU.

Syntax

lua_verb	unsigned short int

lua_verb_length	unsigned short int

lua_opcode	unsigned short int

lua_correlator	unsigned long int

lua_luname	unsigned char

lua_sid	unsigned long int

lua_data_length	unsigned int

lua_data_ptr	char far *

lua_post_handle	unsigned long int

lua_th.snf	struct (unsigned char)

lua_rh	unsigned char

lua_message_type	unsigned char

lua_flag1.sscp_exp	struct (unsigned char)

lua_flag1.sscp_norm	struct (unsigned char)

lua_flag1.lu_exp	struct (unsigned char)

lua_flag1.lu_norm	struct (unsigned char)

lua_data_length	unsigned long int

lua_prim_rc	unsigned short int

lua_sec_rc	unsigned long int

lua_th	struct (unsigned char)

lua_flag2.async	struct (unsigned char)

lua_flag2.sscp_exp	struct (unsigned char)

lua_flag2.sscp_norm	struct (unsigned char)

lua_flag2.lu_exp	struct (unsigned char)

lua_flag2.lu_norm	struct (unsigned char)

lua_sequence_number	unsigned char

Parameter	Description

lua_verb	Supplied parameter; LUA_VERB_SLI.

lua_verb_length	Supplied parameter; specifies the length, in bytes, of the LUA VCB. It must contain the length of the verb being issued.

lua_opcode	Supplied parameter; LUA_OPCODE_SLI_SEND.

lua_correlator	Supplied parameter; a user-supplied value that links the verb with other user-supplied information. This parameter is neither examined nor modified by the Windows LUA interface.

lua_luname	Supplied parameter; specifies the ASCII name of the local LU used by the Windows LUA session.

SLI_OPEN and RUI_INIT require this parameter. Other Windows LUA verbs require this parameter only if lua_sid is 0.

This parameter is 8 bytes long; pad on the right with spaces, X'20', if the name is shorter than 8 characters.

lua_sid	Supplied/returned parameter; specifies the session ID and is returned by SLI_OPEN and RUI_INIT. Other verbs use this parameter to identify the session used for the command. If other verbs use lua_luname to identify sessions, set lua_sid to 0.

lua_data_length	Supplied parameter; specifies the length of the data being sent or received.

lua_data_ptr	Supplied parameter; points to the application data buffer. Both SNA commands and data are placed in this buffer and they can be in an EBCDIC format.

When SLI_RECEIVE or RUI_READ is issued, this parameter points to the location to receive the data from the host.

When SLI_SEND or RUI_WRITE is issued, this parameter points to the location of the application’s data to be sent to the host.

When SLI_PURGE or RUI_PURGE is issued, this parameter points to the location of the SLI_RECEIVE or RUI_READ verb’s VCB that is to be canceled.

When SLI_OPEN is issued, this parameter can be one of the following:

   The LOGON message for the SSCP normal flow when the initialization type is secondary with an unformatted LOGON message.

   The RU for INITSELF. When the initialization type is secondary with INITSELF, the necessary data for the application is provided.

   For all other open types, this field should be set to 0.

This information is provided by the Windows LUA application.

lua_post_handle	Supplied parameter; for the Windows NT system, if asynchronous notification is to be accomplished by events, lua_post_handle contains the handle of the event to be signaled.

lua_th.snf	Supplied parameter; specifies the sequence number of the RU (not byte-reversed). The fifth and sixth bytes of lua_th.

lua_rh	Supplied/returned parameter; supplies the information from the SNA RH of the message. It is set for the write function and returned by the read and bid functions. For a list of the bit masks that apply to this parameter, see Appendix B, “Verb Control Block.”

lua_message_type	Supplied parameter; supplies the type of SNA data or command sent to the host. Possible values are as follows:

LUA_MESSAGE_TYPE_LU_DATA

LUA_MESSAGE_TYPE_SSCP_DATA

LUA_MESSAGE_TYPE_RSP

LUA_MESSAGE_TYPE_BID

LUA_MESSAGE_TYPE_BIS

LUA_MESSAGE_TYPE_CANCEL

LUA_MESSAGE_TYPE_CHASE

LUA_MESSAGE_TYPE_LUSTAT_LU

LUA_MESSAGE_TYPE_LUSTAT_SSCP

LUA_MESSAGE_TYPE_QC

LUA_MESSAGE_TYPE_QEC

LUA_MESSAGE_TYPE_RELQ

LUA_MESSAGE_TYPE_RQR

LUA_MESSAGE_TYPE_RTR

LUA_MESSAGE_TYPE_SBI

LUA_MESSAGE_TYPE_SIGNAL

The SLI receives and responds to the BIND and STSN requests through the LUA interface extension routines.

LU-DATA, LUSTAT_LU, LUSTAT_SSCP, and SSCP_DATA are not SNA commands.

lua_flag1.sscp_exp	Supplied parameter; flag indicates SSCP expedited flow.

lua_flag1.sscp_norm	Supplied parameter; flag indicates SSCP normal flow.

lua_flag1.lu_exp	Supplied parameter; flag indicates LU expedited flow.

lua_flag1.lu_norm	Supplied parameter; flag indicates LU normal flow.

lua_data_length	Returned parameter; specifies the length of the data being sent or received.

lua_th	Returned parameter; supplies the information from the SNA TH of the received message. For a list of the subparameters that apply to this parameter, see Appendix B, “Verb Control Block.”

lua_flag2.async	Returned parameter; set to 1 if the LUA interface verb completed asynchronously.

lua_flag2.sscp_exp	Returned parameter; flag indicates flag indicates SSCP expedited flow.

lua_flag2.sscp_norm	Returned parameter; flag indicates flag indicates SSCP normal flow.

lua_flag2.lu_exp	Returned parameter; flag indicates flag indicates LU expedited flow.

lua_flag2.lu_norm	Returned parameter; flag indicates flag indicates LU normal flow.

lua_sequence_number	Returned parameter; contains the sequence number for either the first in the chain request unit or the only segment in the chain request unit. Note that this parameter is not byte-reversed.

Return Codes

LUA_OK

Primary return code; the verb executed successfully:

LUA_SEC_OK

Secondary return code; no additional information exists for LUA_OK.

LUA_PARAMETER_CHECK

Primary return code; the verb did not execute because of a parameter error:

LUA_INVALID_LUNAME

Secondary return code; an invalid lua_luname was specified.

LUA_BAD_SESSION_ID

Secondary return code; an invalid value for lua_sid was specified in the VCB.

LUA_BAD_DATA_PTR

Secondary return code; the lua_data_ptr parameter either does not contain a valid pointer or does not point to a read/write segment and supplied data is required.

LUA_RESERVED_FIELD_NOT_ZERO

Secondary return code; a reserved parameter for the verb just issued is not set to 0.

LUA_INVALID_POST_HANDLE

Secondary return code; for a Windows NT system using events as the asynchronous posting method, the Windows LUA VCB does not contain a valid event handle.

For the Windows version 3. x system, the LUA VCB does not contain the valid procedure address returned by the MakeProcInstance command.

For OS/2, the LUA VCB does not contain a valid semaphore or queue handle, which is needed when a verb completes asynchronously.

LUA_INVALID_FLOW

Secondary return code; the lua_flag1 flow flags were set incorrectly when a verb was issued:

When issuing SLI_SEND to send an SNA response, set only one lua_flag1 flow flag.

When issuing SLI_RECEIVE, set at least one lua_flag1 flow flag.

LUA_VERB_LENGTH_INVALID

Secondary return code; an LUA verb was issued with a value for lua_verb_length unexpected by the LUA.

LUA_REQUIRED_FIELD_MISSING

Secondary return code; the verb that was issued either did not include a data pointer (if the data count was not 0) or did not include an lua_flag1 flow flag.

LUA_INVALID_MESSAGE_TYPE

Secondary return code; the lua_message_type parameter is not recognized by the LUA interface.

LUA_DATA_LENGTH_ERROR

Secondary return code; the application did not provide user-supplied data required by the verb issued. Note that when SLI_SEND is issued for an SNA LUSTAT command, status (in 4 bytes) is required, and that when SLI_OPEN is issued with secondary initialization, data is required.

LUA_STATE_CHECK

Primary return code; the verb did not execute because it was issued in an invalid state:

LUA_NO_SLI_SESSION

Secondary return code; a session was not open or was down due to an SLI_CLOSE or session failure when a command was issued.

LUA_MAX_NUMBER_OF_SENDS

Secondary return code; the application issued a third SLI_SEND before one completed.

LUA_SEND_ON_FLOW_PENDING

Secondary return code; an SLI_SEND was still outstanding when the application issued another SLI_SEND for an SNA flow.

LUA_SESSION_FAILURE

Primary return code; an error condition, specified in the secondary return code, caused the session to fail:

LUA_RECEIVED_UNBIND

Secondary return code; the primary LU sent an SNA UNBIND command to the LUA interface when a session was active. As a result, the session was stopped.

LUA_SLI_LOGIC_ERROR

Secondary return code; the LUA interface found an internal error in logic.

LUA_NO_RUI_SESSION

Secondary return code; no session has been initialized for the LUA verb issued, or some verb other than SLI_OPEN was issued before the session was initialized.

LUA_LU_COMPONENT_DISCONNECTED

Secondary return code; an LU component is unavailable because it is not connected properly. Make sure that the power is on.

LUA_DATA_SEGMENT_LENGTH_ERROR

Secondary return code; one of the following has occurred:

The supplied data segment for SLI_RECEIVE or SLI_SEND is not a read/write data segment as required.

The supplied data segment for SLI_RECEIVE is not as long as that provided in lua_max_length.

The supplied data segment for SLI_SEND is not as long as that provided in lua_data_length.

LUA_VERB_RECORD_SPANS_SEGMENTS

Secondary return code; the LUA VCB length parameter plus the segment offset is beyond the segment end.

LUA_NOT_ACTIVE

Secondary return code; LUA was not active within SNA Server when an LUA verb was issued.

LUA_SLI_LOGIC_ERROR

Secondary return code; the LUA interface found an internal error in logic.

LUA_INVALID_PROCESS

Secondary return code; the session for which an LUA verb was issued is unavailable because another OS/2 process owns the session.

LUA_LU_INOPERATIVE

Secondary return code; a severe error occurred while the LUA was attempting to stop the session. This LU is unavailable for any LUA requests until an ACTLU is received from the host.

LUA_MODE_INCONSISTENCY

Secondary return code; performing this function is not allowed by the current status. The request sent to the half-session component was not executed even though it was understood and supported. This SNA sense code is also an exception request sense code.

LUA_INSUFFICIENT_RESOURCES

Secondary return code; a temporary condition of insufficient resources caused the request receiver to be unable to perform. The request sent to the half-session component was not executed, even though it was understood and supported.

LUA_SEND_CORRELATION_TABLE_FULL

Secondary return code; the session send correlation table for the flow requested reached its capacity.

LUA_RU_LENGTH_ERROR

Secondary return code; the RU request was an incorrect length (either too short or too long). The request unit was not interpreted or processed even though it was delivered to the half-session component. The half-session capabilities do not match. This SNA sense code is also an exception request sense code.

LUA_FUNCTION_NOT_SUPPORTED

Secondary return code; LUA does not support the requested function. A control character, an RU parameter, or a formatted request code may have specified the function. Specific sense code information is in bytes 2 and 3.

LUA_HDX_BRACKET_STATE_ERROR

Secondary return code; the existing state error prevented the current request from being sent. The determination was made by a protocol computer.

LUA_RESPONSE_ALREADY_SENT

Secondary return code; a response for the chain was already sent so that the current request was not sent. The determination was made by a protocol computer.

LUA_EXR_SENSE_INCORRECT

Secondary return code; the application responded negatively to an exception request. The sense code was unacceptable.

LUA_RESPONSE_OUT_OF_ORDER

Secondary return code; the current response was not for the oldest request. The determination was made by a protocol computer.

LUA_CHAIN_RESPONSE_REQUIRED

Secondary return code; a CHASE response was still outstanding when a more recent request was attempted. The determination was made by a protocol computer.

LUA_BRACKET

Secondary return code; the sender failed to enforce the session bracket rules. Note that contention and race conditions are exempt from this error. An invalid request header or request unit for the receiver’s current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_DIRECTION

Secondary return code; while the half-duplex flip-flop state was NOT_RECEIVE, a request for normal flow was received. An invalid request header or request unit for the receiver’s current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_DATA_TRAFFIC_RESET

Secondary return code; a half-session of an active session but with inactive data traffic received a normal flow DFC or FMD request. An invalid request header or request unit for the receiver’s current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_DATA_TRAFFIC_QUIESCED

Secondary return code; a DFC or FMD request was received from a half-session that sent either a SHUTC command or QC command, and the DFC or FMD request has not responded to a RELQ command. An invalid request header or request unit for the receiver’s current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_DATA_TRAFFIC_NOT_RESET

Secondary return code; while the data traffic state was not reset, the session control request was received. An invalid request header or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_NO_BEGIN_BRACKET

Secondary return code; the receiver has already sent a positive response to a BIS command when a BID or an FMD request specifying BBI=BB was received. An invalid request header or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_SC_PROTOCOL_VIOLATION

Secondary return code; a violation of SC protocol occurred. A request (that is permitted only after an SC request and a positive response to that request have been successfully exchanged) was received before the required exchange. Byte 4 of the sense data contains the request code. No user data exists for this sense code. An invalid header request or data flow control state was found. Delivery to the half-session component was prevented.

LUA_IMMEDIATE_REQUEST_MODE_ERROR

Secondary return code; the request violated the immediate request mode protocol. An invalid header request or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_QUEUED_RESPONSE_ERROR

Secondary return code; the request violated the queued response protocol. An invalid header request or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_ERP_SYNC_EVENT_ERROR

Secondary return code; a violation of the ERP synchronous event protocol occurred. An invalid header request or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_RSP_BEFORE_SENDING_REQ

Secondary return code; a previously received request has not been responded to yet and an attempt was made in half-duplex send/receive mode to send a normal flow request. An invalid header request or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

LUA_RSP_CORRELATION_ERROR

Secondary return code; a response was sent that does not correspond to a previously received request or a response was received that does not correspond to a previously sent request.

LUA_BB_NOT_ALLOWED

Secondary return code; the begin bracket indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_EB_NOT ALLOWED

Secondary return code; the end bracket indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_EXCEPTION_RSP_NOT_ALLOWED

Secondary return code; when an exception response was not allowed, one was requested. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_DEFINITE_RSP_NOT_ALLOWED

Secondary return code; when a definite response was not allowed, one was requested. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_CD_NOT_ALLOWED

Secondary return code; the change-direction indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_NO_RESPONSE_NOT_ALLOWED

Secondary return code; a request other than an EXR contained a “no response.” The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_CHAINING_NOT_SUPPORTED

Secondary return code; the chaining indicators were incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_BRACKETS_NOT_SUPPORTED

Secondary return code; the bracket indicators were incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_CD_NOT_SUPPORTED

Secondary return code; the change-direction indicator was set, but LUA does not support change-direction for this situation. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_USE_OF_FI

Secondary return code; the format indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_ALTERNATE_CODE_NOT_SUPPORTED

Secondary return code; the code selection indicator was set, but LUA does not support code selection for this session. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_REQUEST_CODE

Secondary return code; the request code was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_SPEC_OF_SDI_RTI

Secondary return code; the SDI and the RTI were not specified correctly on a response. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_DR1I_DR2I-ERI

Secondary return code; the DR1I, the DR2I, and the ERI were specified incorrectly. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_USE_OF QRI

Secondary return code; the queued response indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_USE_OF_EDI

Secondary return code; the EDI was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_INCORRECT_USE_OF_PDI

Secondary return code; the PDI was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

LUA_NO_SESSION

Secondary return code; a request to activate a session is required because no active half-session in the receiving end node for the origination-destination pair exists, or no active boundary function half-session component for the origination-destination pair in a node that supplies the boundary function exists. Delivery of the request could not take place for one of the following reasons:

A path information unit error

A path outage

An invalid sequence of requests for activation

If a path error is received during an active session, that usually indicates there is no longer a valid path to the session partner.

LUA_CANCELED

Primary return code; the secondary return code gives the reason for canceling the command:

LUA_TERMINATED

Secondary return code; the session was terminated when a verb was pending. The verb process has been canceled.

LUA_IN_PROGRESS

Primary return code; an asynchronous command was received but is not completed.

LUA_COMM_SUBSYSTEM_ABENDED

Primary return code; indicates one of the following conditions:

The node used by this conversation encountered an ABEND.

The connection between the TP and the PU 2.1 node has been broken (a LAN error).

The SnaBase at the TP’s computer encountered an ABEND.

LUA_COMM_SUBSYSTEM_NOT_LOADED

Primary return code; a required component could not be loaded or has terminated while processing the verb. Thus, communication could not take place. Contact the system administrator for corrective action.

LUA_INVALID_VERB_SEGMENT

Primary return code; the VCB extended beyond the end of the data segment.

LUA_UNEXPECTED_DOS_ERROR

Primary return code; after issuing an operating system call, an unexpected operating system return code was received and is specified in the secondary return code.

LUA_STACK_TOO_SMALL

Primary return code; the stack size of the application is too small to execute the verb. Increase the stack size of your application.

LUA_INVALID_VERB

Primary return code; either the verb code or the operation code, or both, is invalid. The verb did not execute.

Remarks

SLI_SEND sends responses, SNA commands, and data from the Windows LUA application to a host LU. A session must already be open to issue SLI_SEND for a particular LU-LU session flow. To send data on the SSCP normal flow prior to the completion of SLI_OPEN, the session must have been initialized as primary with SSCP access. In addition, the session status must be INIT_COMPLETE.

The settings for lua_message_type determine the type of processing that will be done by SLI_SEND. The following table indicates the parameters to set based on the value of lua_message_type.

SLI_SEND Parameter Settings Based on lua_message_type

SLI_SEND parameter		LU_DATA SSCP_DATA		BID BIS RTR	CHASE QC	LUSTAT_LU LUSTAT_SSCP		QEC RELQ SBI SIGNAL	RQR	RSP
lua_data_length		Req.		0	0	Req.		0	0	Req. (0 ifno data)
lua_data_ptr		Req. (0 ifno data)		0	0	Req.		0	0	Req. (0 ifno data)
lua_flag1 flow flags		0		0	0	0		0	0	Req. (setone)
lua_rh		FIDRL1 DRL2R IBBIEB ICDICS IEDI		SDIQRI	SDIQRIE BICDI	SDIQRID RL1DRL2 RIBBIEBI CDI		SDI	0	RRIRI
lua_th		0		0	0	0		0	0	SNF

The location provided in lua_data_ptr and the length provided in lua_data_length determines the data that the SLI sends. The data will be chained by the SLI verbs if necessary.

When sending a response, the type of response determines the SLI_SEND information required. For all responses, you must:

Set the selected lua_flag1 flow flag.

Provide the sequence number in lua_th.snf for the request to which you are responding.

Set lua_message_type to LUA_MESSAGE_TYPE_RSP.

For multichain message responses, the sequence number of the last received chain element must be used. For a response to a multichain message ending with a CANCEL command, the CANCEL command sequence number is used.

For positive responses that only require the request code, set lua_rh.ri to 0 (indicating that the response is positive) and lua_data_length to 0 (indicating no data is provided). The request code is filled in by the SLI, using the sequence number provided.

For negative responses in which lua_rh.ri is set to 1, set the lua_data_ptr to the SNA sense code address and the lua_data_length to the SNA sense code length (4 bytes). The sequence number is used by the SLI to fill in the request code.


SLI_BIND_ROUTINE
LUA SLI Verbs	8 of 9

SLI_BIND_ROUTINE

Notifies the Windows LUA application that a BIND request has come from the host and allows the user-supplied routine to examine the request and formulate a response.

Syntax

lua_verb	unsigned short int

lua_verb_length	unsigned short int

lua_opcode	unsigned short int

lua_luname	unsigned char

lua_sid	unsigned long int

lua_data_length	unsigned int

lua_data_ptr	char far *

lua_th	struct (unsigned char)

lua_rh	unsigned char

lua_sec_rc	unsigned long int

lua_prim_rc	unsigned short int

lua_message_type	unsigned short int

Parameter	Description

lua_verb	Supplied parameter; LUA_VERB_SLI.

lua_verb_length	Supplied parameter; specifies the length, in bytes, of the LUA VCB. It must contain the length of the verb being issued.

lua_opcode	Supplied parameter; LUA_OPCODE_SLI_BIND_ROUTINE.

lua_luname	Supplied parameter; specifies the ASCII name of the local LU used by the Windows LUA session.

SLI_OPEN and RUI_INIT require this parameter. Other Windows LUA verbs require this parameter if lua_sid is 0.

This parameter is 8 bytes long; pad on the right with spaces, X'20', if the name is shorter than 8 characters.

lua_sid	Supplied parameter; specifies the session ID and is returned by SLI_OPEN and RUI_INIT. Other verbs use this parameter to identify the session used for the command. If other verbs use lua_luname to identify sessions, set lua_sid to 0.

lua_data_length	Supplied/returned parameter; specifies the length of the data being sent or received.

lua_data_ptr	Supplied parameter; points to the application data buffer. Both SNA commands and data are placed in this buffer and they can be in an EBCDIC format.

When SLI_RECEIVE or RUI_READ is issued, this parameter points to the location to receive the data from the host.

When SLI_SEND or RUI_WRITE is issued, this parameter points to the location of the application’s data to be sent to the host.

When SLI_PURGE or RUI_PURGE is issued, this parameter points to the location of the SLI_RECEIVE or RUI_READ verb’s VCB that is to be canceled.

When SLI_OPEN is issued, this parameter can be one of the following:

   The LOGON message for the SSCP normal flow when the initialization type is secondary with an unformatted LOGON message.

   The RU for INITSELF. When the initialization type is secondary with INITSELF, the necessary data for the application is provided.

   For all other open types, this field should be set to 0.

This information is provided by the Windows LUA application.

lua_th	Supplied parameter; supplies the information from the SNA TH of the received message. Various subparameters are to be set for write functions and returned for read functions. For a list of the subparameters that apply to this parameter, see Appendix B, “Verb Control Block.”

lua_rh	Supplied parameter; supplies the information from the SNA RH of the message to send. It is set for the write function and returned by the read and bid functions. For a list of the bit masks that apply to this parameter, see Appendix B, “Verb Control Block.”

lua_message_type	Supplied parameter; supplies the type of SNA data or command sent to the host. For a list of the possible values for this parameter, see Appendix B, “Verb Control Block.”

Return Codes

LUA_OK

Primary return code; the verb executed successfully:

LUA_SEC_OK

Secondary return code; no additional information exists for LUA_OK.

LUA_NEGATIVE_RSP

Primary return code; either the LUA sent a negative response to a message received from the primary LU because an error was found in the message, or the application responded negatively to a chain for which the end-of-chain has arrived.

Remarks

SLI_BIND_ROUTINE provides a mechanism for the Windows LUA application to examine BIND requests that are received from the host. The Windows LUA uses a user-supplied DLL to notify the Windows LUA application that a BIND request has been received. The user-supplied DLL routine then examines the contents of the BIND and formulates a response for the request.

The DLL name for the routine is provided as extensions of the SLI_OPEN verb’s VCB. The lua_extension_list_offset parameter provides the offset from the start of the VCB to the first name in the extension list.

The Windows LUA interface assigns storage space where the VCB is structured. The VCB of SLI_BIND_ROUTINE contains lua_th and lua_rh. The address of the BIND RU is specified in lua_data_ptr and the length of the RU is specified in lua_data_length.

When SLI_BIND_ROUTINE returns to the Windows LUA, processing of SLI_BIND_ROUTINE is completed. The BIND response should overwrite the BIND RU. When the BIND is accepted, the primary return code should be set to LUA_OK. If the BIND is rejected, the primary return code should be set to LUA_NEGATIVE_RSP and the BIND buffer contains the negative sense code. The lua_data_ptr parameter should not be modified.

If a negative response is returned from SLI_BIND_ROUTINE, SLI_OPEN is canceled. The lua_prim_rc of the SLI_OPEN is set to LUA_SESSION_FAILURE, and the lua_sec_rc is set to LUA_NEG_RSP_FROM_BIND_ROUTINE.


SLI_STSN_ROUTINE
LUA SLI Verbs	9 of 9

SLI_STSN_ROUTINE

Notifies the Windows LUA application that an STSN command has come from the host and allows the user-supplied routine to examine the request and formulate a response.

Syntax

lua_verb	unsigned short int

lua_verb_length	unsigned short int

lua_opcode	unsigned short int

lua_luname	unsigned char

lua_sid	unsigned long int

lua_data_length	unsigned int

lua_data_ptr	char far *

lua_th	struct (unsigned char)

lua_rh	unsigned char

lua_message_type	unsigned short int

lua_prim_rc	unsigned short int

lua_sec_rc	unsigned long int

Parameter	Description

lua_verb	Supplied parameter; LUA_VERB_SLI.

lua_verb_length	Supplied parameter; specifies the length, in bytes, of the LUA VCB. It must contain the length of the verb being issued.

lua_opcode	Supplied parameter; LUA_OPCODE_SLI_STSN_ROUTINE.

lua_luname	Supplied parameter; specifies the ASCII name of the local LU used by the Windows LUA session.

SLI_OPEN and RUI_INIT require this parameter. Other Windows LUA verbs require this parameter only if lua_sid is 0.

This parameter is 8 bytes long; pad on the right with spaces, X'20', if the name is shorter than 8 characters.

lua_sid	Supplied parameter; specifies the session and is returned by SLI_OPEN and RUI_INIT. Other verbs use this parameter to identify the session used for the command. If other verbs use lua_luname to identify sessions, set lua_sid to 0.

lua_data_length	Supplied/returned parameter; specifies the length of the data being sent or received.

lua_data_ptr	Supplied parameter; points to the application data buffer. Both SNA commands and data are placed in this buffer and they can be in an EBCDIC format.

When SLI_RECEIVE or RUI_READ is issued, this parameter points to the location to receive the data from the host.

When SLI_SEND or RUI_WRITE is issued, this parameter points to the location of the application’s data to be sent to the host.

When SLI_PURGE or RUI_PURGE is issued, this parameter points to the location of the SLI_RECEIVE or RUI_READ verb’s VCB that is to be canceled.

When SLI_OPEN is issued, this parameter can be one of the following:

   The LOGON message for the SSCP normal flow when the initialization type is secondary with an unformatted LOGON message.

   The RU for INITSELF. When the initialization type is secondary with INITSELF, the necessary data for the application is provided.

   For all other open types, this field should be set to 0.

This information is provided by the Windows LUA application.

lua_th	Supplied parameter; supplies the information from the SNA TH of the received message. Various subparameters are to be set for write functions and returned for read functions. For a list of the subparameters that apply to this parameter, see Appendix B, “Verb Control Block.”

lua_rh	Supplied parameter; supplies the information from the SNA RH of the message to send. It is set for the write function and returned by the read and bid functions. For a list of the bit masks that apply to this parameter, see Appendix B, “Verb Control Block.”

lua_message_type	Supplied parameter; supplies the type of SNA data or command sent to the host. For a list of the possible values for this parameter, see Appendix B, “Verb Control Block.”

Return Codes

LUA_OK

Primary return code; the verb executed successfully:

LUA_SEC_OK

Secondary return code; no additional information exists for LUA_OK.

LUA_NEGATIVE_RSP

Primary return code; either the LUA sent a negative response to a message received from the primary LU because an error was found in the message, or the application responded negatively to a chain for which the end-of-chain has arrived.

Remarks

SLI_STSN_ROUTINE provides a mechanism for the Windows LUA application to examine and respond to STSN commands. The Windows LUA notifies the Windows LUA application that an STSN command has been received from the host. This is done through a user-supplied DLL. The user’s DLL examines the STSN request and formulates a response to the request.

The DLL name for the routine is provided as extensions of the SLI_OPEN verb’s VCB. The lua_extension_list_offset parameter provides the offset from the start of the VCB to the first name in the extension list.

The Windows LUA interface assigns storage space where the VCB is structured. The VCB of the SLI_STSN_ROUTINE contains lua_th and lua_rh. The address of the STSN RU is specified in lua_data_ptr and the length of the RU is specified in lua_data_length.

When SLI_STSN_ROUTINE returns to the Windows LUA, processing of the SLI_STSN_ROUTINE is completed. The STSN response should overwrite the STSN RU. When the STSN is accepted, the primary return code should be set to LUA_OK. If the STSN is rejected, the primary return code should be set to LUA_NEGATIVE_RSP and the STSN buffer contains the negative sense code. The lua_data_ptr parameter should not be modified.

If a negative response is returned from SLI_STSN_ROUTINE, SLI_OPEN is canceled. The lua_prim_rc of the SLI_OPEN is set to LUA_SESSION_FAILURE, and the lua_sec_rc is set to LUA_NEG_RSP_FROM_STSN_ROUTINE.


Extensions for the Windows Environment
Chapter 5	1 of 6

Extensions for the Windows Environment

The extensions described in this chapter have been designed for all implementations and versions of the Microsoft Windows graphical environment version 3.0 or later. They provide support for maximum Windowsbased programming compatibility and optimum application performance in both 16bit and 32bit operating environments.

Windows LUA allows multithreaded Windows-based processes. A process contains one or more threads of execution. The 16bit Windows environment is not multithreaded. In this instance, a task corresponds to a process with a single thread. All references to threads in this document refer to actual threads in multithreaded Windows environments.

This chapter provides, for each extension, a definition of the function, syntax, returns, and remarks for using the extension.


WinRUI( ) / WinSLI( )
Extensions for the Windows Environment	2 of 6

WinRUI( ) / WinSLI( )

Provides asynchronous message notification for all Windowsbased RUI and SLI verbs.

Syntax

int WINAPI WinRUI (hWnd, lpVCB);

int WINAPI WinSLI (hWnd, 1pVCB);

Returns

The function returns a value indicating whether the request was accepted by the Windowsbased RUI or SLI for processing. A returned value of 0 indicates that the request was accepted and will be processed. A value other than 0 indicates an error. Possible error codes are as follows:

WLUAINVALIDHANDLE

The window handle provided is invalid.

WLUASTARTUPNOTCALLED

The application has not initiated a session using WinRUIStartup / WinSLIStartup.

The value returned in lua_flag2.async indicates whether asynchronous notification will occur. If the flag is set (nonzero), asynchronous notification will occur via a message posted to the application’s message queue. If the flag is not set, the request completed synchronously. Examine the primary return code and secondary return code for any error conditions.

Remarks

When the asynchronous operation is complete, the application’s window hWnd receives the message returned by RegisterWindowMessage with "WinRUI" or "WinSLI" as the input string. The lParam argument contains the address of the VCB being posted as complete. The wParam argument is undefined.

Note

It is possible for the request to be accepted for processing (the function call returns 0) but rejected later with a primary return code and secondary return code set in the VCB. Examine the primary return code and secondary return code for any error conditions.

If the application calls WinRUI / WinSLI without first initializing the session using WinRUIStartup / WinSLIStartup, an error is returned.

See Also

RUI/SLI


WinRUICleanup( ) / WinSLICleanup( )
Extensions for the Windows Environment	3 of 6

WinRUICleanup( ) / WinSLICleanup( )

Terminates and deregisters an application from a Windows LUA implementation.

Syntax

BOOL WINAPI WinRUICleanup(void);

BOOL WINAPI WinSLICleanup(void);

Returns

The return value specifies whether the deregistration was successful. If the value is not 0, the application was successfully deregistered. If the value is 0, the application was not deregistered.

Remarks

Use WinRUICleanup / WinSLICleanup to indicate deregistration of a Windows LUA application from a Windows LUA implementation. This function can be used, for example, to free up resources allocated to the specific application.

If WinRUICleanup / WinSLICleanup is called while LUs are in session (RUI_TERM or SLI_CLOSE not issued), the cleanup code should issue an RUI_TERM or SLI_CLOSE close type ABEND for the application for all open sessions.

See Also

WinRUIStartup/WinSLIStartup


WinRUIGetLastInitStatus( )
Extensions for the Windows Environment	4 of 6

WinRUIGetLastInitStatus( )

Enables an application to determine the status of an RUI_INIT, so that the application can evaluate whether the RUI_INIT should be timed out. This extension can be used to initiate the reporting of status, terminate the reporting of status, or find the current status. For details, see the Remarks section.

Syntax

int WINAPI WinRUIGetLastInitStatus (DWORD  dwSid, HANDLE
hStatusHandle, DWORD  dwNotifyType, BOOL  bClearPrevious);

Parameter	Description

dwSid	Specifies the RUI session ID of the session for which status will be determined. If dwSid is 0, hStatusHandle is used to report status on all sessions. Note that the lua_sid parameter in the RUI_INIT VCB is valid as soon as the call to RUI() or WinRUI() for the RUI_INIT returns.

hStatusHandle	Specifies a handle used for signaling the application that the status for the session (specified by dwSid) has changed. Can be a window handle, an event handle, or NULL; dwNotifyType must be set accordingly:

   If hStatusHandle is a window handle, status is sent to the application via a window message. The message is obtained from RegisterWindowMessage using the string WinRUI. The parameter wParam contains the session status (see return codes). Depending on the value of dwNotifyType, lParam contains either the RUI session ID of the session, or the value of lua_correlator from the RUI_INIT verb.

   If hStatusHandle is an event handle, when the status for the session specified by dwSid changes, the event is put into the signaled state. The application must then make a further call to WinRUIGetLastInitStatus() to find out the new status. Note that the event should not be the same as one used for signaling completion of any RUI verb.

   If hStatusHandle is NULL, the status of the session specified by dwSid is returned in the return code. In this case, dwSid must not be 0 unless bClearPrevious is TRUE. If hStatusHandle is NULL, dwNotifyType is ignored.

dwNotifyType	Specifies the type of indication required. This determines the contents of the lParam of the window message, and how WinRUIGetLastInitStatus() interprets hStatusHandle. Allowed values are:

WLUA_NTFY_EVENT
The hStatusHandle parameter contains an event handle.

WLUA_NTFY_MSG_CORRELATOR
The hStatusHandle parameter contains a window handle, and the lParam of the returned window message should contain the value of the lua_correlator field on the RUI_INIT.

WLUA_NTFY_MSG_SID
The hStatusHandle parameter contains a window handle, and the lParam of the returned window message should contain the LUA session identifier.

bClearPrevious	If TRUE, status messages are no longer sent for the session identified by dwSid. If dwSid is 0, status messages are no longer sent for any session. If bClearPrevious is TRUE, hStatusHandle and dwNotifyType are ignored.

Return Codes

WLUASYSNOTREADY

SnaBase is not running.

WLUANTFYINVALID

The dwNotifyType parameter is invalid.

WLUAINVALIDHANDLE

The hStatusHandle parameter does not contain a valid handle.

WLUASTARTUPNOTCALLED

WinRUIStartup has not been called.

WLUALINKINACTIVE

The link to the host is not yet active.

WLUALINKACTIVATING

The link to the host is being activated.

WLUAPUINACTIVE

The link to the host is active, but no ACTPU has yet been received.

WLUAPUACTIVE

An ACTPU has been received.

WLUAPUREACTIVATED

The PU has been reactivated.

WLUALUINACTIVE

The link to the host is active, and an ACTPU has been received, but no ACTLU has been received.

WLUALUACTIVE

The LU is active.

WLUALUREACTIVATED

The LU has been reactivated.

WLUAUNKNOWN

The session is in an unknown status. (This is an internal error.)

WLUAGETLU

The session is waiting for an Open(SSCP) response from the node.

WLUASIDINVALID

The SID specified does not match any known by the RUI.

WLUASIDZERO

The hStatusHandle parameter is NULL and bClearPrevious is FALSE, but dwSid is 0.

WLUAGLOBALHANDLER

The dwSid parameter is 0, and messages from all sessions will be notified. (This is a normal return code, not an error.)

Remarks

This extension is intended to be used either with a window handle or an event handle to enable asynchronous notification of status changes, but it can also be used on its own to find out the current status of a session.

To use this extension with a window handle, you can implement it in one of two ways. One way to use it is as follows:

WinRUIGetLastInitStatus(Sid,Handle,WLUA_NTFY_MSG_CORRELATOR,FALSE);

Another way to use it is as follows:

WinRUIGetLastInitStatus(Sid,Handle,WLUA_NTFY_MSG_SID,FALSE);

With this implementation, changes in status are reported by a window message sent to the window handle specified. If WLUA_NTFY_MSG_CORRELATOR is specified, the lParam field in the window message contains the lua_correlator field for the session. If WLUA_NTFY_MSG_SID is specified, the lParam field in the window message contains the LUA session identifier for the session.

When the extension has been used with a window handle, use the following to cancel the reporting of status:

WinRUIGetLastInitStatus(Sid,NULL,0,TRUE);

For this implementation, note that if Sid is non-zero, status is only reported for that session. If Sid is 0, status is reported for all sessions.

To use this extension with an event handle, implement it as follows:

WinRUIGetLastInitStatus(Sid,Handle,WLUA_NOTIFY_EVENT,FALSE);

The event whose handle is given will be signaled when a change in state occurs. Since no information is returned when an event is signaled, a further call must be issued to find out the status.

Status = WinRUIGetLastInitStatus(Sid,NULL,0,0,FALSE);

Note that in this case, a Sid must be specified.

When the extension has been used with an event handle, use the following to cancel the reporting of status:

WinRUIGetLastInitStatus(Sid,NULL,0,TRUE);

To use this extension to query the current status of a session, it is not necessary to use an event or window handle. Instead, use the following:

Status = WinRUIGetLastInitStatus(Sid,NULL,0,0,FALSE);


WinRUIStartup( ) / WinSLIStartup( )
Extensions for the Windows Environment	5 of 6

WinRUIStartup( ) / WinSLIStartup( )

Allows an application to specify the version of Windows LUA required and to retrieve details of the specific Windows LUA implementation. This function must be called by an application before issuing any further Windows LUA calls to register itself with a Windows LUA implementation.

Syntax

int WINAPI WinRUIStartup (WORD wVersionRequired, LPLUADATA);

int WINAPI WinSLIStartup (WORD wVersionRequired, LPLUADATA);

Parameter	Description

wVersionRequired	Specifies the version of Windows LUA support required. The high-order byte specifies the minor version (revision) number; the low-order byte specifies the major version number.

Returns

The return value specifies whether the application was registered successfully and whether the Windows LUA implementation can support the specified version number. If the value is 0, it was registered successfully and the specified version can be supported. Otherwise, the return value is one of the following:

WLUASYSNOTRERADY

The underlying network subsystem is not ready for network communication.

WLUAVERNOTSUPPORTED

The version of Windows LUA support requested is not provided by this particular Windows LUA implementation.

WLUAINVALID

The Windows LUA version specified by the application is not supported by this DLL.

WLUAFAILURE

A failure occurred while the Windows LUA DLL was initializing. This usually occurs because an operating system call failed.

WLUAINITREJECT

WinRUIStartup or WinSLIStartup was called multiple times.

Remarks

In order to support future Windows LUA implementations and applications that may have functionality differences, a negotiation takes place in WinRUIStartup/WinSLIStartup. An application passes to WinRUIStartup/WinSLIStartup the Windows LUA version that it can use. If this version is lower than the lowest version supported by the Windows LUA DLL, the DLL cannot support the application and WinRUIStartup/WinSLIStartup fails. If the version is not lower, however, the call succeeds and returns the highest version of Windows LUA supported by the DLL. If this version is lower than the lowest version supported by the application, the application either fails its initialization or attempts to find another Windows LUA DLL on the system.

This negotiation allows both a Windows LUA DLL and a Windows LUA application to support a range of Windows LUA versions. An application can successfully use a DLL if there is any overlap in the versions. The following table illustrates how WinRUIStartup/WinSLIStartup works in conjunction with different application and DLL versions:

App versions	DLL versions	To WinRUIStartup/ WinSLIStartup	From WinRUIStartup/ WinSLIStartup	Result
1.0	1.0	1.0	1.0	Use 1.0
1.0, 2.0	1.0	2.0	1.0	Use 1.0
1.0	1.0, 2.0	1.0	2.0	Use 1.0
1.0	2.0, 3.0	1.0	WLUAINVALID	Fail
2.0, 3.0	1.0	3.0	1.0	App Fails
1.0, 2.0, 3.0	1.0, 2.0, 3.0	3.0	3.0	Use 3.0
Note

The application must call WinRUIStartup / WinSLIStartup prior to issuing any other LUA commands. However, WinRUIStartup / WinSLIStartup needs to be called only once per application. If it is called multiple times, the subsequent calls will be rejected.

Details of the actual LUA implementation are described in the WLUADATA structure, defined as follows:

typedef struct tagWLUADATA { WORD wVersion;

      char szDescription[WLUADESCRIPTION_LEN+1];

      } WLUADATA, FAR *LPWLUADDATA;

Having made its last Windows LUA call, an application should call the WinRUICleanup/WinSLICleanup routine.

Each LUA implementation must make a WinRUIStartup/WinSLIStartup call before issuing any other LUA calls.

See Also

WinRUICleanup/WinSLICleanup


RUI( ) / SLI( )
Extensions for the Windows Environment	6 of 6

RUI( ) / SLI( )

Provides event notification for all RUI and SLI verbs.

Syntax

void WINAPI RUI (lpVCB);

void WINAPI SLI (1pVCB);

Returns

The value returned in lua_prim_rc indicates whether asynchronous notification will occur. If the field is set to LUA_IN_PROGRESS, asynchronous notification will occur via event signaling. If the flag is not LUA_IN_PROGRESS, the request completed synchronously. Examine the primary return code and secondary return code for any errors.

Remarks

The application must provide a handle to an event in the lua_post_handle parameter of the verb control block. The event must be in the not-signaled state.

When the asynchronous operation is complete, the application is notified via the signaling of the event. Upon signaling of the event, examine the primary return code and secondary return code for any error conditions.

See Also

WinRUI/WinSLI


SNA Server Enhancements to the Windows Environment
Appendix A	1 of 2

SNA Server Enhancements to the Windows Environment

This appendix describes the SNA Server-specific extension to Windows LUA that converts primary and secondary return codes in the VCB to a printable string.

Below is a definition of the function, syntax, returns, and remarks for using the extension.


GetLuaReturnCode( )
SNA Server Enhancements to the Windows Environment	2 of 2

GetLuaReturnCode( )

Converts the primary and secondary return codes in the VCB to a printable string. This function provides a standard set of error strings for use by LUA applications.

Syntax

int WINAPI GetLuaReturnCode (struct lua_hdr FAR * vpb, UINT buffer_length, unsigned char FAR * buffer_addr)

Parameter	Description

vpb	Supplied parameter; specifies the address of the verb parameter block.

buffer_length	Supplied parameter; specifies the length of the buffer pointed to by buffer_addr. The recommended length is 256.

buffer_addr	Supplied/returned parameter; specifies the address of the buffer that will hold the formatted, null-terminated string.

Returns

0x20000001

The parameters are invalid; the function could not read from the specified verb parameter block or could not write to the specified buffer.

0x20000002

The specified buffer is too small.

0x20000003

The LUA string library LUASTR.DLL (for Windows) or LUAST32.DLL (for Windows NT) could not be loaded.

Remarks

The descriptive error string returned in buffer_addr does not terminate with a new line character (\n).

The descriptive error strings are contained in LUASTR.DLL (for Windows) or LUAST32.DLL (for Windows NT) and can be customized for different languages.


Verb Control Block
Appendix B	1 of 7

Verb Control Block

When an application issues a Windows LUA verb the verb is coded within the application as a precisely defined VCB. The total length of this VCB is variable and is defined by lua_verb_length.

This appendix defines the structure of individual Windows LUA VCBs and is divided into the following sections:

"Common Structure of LUA VCBs," which consists of two tables. Table B.1 presents parameters that are common to all Windows LUA verbs. It lists the parameters and describes them. Table B.2 presents the values that lua_message_type can contain.

"Command-Specific Structures of LUA VCBs," which contains three tables. Tables B.3, B.4, and B.5 present the structure of the command-specific portions of the VCB.


Common Structure of LUA VCBs
Verb Control Block	2 of 7

Common Structure of LUA VCBs

The following table gives the length and offset into the VCB of each parameter that is common to all Windows LUA verbs.

Table B.1    Common VCB Structure

Type	Parameter

unsigned short	lua_verb

Specifies the Windows LUA verb code. It must always contain a value of X'5200'.

unsigned short	lua_verb_length

Specifies the VCB length. It must contain the length of the verb being issued.

unsigned short	lua_prim_rc

Provides the primary return code, which is set by the Windows LUA when the verb completes.

unsigned long	lua_sec_rc

Provides the secondary return code, which is set by the Windows LUA when the verb completes.

unsigned short	lua_opcode

This parameter specifies the Windows LUA command to be executed. Valid values are as follows:

X'0100'   LUA_OPCODE_SLI_OPEN
X'0200'   LUA_OPCODE_SLI_CLOSE
X'0300'   LUA_OPCODE_SLI_RECEIVE
X'0400'   LUA_OPCODE_SLI_SEND
X'0500'   LUA_OPCODE_SLI_PURGE
X'0600'   LUA_OPCODE_SLI_BID
X'1100'   LUA_OPCODE_SLI_BIND_ROUTINE
X'1200'   LUA_OPCODE_SLI_STSN_ROUTINE
X'1300'   LUA_OPCODE_SLI_CRV_ROUTINE
X'0180'   LUA_OPCODE_RUI_INIT
X'0280'   LUA_OPCODE_RUI_TERM
X'0380'   LUA_OPCODE_RUI_READ
X'0480'   LUA_OPCODE_RUI_WRITE
X'0580'   LUA_OPCODE_RUI_PURGE
X'0680'   LUA_OPCODE_RUI_BID

unsigned long	lua_correlator

Specifies the user-supplied value that links the verb with other user-supplied information. This parameter is neither examined nor modified by the Windows LUA interface.

unsigned char  (8 bytes)	lua_luname

Specifies the ASCII name for the local LU to be used for the Windows LUA session. The name must be 8 characters in length and should be padded with spaces (on the right) if the name is less than 8 characters long. SLI_OPEN and RUI_INIT require this parameter. Other Windows LUA verbs require this parameter only if lua_sid is 0.

unsigned short	lua_extension_list_offset

Specifies the offset from the start of the VCB to the extension list of user-supplied DLLs. The value must be the beginning of a word boundary unless there is no extension list. In this case, the value must be set to 0.

unsigned short	lua_cobol_offset

Not defined in the Windows LUA standard. Set to 0.

unsigned short	lua_sid

Identifies the session and is returned by SLI_OPEN and RUI_INIT. Other verbs use this parameter to identify the session used for the command. If other verbs use lua_luname to identify sessions, set lua_sid to 0.

unsigned int	lua_max_length

Specifies the length of the buffer that is used to receive data.

unsigned int	lua_data_length

This parameter specifies the length of the data being sent or received.

char   far *	lua_data_ptr

Points to the application data buffer. Both SNA commands and data are placed in this buffer and they can be in an EBCDIC format.

When SLI_RECEIVE or RUI_READ is issued, this parameter points to the location to receive the data from the host.

When SLI_SEND or RUI_WRITE is issued, this parameter points to the location of the application's data to be sent to the host.

When SLI_PURGE or RUI_PURGE is issued, this parameter points to the location of the SLI_RECEIVE or RUI_READ verb's VCB that is to be canceled.

When SLI_OPEN is issued, this parameter can be one of the following:

   The logon message for the SSCP normal flow when the initialization type is secondary with an unformatted logon message

   The RU for INITSELF. When the initialization type is secondary with INITSELF, the necessary data for the application is provided.

   For all other open types, this field should be set to 0.

This information is provided by the Windows LUA application.

unsigned long	lua_post_handle

For the Windows NT environment, if asynchronous notification is to be accomplished via events, lua_post_handle contains the handle of the event to be signaled.

For all other environments, this parameter is reserved and should be set to 0.

struct	lua_th

Provides the SNA TH for the message. Various subparameters are to be set for write functions and returned for read functions. See the appropriate verb for details. The following are the subparameters:

The first 2 bytes of lua_th.

The following list gives the bit mask for bits that are not reserved and can be some value other than 0:

X'2000'   lua_th.flags_fid
Identifies the format (FID) type 2.

X'0C00'   lua_th.mpf
Defines the type of data segment. The following values are valid:
X'00'   Middle segment
X'04'   Last segment
X'08'   First segment
X'0C'   Only segment

X'0200'   lua_th.odai
Contains the origin-address-field/data-field assignor indicator.

X'0100'   lua_th.efi
Contains the expedited-flow indicator.

lua_th.daf

The third byte of lua_th. Contains the destination-address field.

lua_th.oaf

The fourth byte of lua_th. Contains the origin-address field.

lua_th.snf

The fifth and sixth bytes of lua_th. Contains the RU sequence number.

struct	lua_rh

Specifies the SNA RH for the message. It is set for the write function and returned by the read and bid functions. The following list gives the bit mask for bits that are not reserved and can be set to a value other than 0:

X'800000'   lua_rh.rri
The request/response indicator.

X'600000'   lua_rh.ruc
The RU category. The following values are valid:
LUA_RH_FMD   X'00'   FM data segment
LUA_RH_NC    X'20'   Network control
LUA_RH_DFC   X'40'   Data flow control
LUA_RH_SC    X'60'   Session control

X'080000'   lua_rh.fi
The format indicator.

X'040000'   lua_rh.sdi
Indicates that the response has sense data included.

X'020000'   lua_rh.bci
Indicates the beginning of a chain.

X'010000'   lua_rh.eci
Indicates the end of a chain.

X'008000'   lua_rh.dr1i
Indicates a definite-response 1.

X'002000'   lua_rh.dr2i
Indicates a definite-response 2.

X'001000'   lua_rh.ri
Indicates the exception-response for requests and the type of response for responses.

X'000200'   lua_rh.qri
Indicates a queued-response.

X'000100'   lua_rh.pi
Indicates pacing.

X'000080'   lua_rh.bbi
Indicates the beginning of a bracket.

X'000040'   lua_rh.ebi
Indicates the end of a bracket.

X'000020'   lua_rh.cdi
Indicates a change of direction.

X'000008'   lua_rh.csi
Indicates the code selection.

X'000004'   lua_rh.edi
Indicates enciphered data.

X'000002'   lua_rh.pdi
Indicates padded data.

struct	lua_flag1

Composed of bits that are used as input for some verbs. The following list gives the bit mask for bits that are not reserved and can be set to a value other than 0:

High-order half-byte:

X'80'   lua_flag1.bid_enable
Used by SLI_RECEIVE and RUI_READ to indicate that the previous SLI_BID or RUI_BID is to be reused and reactivated. For verbs other than SLI_RECEIVE and RUI_READ, this flag must be set to off.

X'20'   lua_flag1.close_abend
Used by SLI_CLOSE to specify whether the session is to be closed immediately (ON) or closed normally (OFF). For verbs other than SLI_CLOSE, this flag has to be off.

X'10'   lua_flag1.nowait
Used by SLI_RECEIVE and RUI_READ to specify that the verbs should be posted with the NO_DATA return code when no data is available to read. For verbs other than SLI_RECEIVE and RUI_READ, this flag has to be off.

Low-order half-byte:

X'08'   lua_flag1.sscp_exp
Indicates SSCP expedited flow.

X'04'   lua_flag1.sscp_norm
Indicates SSCP normal flow.

X'02'   lua_flag1.lu_exp
Indicates LU expedited flow.

X'01'   lua_flag1.lu_norm
Indicates LU normal flow.

Note that the low-order half-byte flags, when used for SLI_RECEIVE or RUI_READ, indicate the flows on which a message can be received. At least one of the flags has to be set, but they cannot overlap with flags set for outstanding SLI_RECEIVE or RUI_READ verbs. Also note that one and only one of these flags should be set for RUI_WRITE and SLI_SEND (lua_message_type of response only). For verbs other than SLI_RECEIVE, SLI_SEND, RUI_READ, and RUI_WRITE these flags must be set to 0.

char(1 byte)	lua_message_type

Specifies the type of the inbound or outbound SNA commands and data. For SLI_BID, SLI_RECEIVE, RUI_BID, and RUI_READ, the parameter is filled in. For SLI_SEND this parameter must be set.

For possible values of lua_message_type, see Table B.2.

struct	lua_flag2

The bits of this parameter are used as output flags for specified verbs. When the verb is initiated, the parameter should be 0. When the verb completes, bits with no specified value are reserved and set to 0. The following list gives the mask for the bits:

X'80'   lua_flag2.bid_enable
Specifies successful completion of the requested bid_enable function for SLI_RECEIVE or RUI_READ, even if the SLI_RECEIVE or RUI_READ failed.

X'40'   lua_flag2.async
Specifies that the LUA interface verb completes asynchronously if set.

The following list gives the bit mask for bits that indicate the processed message session and flow:

X'08'   lua_flag2.sscp_exp
Specifies SSCP expedited flow.

X'04'   lua_flag2.sscp_norm
Specifies SSCP normal flow.

X'02'   lua_flag2.lu_exp
Specifies LU expedited flow.

X'01'   lua_flag2.lu_norm
Specifies LU normal flow.

char(7 bytes)	lua_resv56

This parameter is reserved and must be set to 0.

char(1 byte)	lua_encr_decr_option

Cryptography is not supported in the Windows LUA standard.


Values for lua_message_type
Verb Control Block	3 of 7

Values for lua_message_type

Table B.2    Possible Values for lua_message_type

Message type	SNA data	SLI_SEND	SLI_BID SLI_RECEIVE	RUI_BID RUI_READ
X'C8'	BID	X	X	X
X'31'	BIND		Extension*	X
X'70'	BIS	X	X	X
X'83'	CANCEL	X	X	X
X'84'	CHASE	X	X	X
X'A1'	CLEAR			X
X'D0'	CRV			X
X'01'	LU_DATA**	X	X	X
X'04'	LUSTAT_LU**	X	X	X
X'14'	LUSTAT_SSCP**	X	X	X
X'81'	QC	X	X	X
X'80'	QEC	X	X	X
X'82'	RELQ	X	X	X
X'A3'	RQR	X		X
X'02'	RSP	X	X
X'05'	RTR	X	X	X
X'71'	SBI	X	X	X
X'C0'	SHUTD			X
X'C9'	SIGNAL	X	X	X
X'A0'	SDT			X
X'11'	SSCP_DATA**	X	X	X
X'A2'	STSN		Extension*	X
X'32'	UNBIND			X
* The SLI receives and responds to the BIND, CRV, and STSN requests through the LUA interface extension routines. ** Not an SNA command.


Command-Specific Structure of LUA VCBs
Verb Control Block	4 of 7

Command-Specific Structure of LUA VCBs

The following tables describe command-specific parameters for SLI_OPEN, RUI_BID, SLI_BID, and SLI_SEND.


SLI_OPEN VCB Structure
Verb Control Block	5 of 7

Command-Specific Structure of LUA VCBs

SLI_OPEN VCB Structure

Table B.3    SLI_OPEN VCB Structure

Type	Parameter

char(1 byte)	lua_init_type

Determines how the LU-LU session is initialized by the Windows LUA interface. The following values are valid:

X'01'   lua_init_type_sec_is
Secondary-initiated and sends the INITSELF command supplied in the OPEN data buffer.

X'02'   lua_init_type_sec_log
Secondary-initiated with an unformatted LOGON message in the OPEN data buffer.

X'03'   lua_init_type_prim
Primary-initiated and waits on the BIND command.

X'04'   lua_init_type_prim_sscp
Primary-initiated with SSCP access.

char(1 byte)	lua_resv65

Reserved and must be set to 0.

2	lua_wait

Specifies how many seconds the Windows LUA interface is to wait before retransmitting the INITSELF or the LOGON message after receiving one of the following:

   A NOTIFY command (indicating a procedure error)

   A network services procedure error message

   A negative response with one of the following secondary return codes:
RESOURCE_NOT_AVAILABLE         X'08010000'
SESSION_LIMIT_EXCEEDED              X'08050000'
sESSION_SERVICE_PATH_ERROR   X'087D0000'

n	This offset length is given in lua_extension_list_offset.

For BIND and STSN, the names of DLL modules and procedure entry points must be supplied to SLI_OPEN by the Windows LUA application. Each of these routines includes an entry of fixed length that defines the DLL and procedure names. The length of the list depends on the number of extension routines. The end of the list is marked by the lua_routine_type_end parameter. The following list provides the routine type, module name, and procedure name parameters.

char(1 byte)	lua_routine_type

Specifies the type of routine for the noted routine. The following values are valid:

X'01'   LUA_ROUTINE_TYPE_BIND
Specifies a bind routine.

X'03'   LUA_ROUTINE_TYPE_STSN
Specifies the STSN routine.

X'00'   LUA_ROUTINE_TYPE_END
Specifies the end of the extension routine list.

Note   SLI_OPEN terminates with an error if lua_wait is set to 0 and one of the preceding routine types for lua_routine_type occurs.

lua_module_name	The user-supplied module name in ASCII. It can be a variable length of up to 8 characters. Remaining bytes should be set to X'00'.

char(9 bytes)	lua_module_name

The user-supplied module name in ASCII. It can be a variable length of up to 8 characters. Remaining bytes should be set to X'00'.

char(33 bytes)	lua_procedure_name

The user-supplied DLL procedure name in ASCIIZ (a null terminated string). It can be a variable length of up to 32 characters. Remaining bytes should be set to X'00'.


SLI_BID and RUI_BID VCB Structure
Verb Control Block	6 of 7

Command-Specific Structure of LUA VCBs

SLI_BID and RUI_BID VCB Structure

Table B.4    SLI_BID and RUI_BID VCB Structure

Type	Parameter

char(12 bytes)	lua_peek_data

For SLI_BID, this parameter is a preview (up to 12 bytes) of the RU data waiting to be read. The lua_data_length parameter contains the exact length of the data peeked.


SLI_SEND VCB Structure
Verb Control Block	7 of 7

Command-Specific Structure of LUA VCBs

SLI_SEND VCB Structure

Table B.5    	SLI_SEND VCB Structure

Type	Parameter

char(2 bytes)	lua_sequence_number

For SLI_SEND, this parameter contains the sequence number for either the first in the chain request unit or the only segment in the chain request unit. Note that this parameter is not byte-reversed.


Common Return Codes
Appendix C	1 of 3

Common Return Codes

This appendix describes the primary and, if applicable, secondary return codes that are common to the LUA verbs. The return codes are listed in hexadecimal order.

Verb-specific return codes are described for the individual verbs in Chapter 3, “LUA RUI Verbs” and Chapter 4, “LUA SLI Verbs.”


Primary Return Codes
Common Return Codes	2 of 3

Primary Return Codes

0x0000

LUA_OK

The verb executed successfully.

0x0001

LUA_PARAMETER_CHECK

The verb did not execute because of a parameter error.

0x0002

LUA_STATE_CHECK

The verb did not execute because it was issued in an invalid state.

0x000F

LUA_SESSION_FAILURE

A required SNA Server component (such as the local node) has terminated.

0x0014

LUA_UNSUCCESSFUL

The verb record supplied was valid, but the verb did not complete successfully.

0x0018

LUA_NEGATIVE_RESPONSE

Either LUA sent a negative response to a message received from the primary LU because an error was found in the message, or the application responded negatively to a chain for which the end-of-chain has arrived.

0x0021

LUA_CANCELED

The secondary return code gives the reason for canceling the command.

0x0030

LUA_IN_PROGRESS

An asynchronous command was received but is not completed.

0x0040

LUA_STATUS

The secondary return code contains SLI status information for the application.

0xF003

LUA_COMM_SUBSYSTEM_ABENDED

Indicates one of the following conditions:

The node used by this conversation encountered an ABEND.

The connection between the TP and the PU 2.1 node has been broken (a LAN error).

The SnaBase at the TP’s computer encountered an ABEND.

0xF004

LUA_COMM_SUBSYSTEM_NOT_LOADED

A required component could not be loaded or has terminated while processing the verb. Thus, communication could not take place. Contact the system administrator for corrective action.

0xF008

LUA_INVALID_VERB_SEGMENT

The VCB extended beyond the end of the data segment.

0xF011

LUA_UNEXPECTED_DOS_ERROR

After issuing an operating system call, an unexpected operating system return code was received and is specified in the secondary return code.

0xF015

LUA_STACK_TOO_SMALL

The stack size of the application is too small to execute the verb. Increase the stack size of your application.

0xFFFF

LUA_INVALID_VERB

Either the verb code or the operation code, or both, is invalid. The verb did not execute.


Secondary Return Codes
Common Return Codes	3 of 3

Secondary Return Codes

The associated secondary return codes are as follows:

0x00000000

LUA_SEC_RC_OK

No additional information exists for LUA_OK.

0x00000001

LUA_INVALID_LUNAME

An invalid lua_luname name was specified.

0x00000002

LUA_BAD_SESSION_ID

An invalid value for lua_sid was specified in the VCB.

0x00000003

LUA_DATA_TRUNCATED

The data was truncated because the data received was longer than the buffer length specified in lua_max_length.

0x00000004

LUA_BAD_DATA_PTR

The lua_data_ptr parameter either does not contain a valid pointer or does not point to a read/write segment and supplied data is required.

0x00000005

LUA_DATA_LENGTH_ERROR

One of the following occurred:

The supplied data segment for SLI_RECEIVE or SLI_SEND is not a read/write data segment as required.

The supplied data segment for SLI_RECEIVE is not as long as that provided in lua_max_length.

The supplied data segment for SLI_SEND is not as long as that provided in lua_data_length.

0x00000006

LUA_RESERVED_FIELD_NOT_ZERO

A reserved parameter for the verb just issued is not set to 0.

0x00000007

LUA_INVALID_POST_HANDLE

For a Windows NT system using events as the asynchronous posting method, the Windows-based LUA VCB does not contain a valid event handle.

For the Windows version 3.x system, the LUA VCB does not contain the valid procedure address returned by the MakeProcInstance command.

For OS/2, the LUA VCB does not contain a valid semaphore or queue handle, which is needed when a verb completes asynchronously.

0x0000000C

LUA_PURGED

SLI_PURGE was issued and canceled SLI_RECEIVE.

0x0000000F

LUA_BID_VERB_ERROR

The buffer with the SLI_BID VCB was released before the SLI_RECEIVE with lua_flag1.bid_enable set to 1 was issued.

0x00000010

LUA_NO_PREVIOUS_BID_ENABLED

SLI_BID was not issued prior to issuing SLI_RECEIVE with bid_enable.

0x00000011

LUA_NO_DATA

No data was available to read when SLI_RECEIVE containing a no wait parameter was issued.

0x00000012

LUA_BID_ALREADY_ENABLED

SLI_RECEIVE was issued with bid_enable when SLI_BID was already active.

0x00000013

LUA_VERB_RECORD_SPANS_SEGMENTS

The LUA VCB length parameter plus the segment offset is beyond the segment end.

0x00000014

LUA_INVALID_FLOW

The lua_flag1 flow flags were set incorrectly when a verb was issued as follows:

When issuing SLI_SEND to send an SNA response, set only one lua_flag1 flow flag.

When issuing SLI_RECEIVE, set at least one lua_flag1 flow flag.

0x00000015

LUA_NOT_ACTIVE

LUA was not active within SNA Server when an LUA verb was issued.

0x00000016

LUA_VERB_LENGTH_INVALID

An LUA verb was issued with the value of lua_verb_length unexpected by the LUA.

0x00000019

LUA_REQUIRED_FIELD_MISSING

The verb that was issued either did not include a data pointer (if the data count was not 0) or did not include an lua_flag1 flow flag.

0x00000030

LUA_READY

Following a NOT_READY status, this status is issued to notify you that the SLI is ready to process commands.

0x00000031

LUA_NOT_READY

One of the following caused the SLI session to be temporarily suspended:

An SNA UNBIND type X'02' command was received, indicating a new BIND is coming.

If the UNBIND type X'02' is received after the beginning SLI_OPEN is complete, the session is suspended until a BIND, optional CRV and STSN, and SDT flows are received. These routines are re-entrant because they have to be called again. The session resumes after the SLI processes the SDT command. If the UNBIND type X'02' is received while SLI_OPEN is still processing, the primary return code is session-failure, not status.

The receipt of an SNA CLEAR caused the suspension.

Receipt of an SNA SDT will cause the session to resume.

0x00000032

LUA_INIT_COMPLETE

The LUA interface initialized the session while SLI_OPEN was processing. LUA applications that issue SLI_OPEN with lua_open_type_prim_sscp receive this status on SLI_RECEIVE or SLI_BID.

0x00000033

LUA_SESSION_END_REQUESTED

The LUA interface received an SNA shutdown command (SHUTD) from the host, indicating the host is ready to shut down the session.

0x00000034

LUA_NO_SLI_SESSION

A session was not open or was down due to an SLI_CLOSE or session failure when a command was issued.

0x00000035

LUA_SESSION_ALREADY_OPEN

A session is already open for the LU name specified in SLI_OPEN.

0x00000036

LUA_INVALID_OPEN_INIT_TYPE

The value in the lua_init_type contained in SLI_OPEN is invalid.

0x00000037

LUA_INVALID_OPEN_DATA

The lua_init_type for the SLI_OPEN issued is set to LUA_INIT_TYPE_SEC_IS when the buffer for data does not have a valid INITSELF command.

0x00000038

LUA_UNEXPECTED_SNA_SEQUENCE

Unexpected data or commands were received from the host while SLI_OPEN was processing.

0x00000039

LUA_NEG_RSP_FROM_BIND_ROUTINE

The user-supplied SLI_BIND routine responded negatively to the BIND. SLI_OPEN ended unsuccessfully.

0x0000003B

LUA_NEG_RSP_FROM_STSN_ROUTINE

The user-supplied SLI STSN routine responded negatively to the STSN. SLI_OPEN ended unsuccessfully.

0x0000003E

LUA_INVALID_OPEN_ROUTINE_TYPE

The lua_open_routine_type for the SLI_OPEN list of extension routines is invalid.

0x0000003F

LUA_MAX_NUMBER_OF_SENDS

The application issued a third SLI_SEND before one completed.

0x00000040

LUA_SEND_ON_FLOW_PENDING

An SLI_SEND was still outstanding when the application issued another SLI_SEND for an SNA flow.

0x00000041

LUA_INVALID_MESSAGE_TYPE

The lua_message_type parameter is not recognized by the LUA interface.

0x00000042

LUA_RECEIVE_ON_FLOW_PENDING

An SLI_RECEIVE was still outstanding when this application issued another SLI_RECEIVE for an SNA flow.

0x00000043

LUA_DATA_LENGTH_ERROR

The application did not provide user-supplied data required by the verb issued. Note that when SLI_SEND is issued for an SNA LUSTAT command, status (in 4 bytes) is required, and that when SLI_OPEN is issued with secondary initialization, data is required.

0x00000044

LUA_CLOSE_PENDING

One of the following has occurred:

A CLOSE_ABEND was still pending when another CLOSE_ABEND was issued. You can issue a CLOSE_ABEND if a CLOSE_NORMAL is pending.

Either a CLOSE_ABEND or a CLOSE_NORMAL was still pending when a CLOSE_NORMAL was issued.

0x00000046

LUA_NEGATIVE_RSP_CHASE

A negative response to an SNA CHASE command from the host was received by the LUA interface while SLI_CLOSE was being processed. SLI_CLOSE continued processing to stop the session.

0x00000047

LUA_NEGATIVE_RSP_SHUTC

A negative response to an SNA SHUTC command from the host was received by the SLI while SLI_CLOSE was still being processed. SLI_CLOSE continued processing to stop the session.

0x00000048

LUA_NEGATIVE_RSP_RSHUTD

A negative response to an SNA RSHUTD command from the host was received by the LUA interface while SLI_CLOSE was still being processed. SLI_CLOSE continued processing to stop the session.

0x0000004A

LUA_NO_RECEIVE_TO_PURGE

No SLI_RECEIVE was outstanding when you issued SLI_PURGE. One of two situations caused the problem:

SLI_RECEIVE completed before SLI_PURGE finished processing.

You can change the application to take care of this problem because it is not an error condition.

The lua_data_ptr parameter does not correctly point to the SLI_RECEIVE you want to purge.

0x0000004D

LUA_CANCEL_COMMAND_RECEIVED

The host sent an SNA CANCEL command to cancel the data chain currently being received by SLI_RECEIVE.

0x0000004E

LUA_RUI_WRITE_FAILURE

An unexpected error was posted to the SLI by RUI_WRITE.

0x00000051

LUA_SLI_BID_PENDING

An SLI verb was still active when another SLI_BID was issued. Only one SLI_BID can be active at a time.

0x00000052

LUA_SLI_PURGE_PENDING

An SLI_PURGE was still active when another SLI_PURGE was issued. Only one SLI_PURGE can be active at a time.

0x00000053

LUA_PROCEDURE_ERROR

A host procedure error is indicated by the receipt of an NSPE or NOTIFY message. The return code is posted to SLI_OPEN when the retry option is not used. To use the reset option, set lua_wait to a value other than 0. The LOGON or INITSELF command will be retried until the host is ready or until you issue SLI_CLOSE.

0x00000054

LUA_INVALID_SLI_ENCR_OPTION

The lua_encr_decr_option parameter was set to 128 in SLI_OPEN, which is not supported for the encryption/decryption processing option.

0x00000055

LUA_RECEIVED_UNBIND

The primary LU sent an SNA UNBIND command to the LUA interface when a session was active. As a result, the session was stopped.

0x0000007F

LUA_SLI_LOGIC_ERROR

The LUA interface found an internal error in logic.

0x00000080

LUA_TERMINATED

The session was terminated when a verb was pending. The verb process has been canceled.

0x00000081

LUA_NO_RUI_SESSION

No session has been initialized for the LUA verb issued, or some verb other than SLI_OPEN was issued before the session was initialized.

0x00000083

LUA_INVALID_PROCESS

The session for which an RUI verb was issued is unavailable because another process owns the session.

0x0000008C

LUA_LINK_NOT_STARTED

The LUA was not able to activate the data link during initialization of the session.

0x0000008D

LUA_INVALID_ADAPTER

The configuration for the DLC is in error, or the configuration file is corrupted.

0x0000008E

LUA_ENCR_DECR_LOAD_ERROR

An unexpected return code was received from the OS/2 DosLoadModule function while attempting to load the user-provided encryption or decryption dynamic link module.

0x0000008F

LUA_ENCR_DECR_LOAD_ERROR

An unexpected return code was received from the OS/2 DosGetProcAddr function while attempting to get the procedure address within the user-provided encryption or decryption dynamic link module.

0x000000BE

LUA_NEG_NOTIFY_RSP

The SSCP responded negatively to a NOTIFY request issued indicating that the secondary LU was capable of a session. The half-session component that received the request understood and supported the request but could not execute it.

0x000000FF

LUA_LU_INOPERATIVE

A severe error occurred while the RUI was attempting to stop the session. This LU is unavailable for any LUA requests until an ACTLU is received from the host.

0x08010000

LUA_RESOURCE_NOT_AVAILABLE

The logical unit, physical unit, link, or link station specified in the request unit is unavailable. This return code is posted to SLI_OPEN when a resource is unavailable unless you use the retry option.

To use the retry option, set lua_wait to a value other than 0. The LOGON or INITSELF command will be retried until the host is ready or until you issue SLI_CLOSE.

0x08050000

LUA_SESSION_LIMIT_EXCEEDED

The session requested was not activated because an NAU is at its session limit.

This SNA sense code applies to the following requests: BID, CINIT, INIT, and ACTDRM. The code will be posted to SLI_OPEN when an NAU is at its limit, unless you use the retry option.

To use the retry option, set lua_wait to a value other than 0. The LOGON or INITSELF command will be retried until the host is ready or until you issue SLI_CLOSE.

0x08090000

LUA_MODE_INCONSISTENCY

Performing this function is not allowed by the current status. The request sent to the half-session component was not executed even though it was understood and supported. This SNA sense code is also an exception request sense code.

0x08120000

LUA_INSUFFICIENT_RESOURCES

A temporary condition of insufficient resources caused the request receiver to be unable to perform. The request sent to the half-session component was not executed, even though it was understood and supported.

0x081B0000

LUA_RECEIVER_IN_TRANSMIT_MODE

Either resources needed to handle normal flow data were not available or the state of the half-duplex contention was not received when a normal-flow request was received. The result is a race condition. This SNA sense code is also an exception request sense code.

0x08310000

LUA_LU_COMPONENT_DISCONNECTED

An LU component is unavailable because it is not connected properly. Make sure that the power is on.

0x08350001

LUA_NEGOTIABLE_BIND_ERROR

A negotiable BIND was received, which is only allowed by the SLI when a user-supplied SLI_BIND routine is provided with SLI_OPEN.

0x08350002

LUA_BIND_FM_PROFILE_ERROR

Only file management header profiles 3 and 4 are supported by the LUA interface. A file management profile other than 3 or 4 was found on the BIND.

0x08350003

LUA_BIND_TS_PROFILE_ERROR

Only TS profile 3 and 4 are supported by the LUA interface. A TS other than 3 or 4 was found on the BIND.

0x0835000E

LUA_BIND_LU_TYPE_ERROR

Only LU 0, LU 1, LU 2, and LU 3 are supported by LUA. An LU other than 0, 1, 2, or 3 was found.

0x08570000

LUA_SSCP_LU_SESSION_NOT_ACTIVE

The required SSCP-LU is inactive. Specific sense code information is in bytes 2 and 3. Valid settings are X'0000', X'0001', X'0002', X'0003', and X'0004'.

0x08780001

LUA_RECEIVE_CORRELATION_TABLE_FULL

The session receive correlation table for the flow requested reached its capacity.

0x08780002

LUA_SEND_CORR_TABLE_FULL

The session send correlation table for the flow requested reached its capacity.

0x087D0000

LUA_SESSION_SERVICE_PATH_ERROR

A request for session services cannot be rerouted to an SSCP-SSCP session path. Specific sense code information in bytes 2 and 3 gives more information about why the request cannot be rerouted.

0x10020000

LUA_RU_LENGTH_ERROR

The RU request was an incorrect length (either too short or too long). The request unit was not interpreted or processed even though it was delivered to the half-session component. The half-session capabilities do not match. This SNA sense code is also an exception request sense code.

0x10030000

LUA_FUNCTION_NOT_SUPPORTED

The LUA does not support the requested function. A control character, an RU parameter, or a formatted request code may have specified the function. Specific sense code information is in bytes 2 and 3.

0x10050121

LUA_HDX_BRACKET_STATE_ERROR

The existing state error prevented the current request from being sent. The determination was made by a protocol computer.

0x10050122

LUA_RESPONSE_ALREADY_SENT

A response for the chain was already sent so that the current request was not sent. The determination was made by a protocol computer.

0x10050123

LUA_EXR_SENSE_INCORRECT

The application responded negatively to an exception request. The sense code was unacceptable.

0x10050124

LUA_RESPONSE_OUT_OF_ORDER

The current response was not for the oldest request. The determination was made by a protocol computer.

0x10050125

LUA_CHAse_RESPONSE_REQUIRED

A CHASE response was still outstanding when a more recent request was attempted. The determination was made by a protocol computer.

0x20020000

LUA_CHAINING_ERROR

The sequence of the chain indicator settings is in error. An invalid request header or request unit for the receiver’s current session control or data flow control state was found. Delivery to the half-session component was prevented.

0x20030000

LUA_BRACKET

The sender failed to enforce the session bracket rules. Note that contention and race conditions are exempt from this error. An invalid request header or request unit for the receiver’s current session control or data flow control state was found. Delivery to the half-session component was prevented.

0x20040000

LUA_DIRECTION

While the half-duplex flip-flop state was NOT_RECEIVE, a request for normal flow was received. An invalid request header or request unit for the receiver’s current session control or data flow control state was found. Delivery to the half-session component was prevented.

0x20050000

LUA_DATA_TRAFFIC_RESET

A half-session of an active session with inactive data traffic received a normal flow DFC or FMD request. An invalid request header or request unit for the receiver’s current session control or data flow control state was found. Delivery to the half-session component was prevented.

0x20060000

LUA_DATA_TRAFFIC_QUIESCED

A DFC or FMD request was received from a half-session that sent either a SHUTC command or QC command, and the DFC or FMD request has not responded to a RELQ command. An invalid request header or request unit for the receiver’s current session control or data flow control state was found. Delivery to the half-session component was prevented.

0x20070000

LUA_DATA_TRAFFIC_NOT_RESET

While the data traffic state was not reset, the session control request was received. An invalid request header or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

0x20080000

LUA_NO_BEGIN_BRACKET

The receiver has already sent a positive response to a BIS command when a BID or an FMD request specifying BBI=BB was received. An invalid request header or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

0x20090000

LUA_SC_PROTOCOL_VIOLATION

A violation of the SC protocol occurred. A request (that is permitted only after an SC request and a positive response to that request have been successfully exchanged) was received before the required exchange. Byte 4 of the sense data contains the request code. No user data exists for this sense code. An invalid header request or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

0x200A0000

LUA_IMMEDIATE_REQUEST_MODE_ERROR

The request violated the immediate request mode protocol. An invalid header request or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

0x200B0000

LUA_QUEUED_RESPONSE_ERROR

The request violated the queued response protocol. An invalid header request or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

0x200C0000

LUA_ERP_SYNC_EVENT_ERROR

A violation of the ERP synchronous event protocol occurred. An invalid header request or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

0x200D0000

LUA_RSP_BEFORE_SENDING_REQ

A previously received request has not been responded to yet and an attempt was made in half-duplex send/receive mode to send a normal flow request. An invalid header request or request unit for the received current session control or data flow control state was found. Delivery to the half-session component was prevented.

0x200E0000

LUA_RSP_CORRELATION_ERROR

A response was sent that does not correspond to a previously received request or a response was received that does not correspond to a request sent previously.

0x200F0000

LUA_RSP_PROTOCOL_ERROR

A violation of the response protocol was found in the response received from the primary half-session.

0x40010000

LUA_INVALID_SC_OR_NC_RH

The RH of an SC or NC request was invalid.

0x40030000

LUA_BB_NOT_ALLOWED

The begin bracket indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

0x40040000

LUA_EB_NOT ALLOWED

The end bracket indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

0x40060000

LUA_EXCEPTION_RSP_NOT_ALLOWED

When an exception response was not allowed, one was requested. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

0x40070000

LUA_DEFINITE_RSP_NOT_ALLOWED

When a definite response was not allowed, one was requested. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

0x40080000

LUA_PACING_NOT_SUPPORTED

The request contained a pacing indicator when support of pacing for this session does not exist for the receiving half-session or boundary function half-session. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

0x40090000

LUA_CD_NOT_ALLOWED

The change-direction indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

0x400A0000

LUA_NO_RESPONSE_NOT_ALLOWED

A request other than an EXR contained a NO RESPONSE. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

0x400B0000

LUA_CHAINING_NOT_SUPPORTED

The chaining indicators were incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

0x400C0000

LUA_BRACKETS_NOT_SUPPORTED

The bracket indicators were incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

0x400D0000

LUA_CD_NOT_SUPPORTED

The change-direction indicator was set, but LUA does not support change-direction for this situation. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

0x400F0000

LUA_INCORRECT_USE_OF_FI

The format indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

0x40100000

LUA_ALTERNATE_CODE_NOT_SUPPORTED

The code selection indicator was set, but LUA does not support code selection for this session. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

0x40110000

LUA_INCORRECT_RU_CATEGORY

The request unit category indicator was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

0x40120000

LUA_INCORRECT_REQUEST_CODE

The request code was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

0x40130000

LUA_INCORRECT_SPEC_OF_SDI_RTI

The SDI and the RTI were not specified correctly on a response. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

0x40140000

LUA_INCORRECT_DR1I_DR2I-ERI

The DR1I, the DR2I, and the ERI were specified incorrectly. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

0x40150000

LUA_INCORRECT_USE_OF QRI

The QRI was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

0x40160000

LUA_INCORRECT_USE_OF_EDI

The EDI was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

0x40170000

LUA_INCORRECT_USE_OF_PDI

The PDI was incorrectly specified. The BIND options chosen previously or the architectural rules were violated by the request header parameter values. Delivery to the half-session component was prevented. The errors are not dependent on the current session state. The sender’s failure to enforce session rules may have caused the errors.

0x80030000

LUA_NAU_INOPERATIVE

The NAU is not able to process responses or requests. Delivery to the receiver could not take place for one of the following reasons:

A path information unit error

A path outage

An invalid sequence of requests for activation

If a path error is received during an active session, that usually means there is no longer a valid path to the session partner.

0x80050000

LUA_NO_SESSION

A request to activate a session is required because no active half-session in the receiving end node for the origination-destination pair exists, or no active boundary function half-session component for the origination-destination pair in a node that supplies the boundary function exists. Delivery of the request could not take place for one of the following reasons:

A path information unit error

A path outage

An invalid sequence of requests for activation

If a path error is received during an active session, that usually indicates there is no longer a valid path to the session partner.


LUA Code Samples in the SDK
Appendix D	1 of 4

LUA Code Samples in the SDK

This chapter describes the LUA code samples in the SNA Server SDK, which show how to build a simple 3270 emulator using either the RUI or SLI APIs. This emulator does not interpret the data it receives from the host but does demonstrate how to use the APIs to establish a session with the host.


Specifying a Filename for Table G for Code Conversion
LUA Code Samples in the SDK	2 of 4

Specifying a Filename for Table G for Code Conversion

The sample emulators use Table G for code conversion and require that the filename for this table be specified. To specify the filename, use the COMTBLG Registry or environment variable, as described in Appendix C of the Microsoft SNA Server Reference.

A sample Table G file, COMTBLG.DAT, can be found on the SNA server in the SYSTEM subdirectory of the SNA server root directory. To use this file, copy it to the client computers where the sample programs will be run, and specify the filename with the COMTBLG variable.


Code Samples Using the RUI APIs
LUA Code Samples in the SDK	3 of 4

Code Samples Using the RUI APIs

The following files can be used to build simple 3270 emulators using the RUI APIs. Study the comments in the *.C files for information about how to run the emulators.

Filename	API Used	Type of file	Target operating system
RUI3270.C	RUI	Source code for RUI3270.EXE	Windows NT, OS/2, or MS-DOS
RUI3270.MAK	RUI	Makefile	Windows NT
RUI3270D.MAK	RUI	Makefile	MS-DOS
RUI3270O.MAK	RUI	Makefile	OS/2
WRUI3270.C	RUI	Source code for WRUI3270.EXE	Windows version 3.1 or Windows for Workgroups
WRUI3270.DEF	RUI	Definition file	Windows version 3.1 or Windows for Workgroups
WRUI3270.LNK	RUI	Link file	Windows version 3.1 or Windows for Workgroups
WRUI3270.MAK	RUI	Makefile	Windows version 3.1 or Windows for Workgroups
WRUI3270.RC	RUI	Resource definition file	Windows version 3.1 or Windows for Workgroups


Code Samples Using the SLI APIs
LUA Code Samples in the SDK	4 of 4

Code Samples Using the SLI APIs

The following files can be used to build simple 3270 emulators using the SLI APIs. Study the comments in the *.C files for information about how to run the emulators.

Filename	API Used	Type of file	Target operating system
SLI3270.C	SLI	Source code for SLI3270.EXE	Windows NT, OS/2, or MS-DOS
SLI3270.MAK	SLI	Makefile	Windows NT
SLI3270O.MAK	SLI	Makefile	OS/2
WSLI3270.C	SLI	Source code for WSLI3270.EXE	Windows version 3.1 or Windows for Workgroups
WSLI3270.DEF	SLI	Definition file	Windows version 3.1 or Windows for Workgroups
WSLI3270.LNK	SLI	Link file	Windows version 3.1 or Windows for Workgroups
WSLI3270.MAK	SLI	Makefile	Windows version 3.1 or Windows for Workgroups
WSLI3270.RC	SLI	Resource definition file	Windows version 3.1 or Windows for Workgroups