Copyright: APPC Programmer's Guide
Citation: APPC 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


APPC Programmer's Guide Contents
Microsoft SNA Server

APPC Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to APPC

Chapter 2	Transaction Programs

Chapter 3	APPC Management Verbs

Chapter 4	APPC TP Verbs

Chapter 5	APPC Conversation Verbs

Chapter 6	APPC Extensions for the Windows Environment

Chapter 7	SNA Server Enhancements to the Windows Environment

Chapter 8	Common Service Verbs

Chapter 9	CSV Extensions for the Windows Environment

Appendix A	Common APPC Return Codes

Appendix B	Common CSV Return Codes

Appendix C	Sample APPC TPs in the SDK

List of Figures

List of Tables


Welcome Contents, APPC Programmer's Guide
Microsoft SNA Server

APPC Programmer's Guide

Contents

Before You Begin

How to Use This Guide

Document Conventions

Common Abbreviations

Finding Further Information

Chapter 1	Introduction to APPC

Chapter 2	Transaction Programs

Chapter 3	APPC Management Verbs

Chapter 4	APPC TP Verbs

Chapter 5	APPC Conversation Verbs

Chapter 6	APPC Extensions for the Windows Environment

Chapter 7	SNA Server Enhancements to the Windows Environment

Chapter 8	Common Service Verbs

Chapter 9	CSV Extensions for the Windows Environment

Appendix A	Common APPC Return Codes

Appendix B	Common CSV Return Codes

Appendix C	Sample APPC TPs in the SDK

List of Figures

List of Tables


Chapter 1 Contents, APPC Programmer's Guide
Microsoft SNA Server

APPC Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to APPC

APPC Verbs

APPC Verb Summary

Windows APPC Overview

Windows APPC Asynchronous Support

Before Using Windows APPC

Using APPC Verbs in C Programs

Verb Control Block

APPC Definition

Issuing an APPC Verb

Windows NT Considerations

Windows Considerations

Translating Service TP Names to ASCII for WIN.INI

MS-DOS Considerations

OS/2 Considerations

Chapter 2	Transaction Programs

Chapter 3	APPC Management Verbs

Chapter 4	APPC TP Verbs

Chapter 5	APPC Conversation Verbs

Chapter 6	APPC Extensions for the Windows Environment

Chapter 7	SNA Server Enhancements to the Windows Environment

Chapter 8	Common Service Verbs

Chapter 9	CSV Extensions for the Windows Environment

Appendix A	Common APPC Return Codes

Appendix B	Common CSV Return Codes

Appendix C	Sample APPC TPs in the SDK

List of Figures

List of Tables


Chapter 2 Contents, APPC Programmer's Guide
Microsoft SNA Server

APPC Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to APPC

Chapter 2	Transaction Programs

Communication Between TPs

Fundamental Terms for TPs and LUs

Sample TPs Illustrating Fundamental Concepts

Configuring and Controlling TPs

Steps for Creating TPs and the Configuration to Support Them

Designing and Coding TPs

Conversation States

State Checks

Changing Conversation States

Confirmation Processing

Establishing the Synchronization Level

Sending a Confirmation Request

Receiving Data and Confirmation Request

Responding to a Confirmation Request

Deallocating the Conversation

Receiving Data Asynchronously

Conversation Security

Basic and Mapped Conversations Compared

Logical Records Used in Basic Conversations

An Example of a Mapped Conversation

Using Invoking and Invokable TPs

Invoking TPs

Invoking TPs and Contention

Invokable TPs

Subcategories for Invokable TPs

How an Invokable TP is Matched to an Invoking TPs Request

Configuring Invokable TPs

Clients Running Windows NT

Registry Entries for Clients Running Windows NT

Example of Registry Entries for an Invokable TP

Clients Running Windows Version 3.x

Environment Variables for Clients Running Windows Version 3.x

Example of WIN.INI Lines for an Invokable TP

Clients Running OS/2

Environment Variables for OS/2-Based Clients

Clients Running MS-DOS

Configuring an SNA Server to Support TPs

Invoking TPs and the SNA Server Configuration

Invokable TPs and the SNA Server Configuration

Possible Arrangements of TPs Within an SNA Network

TP Name Unique for Each TP

TP Name Not Unique; Local LU Alias Unique

TP Name Not Unique; Local LU Alias Unspecified

Troubleshooting for Invokable TPs

SNA Server Features That Simplify APPC Configuration

Chapter 3	APPC Management Verbs

Chapter 4	APPC TP Verbs

Chapter 5	APPC Conversation Verbs

Chapter 6	APPC Extensions for the Windows Environment

Chapter 7	SNA Server Enhancements to the Windows Environment

Chapter 8	Common Service Verbs

Chapter 9	CSV Extensions for the Windows Environment

Appendix A	Common APPC Return Codes

Appendix B	Common CSV Return Codes

Appendix C	Sample APPC TPs in the SDK

List of Figures

List of Tables


Chapter 3 Contents, APPC Programmer's Guide
Microsoft SNA Server

APPC Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to APPC

Chapter 2	Transaction Programs

Chapter 3	APPC Management Verbs

CNOS (Change Number of Sessions)

Setting a Session Limit to 0

DISPLAY

DISPLAY Differences

SNA Server Extensions

Differences by Information Type

Chapter 4	APPC TP Verbs

Chapter 5	APPC Conversation Verbs

Chapter 6	APPC Extensions for the Windows Environment

Chapter 7	SNA Server Enhancements to the Windows Environment

Chapter 8	Common Service Verbs

Chapter 9	CSV Extensions for the Windows Environment

Appendix A	Common APPC Return Codes

Appendix B	Common CSV Return Codes

Appendix C	Sample APPC TPs in the SDK

List of Figures

List of Tables


Chapter 4 Contents, APPC Programmer's Guide
Microsoft SNA Server

APPC Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to APPC

Chapter 2	Transaction Programs

Chapter 3	APPC Management Verbs

Chapter 4	APPC TP Verbs

GET_TP_PROPERTIES

TP_ENDED

TP_STARTED

Default LUs

Chapter 5	APPC Conversation Verbs

Chapter 6	APPC Extensions for the Windows Environment

Chapter 7	SNA Server Enhancements to the Windows Environment

Chapter 8	Common Service Verbs

Chapter 9	CSV Extensions for the Windows Environment

Appendix A	Common APPC Return Codes

Appendix B	Common CSV Return Codes

Appendix C	Sample APPC TPs in the SDK

List of Figures

List of Tables


Chapter 5 Contents, APPC Programmer's Guide
Microsoft SNA Server

APPC Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to APPC

Chapter 2	Transaction Programs

Chapter 3	APPC Management Verbs

Chapter 4	APPC TP Verbs

Chapter 5	APPC Conversation Verbs

[MC_]ALLOCATE

[MC_]CONFIRM

[MC_]CONFIRMED

Confirmation Requests

[MC_]DEALLOCATE

[MC_]FLUSH

[MC_]GET_ATTRIBUTES

GET_TYPE

[MC_]PREPARE_TO_RECEIVE

RECEIVE_ALLOCATE

[MC_]RECEIVE_AND_POST

Conversation States

End of Data for a Basic Conversation

Troubleshooting

[MC_]RECEIVE_AND_WAIT

Issuing the Verb in SEND State

State Change

RECEIVE_AND_WAIT End of Data

[MC_]RECEIVE_IMMEDIATE

RECEIVE_IMMEDIATE End of Data

Testing the what_rcvd Parameter

[MC_]REQUEST_TO_SEND

[MC_]SEND_CONVERSATION

[MC_]SEND_DATA

[MC_]SEND_ERROR

[MC_]TEST_RTS

Chapter 6	APPC Extensions for the Windows Environment

Chapter 7	SNA Server Enhancements to the Windows Environment

Chapter 8	Common Service Verbs

Chapter 9	CSV Extensions for the Windows Environment

Appendix A	Common APPC Return Codes

Appendix B	Common CSV Return Codes

Appendix C	Sample APPC TPs in the SDK

List of Figures

List of Tables


Chapter 6 Contents, APPC Programmer's Guide
Microsoft SNA Server

APPC Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to APPC

Chapter 2	Transaction Programs

Chapter 3	APPC Management Verbs

Chapter 4	APPC TP Verbs

Chapter 5	APPC Conversation Verbs

Chapter 6	APPC Extensions for the Windows Environment

WinAsyncAPPC( )

WinAsyncAPPCEx( )

WinAPPCCancelAsyncRequest( )

WinAPPCCancelBlockingCall( )

WinAPPCCleanup( )

WinAPPCIsBlocking( )

WinAPPCStartup( )

WinAPPCSetBlockingHook( )

WinAPPCUnhookBlockingHook( )

Chapter 7	SNA Server Enhancements to the Windows Environment

Chapter 8	Common Service Verbs

Chapter 9	CSV Extensions for the Windows Environment

Appendix A	Common APPC Return Codes

Appendix B	Common CSV Return Codes

Appendix C	Sample APPC TPs in the SDK

List of Figures

List of Tables


Chapter 7 Contents, APPC Programmer's Guide
Microsoft SNA Server

APPC Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to APPC

Chapter 2	Transaction Programs

Chapter 3	APPC Management Verbs

Chapter 4	APPC TP Verbs

Chapter 5	APPC Conversation Verbs

Chapter 6	APPC Extensions for the Windows Environment

Chapter 7	SNA Server Enhancements to the Windows Environment

GetAppcConfig( )

GetAppcReturnCode( )

GetCsvReturnCode( )

Chapter 8	Common Service Verbs

Chapter 9	CSV Extensions for the Windows Environment

Appendix A	Common APPC Return Codes

Appendix B	Common CSV Return Codes

Appendix C	Sample APPC TPs in the SDK

List of Figures

List of Tables


Chapter 8 Contents, APPC Programmer's Guide
Microsoft SNA Server

APPC Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to APPC

Chapter 2	Transaction Programs

Chapter 3	APPC Management Verbs

Chapter 4	APPC TP Verbs

Chapter 5	APPC Conversation Verbs

Chapter 6	APPC Extensions for the Windows Environment

Chapter 7	SNA Server Enhancements to the Windows Environment

Chapter 8	Common Service Verbs

Windows CSV Overview

SNA Server Asynchronous Support

Before Using Windows CSV

Creating Specific NetView User Alerts

Using CSVs in C Programs

Sample Programs

Verb Control Block

Bit Ordering

WINCSV Definition

WINCSV.H File

Issuing a CSV

Common Service Verbs

CONVERT

COPY_TRACE_TO_FILE

DEFINE_TRACE

GET_CP_CONVERT_TABLE

LOG_MESSAGE

TRANSFER_MS_DATA

Chapter 9	CSV Extensions for the Windows Environment

Appendix A	Common APPC Return Codes

Appendix B	Common CSV Return Codes

Appendix C	Sample APPC TPs in the SDK

List of Figures

List of Tables


Chapter 9 Contents, APPC Programmer's Guide
Microsoft SNA Server

APPC Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to APPC

Chapter 2	Transaction Programs

Chapter 3	APPC Management Verbs

Chapter 4	APPC TP Verbs

Chapter 5	APPC Conversation Verbs

Chapter 6	APPC Extensions for the Windows Environment

Chapter 7	SNA Server Enhancements to the Windows Environment

Chapter 8	Common Service Verbs

Chapter 9	CSV Extensions for the Windows Environment

WinCSVCleanup( )

WinAsyncCSV( )

WinCSVStartup( )

Appendix A	Common APPC Return Codes

Appendix B	Common CSV Return Codes

Appendix C	Sample APPC TPs in the SDK

List of Figures

List of Tables


Appendix A Contents, APPC Programmer's Guide
Microsoft SNA Server

APPC Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to APPC

Chapter 2	Transaction Programs

Chapter 3	APPC Management Verbs

Chapter 4	APPC TP Verbs

Chapter 5	APPC Conversation Verbs

Chapter 6	APPC Extensions for the Windows Environment

Chapter 7	SNA Server Enhancements to the Windows Environment

Chapter 8	Common Service Verbs

Chapter 9	CSV Extensions for the Windows Environment

Appendix A	Common APPC Return Codes

Primary Return Codes

Secondary Return Codes

Appendix B	Common CSV Return Codes

Appendix C	Sample APPC TPs in the SDK

List of Figures

List of Tables


Appendix BContents, APPC Programmer's Guide
Microsoft SNA Server

APPC Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to APPC

Chapter 2	Transaction Programs

Chapter 3	APPC Management Verbs

Chapter 4	APPC TP Verbs

Chapter 5	APPC Conversation Verbs

Chapter 6	APPC Extensions for the Windows Environment

Chapter 7	SNA Server Enhancements to the Windows Environment

Chapter 8	Common Service Verbs

Chapter 9	CSV Extensions for the Windows Environment

Appendix A	Common APPC Return Codes

Appendix B	Common CSV Return Codes

Primary Return Codes

Secondary Return Codes

Appendix C	Sample APPC TPs in the SDK

List of Figures

List of Tables


Appendix C Contents, APPC Programmer's Guide
Microsoft SNA Server

APPC Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to APPC

Chapter 2	Transaction Programs

Chapter 3	APPC Management Verbs

Chapter 4	APPC TP Verbs

Chapter 5	APPC Conversation Verbs

Chapter 6	APPC Extensions for the Windows Environment

Chapter 7	SNA Server Enhancements to the Windows Environment

Chapter 8	Common Service Verbs

Chapter 9	CSV Extensions for the Windows Environment

Appendix A	Common APPC Return Codes

Appendix B	Common CSV Return Codes

Appendix C	Sample APPC TPs in the SDK

Building the TPs

TPSETUP

TPSTART

APPC Send and Receive TPs

Multithreaded Send and Receive TPs

List of Figures

List of Tables


List of Tables Contents, APPC Programmer's Guide
Microsoft SNA Server

APPC Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to APPC

Chapter 2	Transaction Programs

Chapter 3	APPC Management Verbs

Chapter 4	APPC TP Verbs

Chapter 5	APPC Conversation Verbs

Chapter 6	APPC Extensions for the Windows Environment

Chapter 7	SNA Server Enhancements to the Windows Environment

Chapter 8	Common Service Verbs

Chapter 9	CSV Extensions for the Windows Environment

Appendix A	Common APPC Return Codes

Appendix B	Common CSV Return Codes

Appendix C	Sample APPC TPs in the SDK

List of Figures

Communication Between TPs

Partner TP Invoking Another TP

List of Tables


List of Tables Contents, APPC Programmer's Guide
Microsoft SNA Server

APPC Programmer's Guide

Contents

Before You Begin

Chapter 1	Introduction to APPC

Chapter 2	Transaction Programs

Chapter 3	APPC Management Verbs

Chapter 4	APPC TP Verbs

Chapter 5	APPC Conversation Verbs

Chapter 6	APPC Extensions for the Windows Environment

Chapter 7	SNA Server Enhancements to the Windows Environment

Chapter 8	Common Service Verbs

Chapter 9	CSV Extensions for the Windows Environment

Appendix A	Common APPC Return Codes

Appendix B	Common CSV Return Codes

Appendix C	Sample APPC TPs in the SDK

List of Figures

List of Tables

APPC Conversation Verbs

Controlling the Characteristics of TPs

Conversation States

Methods for Receiving Data Asynchronously

Registry Entries for Invokable TPs on Windows NT-Based Clients

Environment Variables for Invokable TPs on Windows-Based Clients

Environment Variables for Invokable TPs on OS/2-Based Clients

Common Service Verbs


Before You Begin
1 of 5

Before You Begin

The Microsoft SNA Server APPC Programmer's Guide contains the information required to develop C-based programs using Advanced Program-to-Program Communications (APPC) to exchange data in a systems network architecture (SNA) environment.

To use this manual effectively, you should be familiar with:

Microsoft [image] SNA Server (SNA Server).

Microsoft C version 5.1 or later.

Microsoft Windows NT [image].

MS-DOS [image] version 3.2 or later.

Microsoft Windows [image] graphical environment version 3.0 or later.

SNA concepts.

IBM [image] Extended Services for OS/2 [image] version 1.0 (IBM ES for 0S/2 version 1.0).


How to Use This Guide
Before You Begin	2 of 5

How to Use This Guide

This manual covers the following topics:

Chapter 1, "Introduction to APPC"

Introduces the fundamental concepts of APPC.

Chapter 2, "Transaction Programs"

Provides background information for writing transaction programs (TPs).

Chapter 3, "APPC Management Verbs"

Describes each management verb.

Chapter 4, "APPC TP Verbs"

Describes each TP verb.

Chapter 5, "APPC Conversation Verbs"

Describes each conversation verb.

Chapter 6, "APPC Extensions for the Windows Environment"

Describes the API  extensions to the Windows APPC that allow asynchronous communication.

Chapter 7, "SNA Server Enhancements to the Windows Environment"

Describes the API extensions to Windows APPC and CSV.

Chapter 8, "Common Service Verbs"

Lists and describes the Common Service Verbs (CSVs) in alphabetical order and explains how to use them in C Programs.

Chapter 9, "CSV Extensions for the Windows Environment"

Describes the API extensions to the Windows CSV.

Appendix A, "Common APPC Return Codes"

Lists all APPC return codes in hexadecimal order.

Appendix B, "Common CSV Return Codes"

Lists all return codes in hexadecimal order.

Appendix C, "Sample APPC TPs in the SDK"

Provides sample TPs.


Document Conventions
Before You Begin	3 of 5

Document Conventions

Throughout this manual, the following conventions distinguish elements of text.

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 is an alphabetical list of common abbreviations used in this manual.

Abbreviation	Meaning

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

DFT	distributed function terminal

DLC	data link control

DLL	dynamic-link library

EBCDIC	Extended Binary Coded Decimal Interchange Code

GDS	general data stream

K	kilobyte

LAN	local area network

LL	record-length field

LU	logical unit

LUA	conventional Logical Unit Application programming interface

MB	megabyte

MDI	multiple document interface

NCP	Network Control Panel

NMVT	Network Management Vector Transport

OS	operating system

PIP	program initialization parameter

PLU	primary logical unit

PU	physical unit

PVC	permanent virtual circuit

QLLC	qualified logical link control

RU	request/response unit

RUI	Request Unit Interface

SCM	Service Control Manager

SDLC	Synchronous Data Link Control

SLI	Session Level Interface

SNA	Systems Network Architecture

SSCP	system services control point

SVC	switched virtual circuit

TP	transaction program

VCB	verb control block

VTAM	Virtual Telecommunications Access Method


Finding Further Information
Before You Begin	5 of 5

Finding Further Information

This manual does not describe the products, architectures, or standards developed by other companies or organizations. For information about the Microsoft Windows graphical environment, Windows NT, and the MS-DOS and IBM [image] OS/2 [image] operating systems, consult your product documentation.

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

Microsoft SNA Server CPI-C Programmer's Guide

Microsoft SNA Server LUA 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, 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


Introduction to APPC
Chapter 1	1 of 15

Introduction to APPC

This chapter introduces the fundamental concepts of Advanced Program-to-Program Communications (APPC) in a distributed processing environment. The APPC verbs are presented, along with an overview of the Windows APPC extensions and sections on using the verbs in C programs, implementing APPC, and operating system considerations. A detailed description of each APPC verb is provided in Chapters 3 through 5.

APPC is an application programming interface (API) that allows peer-to-peer communications in a Systems Network Architecture (SNA) environment. By using APPC, programs distributed across a network can work together—communicating with each other and exchanging data—to accomplish a single processing task. A processing task can query a remote database, copy a remote file, send or receive electronic mail, and so on.


APPC Verbs
Introduction to APPC	2 of 15

APPC Verbs

APPC verbs fall into three categories:

Management

Transaction program (TP)

Conversation

The management verbs are:

CNOS

DISPLAY

TP verbs start and end TPs. The TP verbs are:

GET_TP_PROPERTIES

TP_ENDED

TP_STARTED

Conversation verbs enable TPs to allocate a conversation, deallocate a conversation, send and receive data, and change conversation states. The conversation verbs are listed in Table 1.1.

Conversation verbs fall into two groups: Mapped conversation verbs and Basic conversation verbs. In typical situations, end-user TPs use Mapped conversations and service TPs use Basic conversations. The Mapped conversation is intended for programs that use the conversation directly. The Basic conversation is intended for more complex programs that provide services to other users.

Mapped conversation verbs can only be issued by a TP in Mapped conversation, while Basic conversation verbs are reserved for Basic conversations. There is one exception to this rule. ALLOCATE can be used to start either a Basic or a Mapped conversation.

Table 1.1  APPC Conversation Verbs

Mapped conversation verbs	Basic conversation verbs
MC_ALLOCATE	ALLOCATE
MC_CONFIRM	CONFIRM
MC_CONFIRMED	CONFIRMED
MC_DEALLOCATE	DEALLOCATE
MC_FLUSH	FLUSH
MC_GET_ATTRIBUTES	GET_ATTRIBUTES
GET_TYPE	GET_TYPE
MC_PREPARE_TO_RECEIVE	PREPARE_TO_RECEIVE
RECEIVE_ALLOCATE	RECEIVE_ALLOCATE
MC_RECEIVE_AND_POST	RECEIVE_AND_POST
MC_RECEIVE_AND_WAIT	RECEIVE_AND_WAIT
MC_RECEIVE_IMMEDIATE	RECEIVE_IMMEDIATE
MC_REQUEST_TO_SEND	REQUEST_TO_SEND
MC_SEND_CONVERSATION	SEND_CONVERSATION
MC_SEND_DATA	SEND_DATA
MC_SEND_ERROR	SEND_ERROR
MC_TEST_RTS	TEST_RTS
Mapped and Basic verbs have the same functions in their respective types of conversation. For example, MC_CONFIRM performs the same function in a Mapped conversation as CONFIRM performs in a Basic conversation.


APPC Verb Summary
Introduction to APPC	3 of 15

APPC Verb Summary

This section briefly describes each APPC verb. The APPC verbs are grouped by function. For a more detailed explanation of a particular verb, see Chapters 3 through 5.

The following verbs are required to start a conversation between two TPs. For more information on this subject, see Chapter 2, "Transaction Programs."

TP_STARTED

Issued by the local TP. This verb notifies APPC that the local TP is starting. Upon successful execution, this verb returns a TP identifier (tp_id) for the local TP.

MC_ALLOCATE or ALLOCATE

Issued by the local TP. This verb allocates a session between the local logical unit (LU) and a partner LU and establishes a conversation between the local TP and the partner TP.

ALLOCATE can establish either a Basic or Mapped conversation. MC_ALLOCATE can start only a Mapped conversation. Once the conversation is allocated, APPC uses this verb to return a conversation identifier (conv_id) through this verb.

RECEIVE_ALLOCATE

Issued by the partner TP. This verb confirms that the partner TP is ready to begin a conversation with the local TP, which issued [MC_]ALLOCATE. Upon successful execution, this verb returns a tp_id for the partner TP and the conv_id.

The following conversation verbs send data to the partner TP.

MC_SEND_DATA or SEND_DATA

Puts data in the local LU's send buffer for transmission to the partner TP.

The data collected in the local LU's send buffer is transmitted to the partner LU (and partner TP) when one of the following occurs:

The send buffer fills up.

The local TP issues [MC_]FLUSH, [MC_]CONFIRM, or [MC_]DEALLOCATE (or another verb that flushes the local LU's send buffer).

MC_FLUSH or FLUSH

Flushes the local LU's send buffer, sending the contents of the buffer to the partner LU (and TP). If the send buffer is empty, no action takes place.

MC_CONFIRM or CONFIRM

Sends the contents of the local LU's send buffer and a confirmation request to the partner TP.

MC_PREPARE_TO_RECEIVE or PREPARE_TO_RECEIVE

Changes the state of the conversation from SEND to RECEIVE. Before changing the conversation state, this verb performs the equivalent of [MC_]FLUSH or [MC_]CONFIRM. After this verb has successfully executed, the TP can receive data.

MC_REQUEST_TO_SEND or REQUEST_TO_SEND

Informs the partner TP that the local TP wants to send data. If the partner TP issues [MC_]PREPARE_TO_RECEIVE or [MC_]RECEIVE_AND _WAIT, the conversation state changes to RECEIVE for the partner TP, which makes it possible for the local TP to begin sending data.

The following conversation verbs allow a TP to receive data from its partner TP.

MC_RECEIVE_AND_WAIT or RECEIVE_AND_WAIT

Issuing this verb while the conversation is in RECEIVE state causes the local TP to receive any data that is currently available from the partner TP. If no data is available, the local TP waits for data to arrive.

Issuing this verb while the conversation is in SEND state flushes the LU's send buffer and changes the conversation state to RECEIVE. The local TP then begins to receive data.

MC_RECEIVE_IMMEDIATE or RECEIVE_IMMEDIATE

This verb receives any data that is currently available from the partner TP. If no data is available, the local TP does not wait.

MC_RECEIVE_AND_POST or RECEIVE_AND_POST

(Windows NT and OS/2 operating systems)

Issuing this verb while the conversation is in RECEIVE state changes the conversation state to PENDING_POST and causes the local TP to receive data asynchronously. This allows the local TP to proceed with processing while data is still arriving at the local LU.

Issuing this verb while the conversation is in SEND state flushes the LU's send buffer and changes the conversation state to PENDING_POST. The local TP then begins to receive data asynchronously.

MC_TEST_RTS or TEST_RTS

Determines whether a REQUEST_TO_SEND notification has been received.

The following conversation verbs confirm receipt of data or report an error.

MC_CONFIRMED or CONFIRMED

Replies to a confirmation request from the partner TP. It informs the partner TP that the local TP has received and processed the data without error.

MC_SEND_CONVERSATION or SEND_CONVERSATION

Issued by the invoking TP, this verb allocates a session between the local LU and partner LU, sends data on the session, and then deallocates the session.

MC_SEND_ERROR or SEND_ERROR

Notifies the partner TP that the local TP has encountered an application-level error.

The following verbs get information from TPs.

MC_GET_ATTRIBUTES or GET_ATTRIBUTES

Used by a TP to get the attributes of the conversation.

GET_TP_PROPERTIES

This TP verb returns attributes of the TP and the current transaction.

GET_TYPE

This conversation verb is used by a TP to determine the conversation type (Basic or Mapped) of a particular conversation. With this information, the TP can decide whether to issue Basic or Mapped conversation verbs.

The following verbs provide management functions.

CNOS (Change Number of Sessions)

Establishes APPC LU 6.2 session limits.

DISPLAY

Returns configuration information and current operating values for the SNA node.

The following verbs end a conversation.

MC_DEALLOCATE or DEALLOCATE

Deallocates a conversation between two TPs. Before deallocating the conversation, this verb performs the equivalent of [MC_]FLUSH or [MC_]CONFIRM.

TP_ENDED

This TP verb is issued by both the local and partner TPs. It notifies APPC that the TP is ending. Issuing this verb also terminates any conversations that may be active.


Windows APPC Overview
Introduction to APPC	4 of 15

Windows APPC Overview

In order to provide one common API to port applications from various operating systems to Windows NT and Windows version 3.x, a Windows SNA standard was created. As a direct result of this work, Windows APPC was developed.

The information provided in this guide is source- and execute-code compatible with the following implementations of APPC:

SNA Server APPC applications can reside on the server, or on a client running Windows NT, Windows, MS-DOS, or OS/2.

IBM APPC Extended Services for OS/2 version 1.0.

Programs written to use this implementation of APPC can exchange data with programs written to use other implementations of APPC that adhere to the SNA LU 6.2 architecture.


Windows APPC Asynchronous Support
Introduction to APPC	5 of 15

Windows APPC Overview

Windows APPC Asynchronous Support

Asynchronous call completion returns the initial call immediately so the application can continue with other processes. A program that issues a call 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.

SNA Server uses the RegisterWindowsMessage for asynchronous support. With "WinAsyncAPPC" as the input string, you pass a Windows handle by which you will be notified of verb completion. You then issue your verb, and once it completes, a message is posted to the Windows handle that you passed, notifying you that the verb is complete.

With the exception of asynchronous RECEIVE_AND_WAIT and RECEIVE_AND_POST, which can issue certain other verbs while pending, a conversation can have only one incomplete operation at any time. For more information on using asynchronous RECEIVE_AND_WAIT and RECEIVE_AND_POST, see Chapter 5, "APPC Conversation Verbs."


Before Using Windows APPC
Introduction to APPC	6 of 15

Windows APPC Overview

Before Using Windows APPC

This section describes the APPC verbs and Windows enhancements that are of particular importance in this version of SNA Server:

The following APPC verbs contain important features and should be read before using this version of Windows APPC:

TP_STARTED

Issued by the invoking TP, TP_STARTED notifies APPC that the TP is starting. For a user or group who will be using TPs, 5250 emulators, and/or APPC applications, you can assign a default local APPC LU and a default remote APPC LU. These default LUs are accessed when the user or group member starts an APPC program (a TP, 5250 emulator, or APPC application) and the program does not specify LU aliases. For more information on using default LUs, see the Microsoft SNA Server Administration Guide.

[MC_]ALLOCATE

Issued by the invoking TP, this verb allocates a session between the local LU and partner LU and (in conjunction with RECEIVE_ALLOCATE) establishes a conversation between the invoking TP and the invokable TP. After this verb executes successfully, APPC generates a conversation identifier (conv_id). The conv_id is a required parameter for all other APPC conversation verbs.

For a user or group using TPs, 5250 emulators, and/or APPC applications, you can assign default local and remote LUs. In this case, the field for LU alias is left blank or NULL and the default LUs are accessed when the user or group member starts an APPC program. For more information on using default LUs, see the Microsoft SNA Server Administration Guide.

For Windows version 3.x systems, Microsoft recommends using WinAsyncAPPC, rather than the blocking version of these calls. For more information on using the Windows extensions, see Chapter 6, "APPC Extensions for the Windows Environment."

RECEIVE_ALLOCATE

Issued by the invokable TP to confirm that it is ready to begin a conversation with the invoking TP, which issued [MC_]ALLOCATE. This must be the first APPC verb issued by the invokable TP. The initial state is RESET. If the verb executes successfully (primary_rc is AP_OK), the state changes to RECEIVE.

[MC_]RECEIVE_AND_POST

Receives any data that is currently available from the partner TP. If no data is currently available, the local TP waits for data to arrive. For Windows version 3.x systems, Microsoft recommends using WinAsyncAPPC, rather than the blocking version of this call. For information on using the Windows extensions, see Chapter 6, "APPC Extensions for the Windows Environment."

Note

RECEIVE_AND_WAIT has been altered to act like RECEIVE_AND_POST. While an asynchronous RECEIVE_AND_WAIT is outstanding, the following verbs can be issued:

REQUEST_TO_SEND

GET_TYPE

GET_ATTRIBUTES

TEST_RTS

DEALLOCATE (AP_ABEND_PROG, AP_ABEND_SVC, or AP_ABEND_TIMER)

SEND_ERROR

TP_ENDED

[MC_]RECEIVE_AND_POST

Receives application data and status information asynchronously. This allows the local TP to proceed with processing while data is still arriving at the local LU. RECEIVE_AND_POST is only supported by the Windows NT and OS/2 operating systems. For similar functionality under the Windows version 3.x system, use RECEIVE_AND_WAIT in conjunction with WinAsyncAPPC. For information on using Windows extensions, see Chapter 6, "APPC Extensions for the Windows Environment."

Note

While an asynchronous RECEIVE_AND_POST is outstanding, the following verbs can be issued:

REQUEST_TO_SEND

GET_TYPE

GET_ATTRIBUTES

TEST_RTS

DEALLOCATE (AP_ABEND_PROG, AP_ABEND_SVC, or AP_ABEND_TIMER)

SEND_ERROR

TP_ENDED

Windows APPC provides a complete set of Windows extensions that allow asynchronous communication. These extensions provide maximum programming compatibility between Windows NT and Windows version 3.x. They include the following:

WinAsyncAPPC

Provides an asynchronous version for all of the APPC verbs. Microsoft recommends that you use this extension instead of the blocking versions of the verbs if you will run your application under Windows version 3.x. APPC verbs that can block are:

[MC_]ALLOCATE

[MC_]CONFIRM

[MC_]CONFIRMED

[MC_]DEALLOCATE

[MC_]FLUSH

[MC_]PREPARE_TO_RECEIVE

RECEIVE_ALLOCATE

[MC_]RECEIVE_AND_WAIT

[MC_]REQUEST_TO_SEND

[MC_]SEND_CONVERSATION

[MC_]SEND_DATA

[MC_]SEND_ERROR

TP_ENDED

TP_STARTED

WinAPPCCancelAsyncRequest

Cancels an outstanding WinAsyncAPPC-based request.

WinAPPCCancelBlockingCall

Cancels any outstanding blocking operation for its thread.

WinAPPCCleanup

Terminates and deregisters an application from a Windows APPC implementation.

Important

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

WinAPPCIsBlocking

Determines if a thread is executing while waiting for a previous blocking call to finish.

WinAPPCStartup

Registers an application and specifies the version of Windows APPC required.

Important

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

WinAPPCSetBlockingHook

Allows a Windows APPC implementation to block APPC function calls by means of a new function. This call is used by Windows version 3.x applications to make blocking calls without blocking the rest of the system. Blocking procedures apply only if you do not use asynchronous calls. If a function needs to block, the blocking procedure is called repeatedly until the original request completes. This allows Windows to continue to run while the original application waits for the call to return. Note that while inside the blocking procedure, the application can be re-entered. WinAPPCSetBlockingHook is used by Windows version 3.x applications that go into a PeekMessageLoop to make blocking calls without blocking the rest of the system.

Note

By default, Windows NT does not go into a PeekMessageLoop, but rather, it actually blocks on an event waiting for the call to complete. The only time it would be necessary to use WinAPPCSetBlockingHook for Windows NT is when a single-threaded application for both Windows NT and Windows version 3.x share common source code. In this case, you must explicitly make this call. Contrast with WinAPPCIsBlocking and WinAPPCUnhookBlockingHook.

WinAPPCUnhookBlockingHook

Removes any previous blocking hook that has been installed and reinstalls the default blocking mechanism.

SNA Server permits one outstanding Windows APPC asynchronous call per connection and one blocking verb per thread. For example:

Note

The exceptions to the rule of one outstanding asynchronous call are RECEIVE_AND_POST and RECEIVE_AND_WAIT. While these verbs are outstanding, certain other verbs can also be called. For more information, see RECEIVE_AND_POST or RECEIVE_AND_WAIT described in Chapter 5, "APPC Conversation Verbs."

SNA Server supports the following APPC management verbs:

CNOS

Establishes APPC LU 6.2 session limits.

DISPLAY

Returns configuration information and current operating values for the SNA node.


Using APPC Verbs in C Programs
Introduction to APPC	7 of 15

Using APPC Verbs in C Programs

This implementation of APPC is available for programs written in Microsoft C version 5.1 or later. A C program calls APPC through the external function APPC. For compatibility with previous versions of Microsoft C, the external function APPC_C is also supported.

Note

Compilers other than the Microsoft C compiler can also be used to run this implementation of APPC.


Verb Control Block
Introduction to APPC	8 of 15

Using APPC Verbs in C Programs

Verb Control Block

The only parameter passed to the APPC function is the address of a verb control block. The VCB is a structure made up of variables that identify the APPC verb to be executed, supply information to be used by the verb, and contain information returned by the verb when execution is complete. Each APPC verb has its own VCB structure, which is declared in the WINAPPC.H header file. For compatibility with earlier versions, the APPC_C.H header file is also supported.

You can find the WINAPPC.H file in the SNA Server Software Development Kit.


APPC Definition
Introduction to APPC	9 of 15

Using APPC Verbs in C Programs

APPC Definition

The prototype definitions of the APPC function are as follows:

The VCB address parameter, a 32bit pointer, is declared as a long integer (and thus requires casting from a pointer to a long integer).


Issuing an APPC Verb
Introduction to APPC	10 of 15

Using APPC Verbs in C Programs

Issuing an APPC Verb

The following procedure is required to issue a blocking APPC verb. In this case, the verb issued is MC_SEND_DATA.

1.	Create a structure variable from the VCB structure that applies to the APPC verb to be issued.

The VCB structures are declared in WINAPPC.H; one of these structures is:

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

3.	Assign values to the VCB variables that supply information to APPC.

The values AP_MAPPED_CONVERSATION and AP_M_SEND_DATA are symbolic constants representing integers. These constants are defined in WINAPPC.H.

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

Use WinAsyncAPPC if you are running the application under Windows version 3.x.

To call WinAsyncAPPC:

When the asynchronous operation is complete, the application's window hWnd receives the message returned by RegisterWindowMessage with "WinAsyncAPPC" as the input string. For more information on using Windows extensions, see Chapter 6, "APPC Extensions for the Windows Environment."

5.	Use the variables that were returned by APPC.


Windows NT Considerations
Introduction to APPC	11 of 15

Windows NT Considerations

This section provides information about developing TPs for the Windows NT system.

Byte ordering

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

By default, Intel byte ordering is used. However, for in-line environment defining, NON_INTEL_BYTE_ORDER will do the required flipping for constants. Nonconstant input parameters in VCBs (such as lengths, pointers, and so on) are always in the native format.

For example, the primary return code of AP_PARAMETER_CHECK is defined to have a value of X'001'. Depending on the environment, the constant AP_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 is an example of how the macro can be used:

Packing

For performance considerations, 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 APPC, and the handle must have EVENT_MODIFY_STATE access to the event.

Multiple Threads

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

Note

With the exception of RECEIVE_AND_POST and RECEIVE_AND_WAIT, only one conversation verb can be outstanding at a time on any conversation; however, other verbs can be issued for other conversations. This same guideline also applies to TP verbs and TPs. Although multiple TP verbs can be issued, only one TP verb can be outstanding at a time on a TP. This applies to both multithreaded applications and single-threaded applications that use asynchronous calls. For more information on using RECEIVE_AND_POST and RECEIVE_AND_WAIT, see Chapter 5, "APPC Conversation Verbs."

Yielding to other components

By default, and because the Windows NT environment is multithreaded, there is no need to yield to other components. However, if an application is single-threaded and is intended for both Windows NT and Windows version 3.x, use the Windows extensions WinAPPCSetBlockingHook and WinAPPC-UnhookBlockingHook. These extensions must be explicitly called to accomplish the yield procedure. For more information on using Windows extensions, see Chapter 6, "APPC Extensions for the Windows Environment."

Run-Time Linking

For a TP to be dynamically linked to APPC at run time, the TP must issue the following calls:

LoadLibrary to load the dynamic load libraries WINAPPC.DLL or WAPPC32.DLL.

GetProcAddress to specify APPC on all the desired entry points to the dynamic-link library (DLL) such as WinAsyncAPPC, APPC, WinAPPCStartup, and WinAPPCCleanup.

Issue the FreeLibrary call when the APPC library is no longer required.

For a TP to be dynamically linked to CSV at run time, the TP must issue the following calls:

LoadLibrary to load WINCSV.DLL or WINCSV32.DLL, the dynamic load libraries for Windows CSV.

GetProcAddress to specify CSV on all the desired entry points to the dynamic-link library (DLL) such as ACSSVC, WinAsyncCSV, WinCSVStartup, and WinCSVCleanup.

Issue the FreeLibrary call when the CSV library is no longer required.

Limits

For Windows NT, the number of simultaneous CSVs allowed per process is 64. Only one of these verbs per thread can be synchronous.

Registering and deregistering applications

All Windows APPC applications must call WinAPPCStartup at the beginning of the session to register the application and WinAPPCCleanup at the end of the session to deregister the application. For more information on using Windows extensions, see Chapter 6, "APPC Extensions for the Windows Environment."

All Windows CSV applications must call the Windows SNA extension WinCSVStartup at the beginning of the session to register the application and WinCSVCleanup to deregister the application when the session is finished. For more information on using Windows SNA extensions, see Chapter 9, "CSV 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
WINAPPC.DLL	WAPPC32.DLL
WINCSV.DLL	WINCSV32.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 Considerations
Introduction to APPC	12 of 15

Windows Considerations

This section summarizes information about developing TPs for the Windows version 3.x system.

Packing

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

[MC_]RECEIVE_AND_POST

This verb has been replaced for Windows version 3.x by calling [MC_]RECEIVE_AND_WAIT, via WinAsyncAPPC. For information on using [MC_]RECEIVE_AND_WAIT, see Chapter 5, "APPC Conversation Verbs." For information about the Windows extensions, see Chapter 6, "APPC Extensions for the Windows Environment."

Simultaneous conversations

A TP can participate in as many as 64 conversations simultaneously with the Windows environment. However, if more than 1 TP is active at once, the total number of conversations cannot exceed 64.

Load-time linking

For a TP to be dynamically linked to APPC 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 TP:

Link the TP to WINAPPC.LIB, which contains the entry-point linkage information for APPC. If you intend to use Common Service Verbs (CSVs), you must also link to WINCSV.LIB, which contains the entry-point information for CSVs.

Run-time linking

For a TP to be dynamically linked to APPC at run time, the TP must issue the following calls:

LoadLibrary to load WINAPPC.DLL, the dynamic load library for APPC.

GetProcAddress to specify APPC on all the desired entry points to the DLL such as WinAsyncAPPC, APPC, WinAPPCStartup, and WinAPPCCleanup.

Issue the FreeLibrary call when the APPC library is no longer required.

Limits

ForAPPC limits, see your product documentation. For the Windows version 3.x system, the number of simultaneous CSVs allowed per computer is 64. Only one of these verbs per process can by synchronous.

Blocking routines

Do not use blocking functions if your application will run in Windows version 3.x. Instead, use WinAsyncAPPC in conjunction with a WinAsyncAPPC Windows message. For information on using Windows extensions, see Chapter 6, "APPC Extensions for the Windows Environment."

Yielding to other components

Because Windows version 3.x is single-threaded, there is only one thread of execution. In the case where a function must wait before completing the task, the only thread of execution could block to allow other tasks to proceed.

Note

This means that while in a blocking call, the calling application's Window procedure may be called. To test if this is the case, the extension WinAPPCIsBlocking is provided. Any attempt to make a second blocking call with one already outstanding will cause the call to fail with the return code AP_THREAD_BLOCKING.

Windows APPC and CSV contain a default yield procedure for Windows version 3.x that can yield through to other functions while waiting for the first function to complete. The default is:

Besides the default yield procedure, Windows APPC provides WinAPPCSetBlockingHook to support applications that require more complex message processing. For more information on using the Windows extensions, see Chapter 6, "APPC Extensions for the Windows Environment."

WinAPPCSetBlockingHook allows a Windows APPC implementation to block APPC function calls by means of a new function. This call is used by Windows version 3.x applications to make blocking calls without blocking the rest of the system. To call WinAPPCSetBlockingHook:

WinAPPCUnhookBlockingHook removes any previous blocking hook that has been installed and reinstalls the default blocking mechanism. To call WinAPPCUnhookBlockingHook:

For more information on using Windows extensions, see Chapter 6, "APPC Extensions for the Windows Environment."

Registering and deregistering applications

All Windows APPC applications must call WinAPPCStartup at the beginning of the session to register the application and WinAPPCCleanup at the end of the session to deregister the application. For more information on using these  extensions, see Chapter 6, "APPC Extensions for the Windows Environment."

All Windows CSV applications must call the Windows SNA extension WinCSVStartup at the beginning of the session to register the application and WinCSVCleanup to deregister the application when the session is finished. For more information on using these extensions, see Chapter 9, "CSV Extensions for the Windows Environment."


Translating Service TP Names to ASCII for WIN.INI
Introduction to APPC	13 of 15

Windows Considerations

Translating Service TP Names to ASCII for WIN.INI

For service TPs on SNA Server clients running Windows version 3.x or OS/2, a line must be added to the WIN.INI or SNA.INI file, specifying the TP name in ASCII. For information about converting the name of a service TP to ASCII, see Chapter 2, "Transaction Programs."


MSDOS Considerations
Introduction to APPC	14 of 15

MS-DOS Considerations

This section summarizes information about developing TPs for the MS-DOS system. Windows APPC provides two interfaces to support MS-DOS: a call level library interface (DOSACS.LIB) and AS/400 [image] PC Support Router.

[MC_]RECEIVE_AND_POST

This verb is not available with MS-DOS.

AS/400 PC Support Router API

MS-DOS support for Windows APPC is handled in one of two ways:

The call-level interface through the library provided by SNA Server (DOSACS.LIB)

The software interrupt PC Support Router API

For additional information on the PC Support Router API, see the IBM PC Support/400 Application Program Interface Reference, part number SC41-8254.

Packing

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

Link library

The link library for APPC is DOSACS.LIB.

Simultaneous conversation

In an MS-DOS environment, a TP can participate in as many as 16 conversations simultaneously.

Partner TPs

No support is provided for autostarting MS-DOS partner TPs. The call level interface contains the same syntax as that of OS/2.

SnaBase

When running a TP on an SNA Server MS-DOS – based client, you must use SnaBase, which supports APPC. If you attempt to use something other than SnaBase, your TP will not run.

Limits

Additional system limits are described in the Microsoft SNA Server Administration Guide.

CSV Restrictions when SnaBase not loaded

If your application is running on an SNA Server Windows - based client or MS-DOS–based client, and the SnaBase has not been loaded, only the following verbs are available:

GET_CP_CONVERT_TABLE

CONVERT

Under these circumstances, CONVERT cannot use a type G conversion table. Attempting to use a type G conversion table causes the system to return the SV_TABLE_ERROR primary return code.

Attempting to issue COPY_TRACE_TO_FILE, DEFINE_TRACE, LOG_MESSAGE, or TRANSFER_MS_DATA causes the system to return the SV_COMM_SUBSYSTEM_NOT_LOADED primary return code.


OS/2 Considerations
Introduction to APPC	15 of 15

OS/2 Considerations

This section summarizes information about developing TPs for the OS/2 system. It lists information about APPC verbs, followed by information about CSVs.

Packing

VCBs 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 TP. A data buffer must reside on an unnamed, shared data segment and it must fit entirely within the data segment. Many data buffers can reside on the same data segment.

To allocate a data segment, use the DosAllocSeg function with Flags equal to 1.

To improve efficiency, a TP can reuse the same data segment each time it issues a verb requiring a data buffer. If necessary, the program can allocate a segment of up to 64K and then partition the segment into data buffers.

VCB segment

The segment containing the VCB must be a writable segment.

Simultaneous conversations

A TP can simultaneously participate in as many as 64 conversations for each OS/2 process.

Load-time linking

For a TP to be dynamically linked to APPC 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 TP:

Link the TP to APPC.LIB, which contains the entry-point linkage information for various APIs, including APPC.

Run-time linking

For a TP to be dynamically linked to APPC at run time, the TP must issue the following calls:

DosLoadModule to load APPC.DLL, the DLL for APPC.

DosGetProcAddr to specify APPC as the desired entry point to the DLL.

Unlinking (the DosFreeModule call) is not supported.

Stack size

The recommended stack size for a TP is at least 3000 bytes.

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

Multiple processes

Multiple processes cannot have the same TP identifier (tp_id). Only the process that issues TP_STARTED or RECEIVE_ALLOCATE can use the tp_id returned by the verb. Another process wanting to use APPC must issue TP_STARTED or RECEIVE_ALLOCATE to obtain its own tp_id.

Two or more instances of the same TP can be run as different processes, but each will be assigned a different tp_id.

One process can contain many TPs, each with its own tp_id. In this case, you may want to create a separate thread for each TP to avoid the possibility of a deadlock. (A deadlock occurs when an APPC verb that is hung blocks the execution of verbs in other conversations and TPs.)

A process containing many TPs can issue two or more verbs simultaneously, provided each verb is for a different TP (specifies a different tp_id).

Multiple threads

A TP can have multiple threads that issue verbs. Windows APPC makes provisions for multithreaded processes. A process contains one or more threads of execution. All references to threads refer to actual threads in the multithreaded OS/2 environment.

Note

With the exception of RECEIVE_AND_POST and RECEIVE_AND_WAIT, only one conversation verb can be outstanding at a time on any conversation; however, other verbs can be issued for other conversations. This same guideline also applies to TP verbs and TPs. Although multiple TP verbs can be issued, only one TP verb can be outstanding at a time on a TP. This applies to both multithreaded applications and single-threaded applications that use asynchronous calls. For more information on using RECEIVE_AND_POST and RECEIVE_AND_WAIT, see Chapter 5, "APPC Conversation Verbs."

Critical sections

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

Limits

For more information about system limits, see your product documentation.

SNA Server CSVs are compatible with the common services programming interface provided by IBM ES for OS/2 version 1.0, with the following exceptions:

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

Trace information for products is stored in trace files, not in a storage buffer. With the SNA Server implementation of COPY_TRACE_TO_FILE, the trace information in these files is copied to a single trace file.

The additional tracing features of DEFINE_TRACE are not applicable because of differences between the SNA Server product architecture and the IBM Communications Manager architecture. The tracing features provided in IBM OS/2 ES version 1.0 include event tracing, automatic tracing, and tracing support for the following:

X.25 API verbs, frame data, and data link control (DLC) data.

Twin axial data.

With the SNA Server implementation of GET_CP_CONVERT_TABLE, user-defined code pages are applicable only in an OS/2 environment. These code pages are supported for only the Windows NT and OS/2 systems because of the additional memory occupancy in the MS-DOS and Windows environments. The new user-defined code pages are explained in the description of the verb.

With the SNA Server implementation of TRANSFER_MS_DATA, support for the PD_STATS subvector type is retained.

DEFINE_DUMP and SET_USER_LOG_QUEUE, provided in IBM OS/2 ES version 1.0, are not applicable because of differences between the SNA Server architecture and IBM Communications Manager architecture. If either verb is called, INVALID_VERB is returned.


Transaction Programs
Chapter 2	1 of 27

Transaction Programs

A processing task accomplished by programs using APPC is called a transaction. Consequently, programs that use APPC are called transaction programs, or TPs. These programs communicate as peers, on an equal (rather than hierarchical) basis. The TPs use APPC verbs to exchange status information and application data. Each TP uses APPC verbs to supply parameters to APPC, which performs the desired function and returns parameters to the TP.

TPs distributed across a local or wide area network perform distributed transaction processing.

This chapter describes how to write TPs and how to configure the systems on which TPs run. The sections in this chapter cover the following general areas:

Understanding fundamental concepts related to TPs

Designing and coding TPs

Configuring Registry and environment variables for invokable TPs

Configuring SNA Server to work with your TPs


Communication Between TPs
Transaction Programs	2 of 27

Communication Between TPs

Various hardware and software elements in the SNA environment are required in order for two TPs to communicate with each other. Figure 2.1 illustrates several fundamental elements:

Figure 2.1    Communication Between TPs

Each TP is associated with an LU of type 6.2. The LU allows the TP to access the network. Note that several TPs can be associated with the same LU.

A partner TP can invoke another TP, which, in turn, invokes another TP, and so on. In Figure 2.2, TP A invokes TP B, and TP B invokes TP C.

Figure 2.2    Partner TP Invoking Another TP


Fundamental Terms for TPs and LUs
Transaction Programs	3 of 27

Communication Between TPs

Fundamental Terms for TPs and LUs

The following terms help to describe some fundamental characteristics of TPs communicating through LUs:

LU-LU Session

The communication between two LUs over a specific connection for a specific amount of time. An LU-LU session is needed before two TPs can interact. One session can be used serially by many pairs of TPs.

An LU 6.2 can have multiple sessions (two or more concurrent sessions with different partner LUs) and parallel sessions (two or more concurrent sessions with the same partner LU).

LUs are configured through the SNA Server Administration program (SNA Server Admin), as are LU-LU pairs and modes; the LU and mode configurations control how many sessions a particular LU-LU pair supports.

LU alias

The string that identifies an LU to a TP. The alias can be as many as eight characters long.

Conversation

The interaction between TPs carrying out a specific task. Each conversation requires an LU-LU session. A TP can be involved in several conversations simultaneously, as shown with TP "B" in Figure 2.2, earlier in this chapter.

Local LU and local TP

An LU and TP working together, when viewed as the "home base" for a particular conversation. From this viewpoint, some other LU and TP are seen as the "partner" or "remote" LU and TP.

Partner LU and partner TP, or remote LU and remote TP

An LU and TP working together, when viewed as being at the far end of a particular conversation.

Mapped conversation

A type of conversation simpler than a Basic conversation, and generally used by application TPs (programs that accomplish tasks for end users). The characters MC_ at the beginning a verb stand for Mapped conversation. For more information, see "Basic and Mapped Conversations Compared," later in this chapter.

Basic conversation

A type of conversation more complex than a Mapped conversation, and generally used by service TPs (SNA-based programs that provide services to other programs). For more information, see "Basic and Mapped Conversations Compared," later in this chapter.

Synchronous verb

An APPC verb that blocks further program operations until the processing of the verb is complete.

Asynchronous verb

An APPC verb with which the initial API call returns immediately, so that the normal operation of the program is not blocked while processing of the verb completes. For more information, see "Receiving Data Asynchronously," later in this chapter.

Invoking TP

A TP that can invoke (that is, initiate a conversation with) other TPs. Invoking TPs are generally client-type applications, that is, they work in the same general way that an emulator works. For more information about invoking TPs, see "Invoking TPs," later in this chapter.

Invokable TP

A TP that can be invoked by another TP. Invokable TPs are generally server-type applications, that is, they work in the same general way that an application such as CICS [image] works. Parameters for an invokable TP are configured through Registry or environment variables.

There are several types of invokable TPs:

Operator-started invokable TP

A TP that is started manually in preparation for being invoked.

Autostarted invokable TP

A TP that is automatically started by APPC when invoked.

Queued TP

A TP that, when invoked multiple times, loads once and then queues up subsequent requests to be dealt with one at a time. All operator-started TPs and some autostarted TPs are queued.

Nonqueued TP

A TP loaded multiple times, once for every time it is invoked. Some autostarted TPs are nonqueued (but no operator-started TPs are nonqueued).

For more information about invokable TPs, see "Invokable TPs," later in this chapter.


Sample TPs Illustrating Fundamental Concepts
Transaction Programs	4 of 27

Communication Between TPs

Sample TPs Illustrating Fundamental Concepts

A set of sample TPs are provided on the SNA Server CD in the \SDK\SAMPLES directory. Included with the sample code is TPSETUP, a program that simplifies the setting of Registry or environment variables needed by autostarted invokable TPs. Without an interface like that provided by TPSETUP, configuring of such variables can be complicated and errorprone. Therefore, it is recommended that you use code like TPSETUP in installation programs for autostarted invokable TPs.

INSTALL.C (the source code for TPSETUP) can be compiled to work either in the Windows NT environment or in the Windows version 3.x environment.

For information about TPSETUP and about the sample TPs, see Appendix C, "Sample APPC TPs in the SDK."


Configuring and Controlling TPs
Transaction Programs	5 of 27

Communication Between TPs

Configuring and Controlling TPs

Table 2.1 shows how the characteristics of the TPs and selection of the LUs for a conversation are controlled:

Table 2.1    Controlling the Characteristics of TPs

Characteristic		How the characteristic is controlled
Type of verb: synchronous or asynchronous		Written into the code. Synchronous verbs use blocking calls; asynchronous verbs avoid blocking calls. For more information, see "Receiving Data Asynchronously," later in this chapter, and "WinAsyncAPPC" in Chapter 6.
Type of conversation: Basic or Mapped		Written into the code of the TPs. The MC_ prefix is used on verbs in Mapped conversations and omitted on verbs in Basic conversations. In order for two TPs to communicate successfully, they must both use the same type of conversation, Basic or Mapped. For more information, see "Basic and Mapped Conversations Compared," later in this chapter.
Type of TP: invoking or invokable		Written into the code. Invoking TPs start with TP_STARTED, which identifies the invoking TP, and [MC_]ALLOCATE, which identifies the requested invokable TP. Invokable TPs start with RECEIVE_ALLOCATE, which identifies the invokable TP. For more information, see "Invoking TPs" and "Invokable TPs," later in this chapter.
The local LU alias to be used by an invoking TP		Three options: Written into the code in TP_STARTED. Configured (in SNA Server Admin) as the Default Local APPC LU for the user who starts the invoking TP. Configured (in SNA Server Admin) as a member of the default outgoing local APPC LU pool. For information, see "Invoking TPs and the SNA Server Configuration," later in this chapter.
The invokable TP requested by an invoking TP		Written into the [MC_]ALLOCATE request in the invoking TP.
The LU alias to be used by an invokable TP		Two options: Written into the invoking TP (not the invokable TP), in [MC_]ALLOCATE. Configured as the Default Remote APPC LU for the user who starts the invoking TP. For information, see "Invoking TPs and the SNA Server Configuration" and "How an Invokable TP is Matched to an Invoking TP's Request," later in this chapter.
Type of autostarted invokable TP: queued or nonqueued		Configured with Registry or environment variables. For more information, see "Configuring Invokable TPs," later in this chapter.
Local LU and remote LU aliases		Configured in SNA Server Admin. For information, see the Microsoft SNA Server Administration Guide.
The pairing of local and remote LUs, and the mode used for each LULU pair		Configured in SNA Server Admin. For information, see the Microsoft SNA Server Administration Guide.


Steps for Creating TPs and the Configuration to Support Them
Transaction Programs	6 of 27

Communication Between TPs

Steps for Creating TPs and the Configuration to Support Them

The following list shows the general procedure for creating TPs and setting up a configuration to support them:

1.	Write, compile, and link each TP.

2.	Place each TP on an appropriate computer.

For TPs that you will start many times, or that will be started by a user, arrange for the TP to be started easily. That is, for graphical interfaces, create a program icon for starting the TP; for non-graphical interfaces, make sure the TP is in the path.

3.	On one or more SNA servers, configure LUs, modes, and LU-LU pairs for use by the TPs.

For information about how to set up LU-LU pairs to support TPs, see "Using Invoking and Invokable TPs," later in this chapter, as well as the Microsoft SNA Server Administration Guide.

4.	Set any Registry or environment variables needed for the invokable TP.

For autostarted invokable TPs, it is recommended that you use the sample TP configuration program, TPSETUP, for this step. When you write an installation program for autostarted invokable TPs, it is recommended that you add code similar to TPSETUP to the installation program.

For information about Registry or environment variables, see "Configuring Invokable TPs" later in this chapter. For information about TPSETUP, see Appendix C, "Sample APPC TPs in the SDK."

5.	If the invokable TP is operator-started, start it, or arrange for it to be started when the computer is restarted (and then restart the computer).

If the invokable TP is autostarted, SNA Server will start it when needed.

6.	Start the invoking TP.

The remainder of this chapter discusses the coding and configuration of TPs, and covers the following general topics:

Designing and coding TPs

Configuring Registry and environment variables for invokable TPs

Configuring SNA Server to work with your TPs


Designing and Coding TPs
Transaction Programs	7 of 27

Designing and Coding TPs

This section provides background information about designing and coding TPs. The following topics are discussed:

Conversation states

Confirmation processing

Receiving data asynchronously

Conversation security

Basic and Mapped conversations

Invoking and invokable TPs


Conversation states
Transaction Programs	8 of 27

Designing and Coding TPs

Conversation States

The state of the conversation (as viewed by a particular TP) governs which APPC verbs can be issued by the TP at a particular time. For example, a TP cannot issue MC_SEND_DATA if the conversation is not in SEND state for that TP.

The state of a conversation depends on the TP from which it is viewed. A local TP may view a conversation as being in SEND state while the partner TP views the conversation as being in RECEIVE state. A particular TP may be in several conversations, each of which is in a different state.

The possible conversation states are summarized in Table 2.2.

Table 2.2    Conversation States

State		Indicates
CONFIRM		The TP has received a request for confirmation of receipt of data; it must respond positively or send error information to the partner TP.
CONFIRM_DEALLOCATE		The TP has received a request for confirmation and must respond positively or send error information. If the TP responds positively, the conversation is automatically deallocated.
CONFIRM_SEND		The TP has received a request for confirmation; it must respond positively or send error information. After responding, the TP can begin to send data.
PENDING_POST		The TP is receiving data asynchronously. The TP can perform other processing not related to this conversation.
RECEIVE		The TP can receive application data and status information from the partner TP. When the conversation is in RECEIVE state, the TP can also send error information and request permission to send data.
RESET		The conversation has not started or has been terminated.
SEND		The TP can send data to the partner TP and request confirmation. When the conversation is in SEND state, the TP can also begin to receive data, which changes the state to RECEIVE.
SEND_PENDING		The TP issued a receive verb and the what_rcvd parameter returned by that verb indicated both data received and a status indication of SEND. This only affects the use of the err_dir parameter for [MC_]SEND_ERROR. Otherwise, the state is the same as the SEND state.
 State Checks

A state check occurs when a TP issues an APPC verb, and the conversation is not in the appropriate state. For instance, a state check would occur if a TP issued MC_SEND_DATA while the conversation was in RECEIVE state. When a state check occurs, APPC does not execute the verb; it returns state-check information through primary and secondary return codes.

Changing Conversation States

A change in the conversation state can result from:

A verb issued by the local TP.

A verb issued by the partner TP.

An error condition.

The example that follows shows how APPC verbs can change the state of the conversation from SEND to RECEIVE and from RECEIVE to SEND.

Note

Any TP can potentially send or receive data, regardless of whether the TP is the invoking TP (the TP that started the conversation) or the invokable TP (the TP that responded to a request to start a conversation).

This table shows how the conversation state can change. In this table, each conversation state appears in bold, and precedes the APPC verbs that are used while in that state.

Issued by the invoking TP	Issued by the invokable TP
TP_STARTED
Conversation state: RESET
MC_ALLOCATE
(sync_level=AP_CONFIRM_SYNC_LEVL)
Conversation state: SEND
MC_SEND_DATA
MC_PREPARE_TO_RECEIVE
(ptr_type=AP_SYNC_LEVEL)
	Conversation state: RESET
	RECEIVE_ALLOCATE
	Conversation state: RECEIVE
	MC_RECEIVE_AND_WAIT
	(primary_rc=AP_OK)
	(what_rcvd=AP_DATA_COMPLETE)
	MC_RECEIVE_AND_WAIT
	(primary_rc=AP_OK)
	(what_rcvd=AP_CONFIRM_SEND)
	Conversation state: CONFIRM_SEND
	MC_CONFIRMED
	Conversation state: SEND
	MC_SEND_DATA
	MC_CONFIRM
Conversation state: RECEIVE
MC_RECEIVE_AND_WAIT
(primary_rc=AP_OK)
(what_rcvd=AP_DATA_COMPLETE)
MC_RECEIVE_AND_WAIT
(primary_rc=AP_OK)
(what_rcvd=AP_CONFIRM_WHAT_RECEIVED)
Conversation state: CONFIRM
MC_REQUEST_TO_SEND
MC_CONFIRMED
	(rts_rcvd=AP_YES)
	MC_PREPARE_TO_RECEIVE
	(ptr_type=AP_SYNC_LEVEL)
Conversation state: RECEIVE
MC_RECEIVE_AND_WAIT
(primary_rc=AP_OK)
(what_rcvd=AP_CONFIRM_SEND)
Conversation state: CONFIRM_SEND
MC_CONFIRMED
Conversation state: SEND
MC_SEND_DATA
MC_DEALLOCATE
(dealloc_type=AP_SYNC_LEVEL)
	Conversation state: RECEIVE
	MC_RECEIVE_AND_WAIT
	(primary_rc=AP_OK)
	(what_rcvd=AP_DATA_COMPLETE)
	MC_RECEIVE_AND_WAIT
	(primary_rc=AP_OK)
	(what_rcvd=AP_CONFIRM_DEALLOCATE)
	Conversation state: CONFIRM_DEALLOCATE
	MC_CONFIRMED
Conversation state: RESET	Conversation state: RESET
TP_ENDED	TP_ENDED
Initial States

Before the conversation is allocated, the state is RESET for both TPs.

In the example, after the conversation is allocated, the initial state is SEND for the invoking TP and RECEIVE for the invokable TP.

Changing to RECEIVE State

MC_PREPARE_TO_RECEIVE allows a TP to change the conversation from SEND to RECEIVE state. This verb:

Flushes the local LU's send buffer.

Sends the AP_CONFIRM_SEND indicator to the partner TP through the what_rcvd parameter of a receive verb. This indicator tells the partner TP that an MC_CONFIRMED response is expected before the partner TP can begin to send data.

Confirmation processing is performed when the following conditions are true:

The ptr_type parameter is set to AP_SYNC_LEVEL.

The synchronization level of the conversation is set to AP_CONFIRM_SYNC_LEVEL.

For more information about confirmation processing, see the next section.

Important

Issuing MC_RECEIVE_AND_WAIT while the conversation is in SEND state flushes the LU's send buffer and changes the conversation state to RECEIVE. Changing the conversation state in this manner does not support confirmation processing.

Changing to SEND State

MC_REQUEST_TO_SEND informs the partner TP (for which the conversation is in SEND state) that the local TP (for which the conversation is in RECEIVE state) wants to send data. This request is communicated to the partner TP through the rts_rcvd parameter of MC_CONFIRM. (The rts_rcvd parameter is also returned to MC_SEND_DATA and other verbs.)

When the partner TP issues MC_PREPARE_TO_RECEIVE, the conversation state changes to RECEIVE for the partner TP, making it possible for the local TP to send data.

Important

Issuing MC_REQUEST_TO_SEND does not change the state of the conversation. Upon receiving a request to send, the partner TP is not required to change the conversation state; it can ignore the request.


Confirmation Processing
Transaction Programs	9 of 27

Designing and Coding TPs

Confirmation Processing

The sequence of events for confirmation processing is as follows:

1.	Establish the synchronization level.

2.	Send a confirmation request.

3.	Receive data and confirmation request.

4.	Respond to the confirmation request.

5.	Deallocate the conversation.

Using confirmation processing, a TP sends a confirmation request with the data; the partner TP confirms receipt of the data or indicates that an error occurred. Each time the two TPs exchange a confirmation request and response, they are synchronized.

Note

Although the example in this section does not show this, any TP can potentially send or receive data, regardless of whether the TP is the invoking TP or the invokable TP.

The following example illustrates confirmation processing.

Issued by the invoking TP	Issued by the invokable TP
TP_STARTED
MC_ALLOCATE
(sync_level=AP_CONFIRM_SYNC_LEVEL)
MC_SEND_DATA
(type=AP_SEND_DATA_CONFIRM)
	RECEIVE_ALLOCATE
	MC_RECEIVE_AND_WAIT
	(primary_rc=AP_OK)
	(rtn_status=AP_YES)
	(what_rcvd=AP_DATA_COMPLETE_CONFIRM)
	MC_CONFIRMED
MC_SEND_DATA
(type=AP_SEND_DATA_DEALLOC_SYNC_LEVEL)
	MC_RECEIVE_AND_WAIT
	(primary_rc=AP_OK)
	(rtn_status=AP_YES)
	(what_rcvd=AP_DATA_COMPLETE_CONFIRM_ DEALLOCATE)
	MC_CONFIRMED
TP_ENDED	TP_ENDED
The following sections describe the steps used for confirmation processing.

Establishing the Synchronization Level

The sync_level parameter of MC_ALLOCATE determines the synchronization level of the conversation. There are two possible synchronization levels:

AP_CONFIRM_SYNC_LEVEL, under which the TPs can request confirmation of receipt of data and respond to requests for confirmation of data

AP_NONE, under which confirmation processing does not occur

Sending a Confirmation Request

MC_SEND_DATA with type AP_SEND_DATA_CONFIRM has two effects:

It flushes the local LU's send buffer (which sends any data contained in the buffer to the partner TP).

It sends a confirmation request, which the partner TP receives through the what_rcvd parameter of a receive verb.

After issuing MC_SEND_DATA, the local TP waits for confirmation from the partner TP.

Receiving Data and Confirmation Request

The what_rcvd parameter of MC_RECEIVE_AND_WAIT indicates:

Status of the data receivedcomplete or incomplete.

Future processing expected of the local TP.

In the example in "Confirmation Processing" earlier in this chapter, what_rcvd is AP_DATA_COMPLETE_CONFIRM, indicating that the status is complete and a confirmation is requested.

Responding to a Confirmation Request

The partner TP issues MC_CONFIRMED to confirm receipt of data. This frees the local TP to resume processing.

Deallocating the Conversation

MC_SEND_DATA sends a confirmation request with the data when all of the following conditions are true:

The conversation's synchronization level (established by the sync_level parameter of MC_ALLOCATE) is AP_CONFIRM_SYNC_LEVEL.

The type parameter of MC_SEND_DATA is set to AP_SEND_DATA_DEALLOC_SYNC_LEVEL.

The what_rcvd parameter of the final MC_RECEIVE_AND_WAIT is AP_DATA_COMPLETE_CONFIRM_DEALLOCATE, indicating that a confirmation of receipt of data is required before APPC will deallocate the conversation. The local TP waits for this confirmation until the partner TP issues MC_CONFIRMED.


Receiving Data Asynchronously
Transaction Programs	10 of 27

Designing and Coding TPs

Receiving Data Asynchronously

With the Windows NT, Windows version 3.x, and OS/2 operating systems, a TP can receive data asynchronously  without regard to other events occurring within the TP. Table 2.3 shows the methods by which a TP can receive data asynchronously. The table also indicates how asynchronous methods can be applied to actions other than the receiving of data.

Table 2.3    Methods for Receiving Data Asynchronously

Operating system		Method
Windows NT or Windows version 3.x		Through a Windows message: Issue RECEIVE_AND_WAIT with WinAsyncAPPC; the application is notified of completion through a PostMessage to the defined Windows handle. This method is not restricted to RECEIVE_AND_WAIT, but can be applied to any APPC verb.
Windows NT		Through a Win32 event: Issue RECEIVE_AND_WAIT with WinAsyncAPPCEx; the application is notified of completion through a Win32 event. This method is not restricted to RECEIVE_AND_WAIT, but can be applied to any APPC verb.
Windows NT or OS/2		With RECEIVE_AND_POST:  Issue the RECEIVE_AND_POST verb. With OS/2, the application is notified of completion through a semaphore. With Windows NT, the application is notified of completion through a Win32 event (the unsignaled event, not a semaphore, is passed in the sema field).
The following list gives details about these methods of receiving data asynchronously. For complete information, see the description of the verb(s) to be used.

RECEIVE_AND_WAIT with WinAsyncAPPC

This method is defined as part of Windows SNA. It allows an application to issue a verb and be notified through a PostMessage when the action is complete. To retrieve the message number that will be posted to the window, call RegisterWindowMessage with "WinAsyncAPPC" as the input string. Then issue RECEIVE_AND_WAIT using the WinAsyncAPPC entry point.

RECEIVE_AND_WAIT with WinAsyncAPPCEx

This method allows an application to be notified through a Win32 event. This is particularly useful when writing applications that need to service multiple conversations simultaneously. The event must be in the nonsignaled state when passed to APPC, and the handle must have EVENT_MODIFY_STATE access to the event.

RECEIVE_AND_POST

When using RECEIVE_AND_POST with Windows NT, the application is notified through a Win32 event. The event must be in the nonsignaled state when passed to APPC, and the handle must have EVENT_MODIFY_STATE access to the event.

When using RECEIVE_AND_POST with OS/2, the application is notified through a semaphore. Use DosSemSet to set the semaphore; APPC will clear the semaphore when the TP finishes receiving data asynchronously.

While receiving data asynchronously, the TP performs tasks not related to this conversation; the TP cannot issue most APPC verbs until notification is received. For information about the verbs that can be issued, see the descriptions of WinAsyncAPPC or WinAsyncAPPCEx.

For more information about the verbs described in this section, including information about state changes, see the descriptions of the individual verbs.

After a verb has completed asynchronously, reverify the primary_rc to find out whether the data was received without error.

Note

If the initial call to issue the verb returns successfully, the application is guaranteed to be notified (by the applicable method) when the verb completes, regardless of whether the verb is ultimately successful.


Conversation Security
Transaction Programs	11 of 27

Designing and Coding TPs

Conversation Security

You can use conversation security to require that the invoking TP provide a user ID and password before APPC will allocate a conversation with the invokable TP. If so, the invoking TP must supply a combination of the user ID and password as parameters of [MC_]ALLOCATE.

Conversation security is activated and configured through Registry or environment variables on the computer where the invokable TP is located.

With communication involving more than two TPs, the verification of a user ID and password can be passed from one TP to another. Suppose that TP A invokes TP B, which requires security information, and TP B in turn invokes TP C, which also requires security information. Through [MC_]ALLOCATE, TP B can inform TP C that conversation security has already been verified.

For information about the Registry or environment variables affecting conversation security, see "Configuring Invokable TPs," later in this  chapter.


Basic and Mapped Conversations Compared
Transaction Programs	12 of 27

Designing and Coding TPs

Basic and Mapped Conversations Compared

The following table offers some guidelines for choosing between Basic and Mapped conversations for your TPs. For definitions of Basic and Mapped conversations, see "Fundamental Terms for TPs and LUs," earlier in this chapter.

Characteristic		Basic conversations		Mapped conversations
Common use		Generally used for service TPs.		Generally used for application TPs.
Partnering		Must be used to communicate with an existing TP that uses Basic verbs.		Must be used to communicate with an existing TP that uses Mapped verbs.
Sending and receiving method		Before a TP can begin a send operation, it must convert data records into logical records. The TP does this by adding a 2byte prefix that indicates the length of the record. A TP can send several logical records at one time. When a partner TP receives logical records, it must reconstruct them into usable data records. For more information, see "Logical Records Used in Basic Conversations," later in this chapter.		A TP sends data one record at a time. Neither the sending TP nor the receiving TP needs to convert data records to or from different forms
Abnormal termination		In the DEALLOCATE verb, a TP can indicate whether an error or ABEND (abnormal program termination) was caused by a TP or by a program using the TP.		A TP can indicate an error or ABEND, but cannot tell whether a problem was caused by a TP or by a program using a TP.
		A TP can indicate whether an ABEND was caused by a time-out or by a critical error.		A TP cannot indicate the cause of an ABEND.
Logging of errors		For an error or ABEND, a TP can send an error message, in the form of a general data stream (GDS) error log variable, to the local log and to the partner LU.		For an error or ABEND, a TP cannot send an error message to the local log or to the partner LU.
Logical Records Used in Basic Conversations

Logical records are sent and received in Basic conversations only.

A TP can send or receive multiple logical records with a single SEND_DATA or receive verb. The receive verbs are RECEIVE_AND_POST (Windows NT and OS/2), RECEIVE_IMMEDIATE, and RECEIVE_AND_WAIT. A TP can also send or receive a logical record in successive portionsbeginning, middle, and end.

A logical record is made up of:

A 2-byte record-length (LL) field.

A data field that can range in length from 0 bytes through 32,765 bytes.

The LL field contains a hexadecimal value; this value is the length of the data field plus two bytes (for the LL field). For example, if a record contains 228 bytes of application data, the logical record length would be 230. The LL field would be X'00E6', the hexadecimal equivalent of 230. If the length of the data field is 0, the value contained in the LL field is X'0002'.

Logical records are sent from or received in a data buffer established by the TP. In the data buffer, the LL field must not be in Intel byte-swapped format. For example, a length of 230 must be X'00E6' (not X'E600').

The LL field cannot be X'0000' or X'0001', which allow less than the 2 bytes required for the LL field itself. The LL field also cannot be greater than or equal to X'8000', which is equivalent to decimal 32,768, and therefore allows for a data field greater than 32,765 and/or an LL field greater than 2.

Setting the most significant bit of the LL field to 1 indicates that the information contained in this logical record is continued in the next logical record.

An Example of a Mapped Conversation

For background information about Mapped conversations, see "Basic and Mapped Conversations Compared," earlier in this chapter.

The following example of a Mapped conversation shows the APPC verbs used to start a conversation, exchange data, and end the conversation. The characters MC_ at the beginning of many of the verbs stand for Mapped conversation. APPC verb parameters are in parentheses.

Issued by the invoking TP	Issued by the invokable TP
TP_STARTED
MC_ALLOCATE
MC_SEND_DATA
MC_DEALLOCATE
TP_ENDED	RECEIVE_ALLOCATE
	MC_RECEIVE_AND_WAIT
	(primary_rc=AP_OK)
	(rtn_status=AP_NO)
	(what_rcvd=AP_DATA_COMPLETE)
	MC_RECEIVE_AND_WAIT
	(primary_rc=AP_DEALLOC_NORM)
	TP_ENDED
The following sections describe the verbs that are used in a Mapped conversation.

Verbs for Starting a Mapped Conversation

To start a conversation, the invoking TP issues:

TP_STARTED, which notifies APPC that the local TP is beginning a conversation.

MC_ALLOCATE, which requests that APPC establish a conversation between the local TP and the partner TP.

The invokable TP issues RECEIVE_ALLOCATE, which informs APPC that it is ready to begin a conversation with the invoking TP.

Verbs for Sending Data in a Mapped Conversation

MC_SEND_DATA puts one data record (a record containing application data to be transmitted) in the send buffer of the local LU. The transmission of the data to the partner TP does not happen until one of the following events occurs:

The send buffer fills up.

The sending TP issues a verb that forces APPC to flush the buffer (send data to the partner TP).

In "An Example of a Mapped Conversation," earlier in this chapter, the send buffer contains both the data record and the MC_ALLOCATE request (which precedes the data record). Therefore, in the example, MC_DEALLOCATE flushes the buffer, sending the MC_ALLOCATE request and data record to the partner TP. (Among other verbs that flush the buffer are MC_CONFIRM and MC_FLUSH.)

Verbs for Receiving Data in a Mapped Conversation

In "An Example of a Mapped Conversation," earlier in this chapter, MC_RECEIVE_AND_WAIT allows a TP to receive a data record or status information. If no data is currently available, the TP waits for data to arrive. For Windows NT and Windows version 3.x systems, issue MC_RECEIVE_AND_WAIT in conjunction with WinAsyncAPPC rather than the blocking version of this call.

Also in the example, the receiving TP issues MC_RECEIVE_AND_WAIT twice. The first time, it issues the verb to receive data. When it finishes receiving the complete data record (what_rcvd is AP_DATA_COMPLETE), it issues MC_RECEIVE_AND_WAIT again to receive a return code. The return code AP_DEALLOC_NORMAL indicates that the conversation has been deallocated.

Note

MC_RECEIVE_IMMEDIATE performs the same function as MC_RECEIVE_AND_WAIT, except that it does not wait if data is not currently available from the partner TP. Instead, it returns a no-data-available response to the calling TP.

Verbs for Ending a Mapped Conversation

To end a conversation, one of the TPs issues MC_DEALLOCATE, which causes APPC to deallocate the conversation between the two TPs.

After the conversation has been deallocated, both TPs issue TP_ENDED.

Note

A TP can participate in multiple conversations simultaneously. In this case, the TP issues TP_ENDED after all conversations have been deallocated.


Using Invoking and Invokable TPs
Transaction Programs	13 of 27

Designing and Coding TPs

Using Invoking and Invokable TPs

There are two kinds of TPs: TPs that can invoke (that is, initiate a conversation with) other TPs, and TPs that can be invoked. A TP that can invoke another TP is called an invoking TP, and a TP that can be invoked is called an invokable TP.

The following sections describe how:

Invoking TPs request invokable TPs.

Invokable TPs identify themselves to SNA Server in preparation for being invoked.

An invokable TP is matched to an invoking TP's request.

For information about how to configure LUs to support TPs, see "Configuring an SNA Server to Support TPs," later in this chapter, and the Microsoft SNA Server Administration Guide.


Invoking TPs
Transaction Programs	14 of 27

Designing and Coding TPs

Invoking TPs

An invoking TP can be located on any system on the SNA network. An invoking TP identifies itself by issuing TP_STARTED. TP_STARTED specifies the name of the invoking TP, and may specify the LU alias that the TP uses. If the LU alias is not specified in TP_STARTED, SNA Server must be configured to supply one, through one of two types of "default" local LU; otherwise, TP_STARTED will fail. For more information, see "Invoking TPs and the SNA Server Configuration," later in this chapter.

Next, the invoking TP initiates the invoking process by issuing [MC_]ALLOCATE. In [MC_]ALLOCATE, the invoking TP specifies the name of the invokable TP, and may also specify the partner LU alias (the LU alias to be used by the invokable TP). If the partner LU is not specified in [MC_]ALLOCATE, SNA Server must be configured to supply one, through the Default Remote APPC LU assigned to the user who started the invoking TP; otherwise, [MC_]ALLOCATE will fail. For more information, see "Invoking TPs and the SNA Server Configuration," later in this chapter.

After a TP successfully issues an [MC_]ALLOCATE verb, an allocation request flows. For more information about what happens after an invoking TP requests an invokable TP, see "How an Invokable TP is Matched to an Invoking TP's Request," later in this chapter.

Invoking TPs and Contention

The following information applies only to cases where LUs are communicating in complex ways (such as chains of LUs) over multiple sessions. In such cases, two LUs may attempt to allocate a conversation on the same session at the same time. If this happens, one LU must win (the contention winner) and one must lose (the contention loser). The contention-winner LU and the contention-loser LU are determined for each session when the session is established. During that particular session, the contention-loser LU must receive permission from the contention-winner LU before allocating a conversation. In contrast, the contention-winner LU on that session allocates a conversation as needed.

Note that when two LUs are communicating over multiple sessions, one LU may be the contention winner for some of the sessions, and the other LU the contention winner for others.

An invoking TP will operate best if the number of concurrent [MC_]ALLOCATE requests that the TP will issue is matched by the number of sessions on which the local LU is the contention winner. The choice of contention winner is controlled through the modes configured at the two ends of the communication. For SNA Server, the mode is configured in SNA Server Admin. A mode must be configured to work with the mode on the remote system in order for communication to begin between two LUs. For more information about modes, see the Microsoft SNA Server Administration Guide.


Invokable TPs
Transaction Programs	15 of 27

Designing and Coding TPs

Invokable TPs

An invokable TP is a TP that can be invoked by another TP. Invokable TPs are written or configured (through Registry or environment variables) to supply their names to SNA Server, as a notification that they are available for incoming requests. SNA Server invokable TPs can be run on any SNA Server or client running Windows NT, Windows version 3.x, or OS/2.

There are two types of invokable TPs:

Operator-started invokable TPs

An operator-started invokable TP must be started by an operator before the TP can be invoked. When the operator-started invokable TP is started, it notifies SNA Server of its availability by issuing a RECEIVE_ALLOCATE verb. The RECEIVE_ALLOCATE causes the name of the invokable TP to be communicated to all the SNA servers in the domain, along with the alias of an associated LU, if one has been configured through a Registry or environment variable.

Autostarted invokable TPs

An autostarted invokable TP can be started by SNA Server when needed. The TP must be registered (through Registry entries or environment variables) on its local system, so that it can be identified to the SnaBase component of the SNA Server client software. The registered information defines the TP as autostarted, and must specify the TP name. The registered information may also specify the local LU alias that the invokable TP will use.

The recommended method for setting Registry or environment variables for autostarted invokable TPs is to use the sample TP configuration program, TPSETUP, or similar code written into your own installation program. For more information about Registry or environment variables for invokable TPs, see "Configuring Invokable TPs," later in this chapter. For information about TPSETUP, see Appendix C, "Sample APPC TPs in the SDK."

If no local LU alias is registered with autostarted TPs, the resulting SNA Server configuration can be more flexible in responding to invoking requests. For more information about such flexible configurations, see "TP Name Not Unique; Local LU Alias Unspecified" later in this chapter.

After an autostarted invokable TP is started by SNA Server, the TP issues RECEIVE_ALLOCATE (just as an operator-started TP does). RECEIVE_ALLOCATE must provide the same TP name as was registered for the TP.

Autostarted TPs must be configured (through Registry or environment variables) to be either queued or nonqueued. All operator-started TPs act as queued TPs.

Queued TPs (including all operator-started TPs)

If an autostarted TP is configured as queued, or if the TP is operator-started, incoming allocation requests are queued, and then sent only when the invokable TP issues RECEIVE_ALLOCATE. For autostarted invokable TPs, if a copy of the TP is not yet running, one is started when an incoming allocation request specifies that TP.

Note

For the Windows NT system, only one copy of a service can be running at any given time; this means that all autostarted TPs that run as services under Windows NT must be queued. To write an autostarted TP so it will run under Windows NT as a service and also run in a "nonqueued" way, write a multithreaded program with a RECEIVE_ALLOCATE always outstanding.

Nonqueued TPs

If an autostarted TP is configured as nonqueued, every time an [MC_]ALLOCATE is received for the TP, a new copy will be started. Nonqueued TPs should process the conversation they have been allocated and then exit, since they will not receive any additional [MC_]ALLOCATE requests.

Subcategories for Invokable TPs

Figure 2.3 shows subcategories for invokable TPs.

Figure 2.3    Subcategories for Invokable TPs

1.	The concept of a TP "running as a service" or "running as an application" is distinct from a "service TP" or an "application TP." "Service TP" and "application TP" are SNA terms that describe how a TP is used  either as a supportive "service" program for other APPC programs, or directly by a user, as an application. For detailed information about Windows NT-based services and applications, see the documentation for Windows NT and for Win32.

2.	To write an autostarted TP so it will run under Windows NT as a service and also run in a "nonqueued" way, write a multithreaded program with a RECEIVE_ALLOCATE always outstanding. For more information, see the previous section.

3.	To run an autostarted TP as an application under Windows NT, make sure the TPSTART program is always started before the TP. For more information, see Appendix C "Sample APPC TPs in the SDK.".


How an Invokable TP is Matched to an Invoking TPs Request
Transaction Programs	16 of 27

Designing and Coding TPs

How an Invokable TP is Matched to an Invoking TP's Request

Each SNA server maintains a list of available invokable TP names, and any LU aliases to be associated with the TP names. This information is obtained as follows:

For autostarted invokable TPs, Registry or environment variables identify a TP name containing a maximum of 8 characters, and may specify an associated LU. This information is sent from the client to the server that sponsors the client. (A client learns about the domain through a sponsor connection to a server; clients must establish the sponsor connection before proceeding with any other tasks.)

For operator-started invokable TPs, a TP name (consisting of a maximum of 64 characters) is specified with the RECEIVE_ALLOCATE verb, and is sent from the client to the server that sponsors the client, along with the alias of an associated LU, if one has been configured through a Registry or environment variable.

Note

If you want a TP name to be unique, it is recommended that you limit the name to eight characters or less, or else make the name unique within the first eight characters. This is because the preliminary routing of allocation requests is carried out using the first eight characters. Although further matching is later carried out between the full TP names specified in [MC_]ALLOCATE and RECEIVE_ALLOCATE, it is inefficient to allow the preliminary routing to succeed when in some cases the later matching will fail.

The next step in the matching of invoking and invokable TPs is the issuing of the [MC_]ALLOCATE verb by the invoking TP. After an invoking TP in an SNA Server domain successfully issues this verb, an allocation request flows to the partner LU specified  in the [MC_]ALLOCATE verb, stating the name of the invokable TP that has been requested.

When an allocation request arrives, the SNA server compares the requested invokable TP name, as well as the LU alias, to the list of available invokable TPs (which may include associated LU aliases). The comparison can be modified by Registry variables, named in a later paragraph, but by default is carried out as follows:

Although the TP name requested in the [MC_]ALLOCATE verb can be as long as 64 characters, any name received through a Registry or environment variable is 8 characters or less. Therefore, only the first 8 characters of TP names are used in comparisons.

The comparison is carried out first on both the TP name and the LU alias. An invokable TP for which there is a match on both TP name and LU alias will be chosen ahead of a TP for which no LU alias has been configured (through a Registry or environment variable). A TP for which no LU alias has been configured can be matched with any request that specifies that TP name, since there cannot be a mismatch based on LU alias.

The comparison of requested and available TP names is carried out in a specific order:

1.	The SNA server first checks for operator-started invokable TPs on the local system (the SNA server itself).

2.	If no match is found, the SNA server checks for autostarted invokable TPs on the local system (the SNA server itself).

3.	If no match is found, the SNA server checks for operator-started invokable TPs on other SNA servers or clients.

4.	If no match is found, the SNA server checks for autostarted invokable TPs on other SNA servers or clients.

This comparison can be modified somewhat by Registry entries for the SnaServr service. The entries are called DloadMatchTPOnly and DloadMatchLocalFirst, and are described in the Microsoft SNA Server Reference.

If a match is found, the SNA server signals the system containing the requested TP to connect to that SNA server. If no match is found, the SNA server rejects the incoming request.

For suggestions about specific ways to handle TP names and LU aliases, see "Possible Arrangements of TPs Within an SNA Network," later in this chapter.

Note

Because of the way APPC works, an allocation request will not flow until local data buffers are full, or a confirm or flush verb is issued. This may mean that the allocation request does not flow until some time after the [MC_]ALLOCATE verb is issued. Therefore, any allocation failure caused by the rejection of the allocation request at the partner LU will be observed as the failure of a later verb with one of the allocation failure return codes.


Configuring Invokable TPs
Transaction Programs	17 of 27

Configuring Invokable TPs

The following sections tell how to configure invokable TPs for the various SNA Server client types.


Clients Running Windows NT
Transaction Programs	18 of 27

Configuring Invokable TPs

Clients Running Windows NT

On clients running Windows NT, invokable TPs are configured through the Registry.

Note

With Windows NT, the recommended method for setting Registry variables for autostarted invokable TPs is to use the sample TP configuration program, TPSETUP (compile INSTALL.C, the source code for TPSETUP, for the Windows NT environment). When you write an installation program for autostarted invokable TPs, it is recommended that you add code similar to TPSETUP to the installation program. For information about TPSETUP, see Appendix C, "Sample APPC TPs in the SDK."

For clients running Windows NT, it is recommended that autostarted invokable TPs be written as Windows NT services. As part of a setup program written to install your TPs, be sure to include code like that in TPSETUP. Among other things, TPSETUP shows how to use the CreateService function when installing a TP. For important information about how services work under Windows NT, see the documentation for Windows NT and for Win32.

Table 2.4 lists the Registry entries used for the types of invokable TPs that can be run on Windows NT-based clients:

Table 2.4    Registry Entries for Invokable TPs on Windows NT-Based Clients

Type of TP	Location in Registry	Possible registry entries (some are otional)
Autostarted invokable TP running as a service on a Windows-NT based client	HKEY_LOCAL_MACHINE   SYSTEM     CurrentControlSet       Services         TPName         (and subkeys)	Registry entries created by the CreateService call, including entries that specify the path, display name, and other characteristics of the service. PLUS Linkage OtherDependencies: REG_MULTI_SZ:SnaBase Parameters SNAServiceType:REG_DWORD:0x5 LocalLU:REG_SZ:LUalias Parameters:REG_SZ:ParameterList Timeout:REG_DWORD:number AcceptNames:REG_SZ:TPNameList ConversationSecurity:REG_SZ:{ YES | NO } AlreadyVerified:REG_SZ:{ YES | NO } **Username1:REG_SZ:Password1** ... UsernameX:REG_SZ:PasswordX**
Autostarted invokable TP running as an application* on a Windows-NT based client	HKEY_LOCAL_MACHINE   SYSTEM     CurrentControlSet       Services         SnaBase           Parameters             TPs               TPName                 Parameters	SNAServiceType:REG_DWORD:{ 0x5 | 0x6 } PathName:REG_EXPAND_SZ:path LocalLU:REG_SZ:LUalias Parameters:REG_SZ:ParameterList TimeOut:REG_DWORD:number AcceptNames:REG_SZ:TPNameList ConversationSecurity:REG_SZ:{ YES | NO } AlreadyVerified:REG_SZ:{ YES | NO } **Username1:REG_SZ:Password1** ... UsernameX:REG_SZ:PasswordX**
Operator-started invokable TP running as a service on a Windows-NT based client	HKEY_LOCAL_MACHINE  SYSTEM     CurrentControlSet       Services         TPName           (and subkeys)	Registry entries created by the CreateService call, including entries that specify the path, display name, and other characteristics of the service. PLUS Linkage OtherDependencies: REG_MULTI_SZ:SnaBase Parameters SNAServiceType:REG_DWORD:0x1A LocalLU:REG_SZ:LUalias Timeout:REG_DWORD:number ConversationSecurity:REG_SZ:{ YES | NO } AlreadyVerified:REG_SZ:{ YES | NO } **Username1:REG_SZ:Password1** ... UsernameX:REG_SZ:PasswordX**
Operator-started invokable TP running as an application on a Windows-NT based client	HKEY_LOCAL_MACHINE  SYSTEM     CurrentControlSet       Services         SnaBase           Parameters             TPs               TPName                 Parameters	SNAServiceType:REG_DWORD:0x1A LocalLU:REG_SZ:LUalias TimeOut:REG_DWORD:number ConversationSecurity:REG_SZ:{ YES | NO } AlreadyVerified:REG_SZ:{ YES | NO } **Username1:REG_SZ:Password1** ... UsernameX:REG_SZ:PasswordX**
* Before an autostarted TP can be started as an application on a Windows NT-based client , the TPSTART program must be started. For more information, see Appendix B, "Sample CPI-C TPs in the SDK." ** AlreadyVerified and username/password entries are used only if ConversationSecurity is set to YES.
For important information about TPSETUP, see the note in the previous section.

Registry Entries for Clients Running Windows NT

The following list gives details about the Registry entries shown in Table 2.4.

Note

The following list shows possible Registry entries; use only the entries that apply to your TP, as shown in Table 2.4.

OtherDependencies:REG_MULTI_SZ:SnaBase

For a TP running as a service, ensures that the SnaBase service will be started before the TP is started. This entry belongs under the Linkage subkey.

SNAServiceType:REG_DWORD:{ 0x5 | 0x6 | 0x1A }

Indicates the type of TP. Use a value of 0x5 for an autostarted queued TP, 0x6 for an autostarted nonqueued TP, and 0x1A for an operator-started TP.

See Table 2.4 for the correct location for this entry.

Note that the value for an autostarted TP running as a service must be 0x5, because these TPs are always queued, as described in "Invokable TPs," earlier in this chapter.

PathName:REG_EXPAND_SZ:path

For an autostarted TP running as an application, specifies the path and filename of the TP. The data type of REG_EXPAND_SZ means that the path can contain an expandable data string; for example, %SystemRoot% represents the directory containing the Windows NT system files. (Note that for a TP running as a service, an equivalent entry is inserted by the CreateService call; no additional path entry is needed.)

LocalLU:REG_SZ:LUalias

Specifies the alias of the local LU to be used when this TP is started on this computer. See Table 2.4 for the correct location for this entry.

Parameters:REG_SZ:ParameterList

Lists parameters to be used by the TP. Separate parameters with spaces. See Table 2.4 for the correct location for this entry.

Note

When using SNA Server version 2.0 with Win32, be sure to get patch 26. This patch causes the parameter arguments in the Parameters Registry entry to be passed to the invokable TP in the order expected when parsing the command line (that is, as an array of ASCII strings). Patch 26 is available on the MSSNA CompuServe [image] forum Library #2 as SNA20.P26.

Timeout:REG_DWORD:number

Specifies the time, in milliseconds, that a RECEIVE_ALLOCATE will wait before timing out. Specify number in decimal; the Registry editor converts this to hexadecimal before displaying. See Table 2.4 for the correct location for this entry. The default is infinity (no limit).

ConversationSecurity:REG_SZ:{ YES | NO }

Indicates whether this TP supports conversation security. See Table 2.4 for the correct location for this entry. The default is NO.

AlreadyVerified:REG_SZ:{ YES | NO }

Indicates whether this TP can be invoked with a user ID and password that have already been verified. AlreadyVerified is ignored if ConversationSecurity is set to NO.

For a diagram of three TPs in a conversation, where the third TP could have been invoked with a password that is already verified by the second TP, see Figure 2.2, earlier in this chapter. The following table shows the requirements for using password verification in a chain of TPs:

First TP (an invoking TP)		Second TP (invokable TP that confirms password and then invokes another TP)		Third and subsequent TPs (invokable TPs that invoke other TPs)
Does not need Registry or environment variables		ConversationSecurity setting must be YES		ConversationSecurity setting must be YES
Does not need Registry or environment variables		AlreadyVerified setting can be YES or NO		AlreadyVerified setting must be YES
[MC_]ALLOCATE in this TP has a security parameter of AP_PGM; as a result, the TP passes along the user_id and pwd values supplied in [MC_]ALLOCATE		[MC_]ALLOCATE in this TP has a security parameter of AP_SAME; as a result, after confirming the user ID and password, the TP passes along the user ID and an already-verified flag		[MC_]ALLOCATE in this TP has a security parameter of AP_SAME; as a result, the TP passes along the user ID as received, along with the already-verified flag
If you set AlreadyVerified to NO, this TP cannot join in a chain of conversations where password verification is already done. (The exception to this is when ConversationSecurity is set to NO, in which case the TP could be the final TP in such a chain, since it will perform no checking.)

If you are configuring a TP that may sometimes need to confirm a password and sometimes accept an already-verified flag, set AlreadyVerified to YES and configure the UsernameX variable appropriately. In this case, whenever the TP is invoked without the already-verified flag being set, AlreadyVerified is ignored; verification is attempted with the user ID and password configured for the TP.

If you want to have a chain of conversations where the user ID and password are reverified at every step, carry out the following. For all the TPs, set ConversationSecurity to YES, and in each [MC_]ALLOCATE issued, set the security parameter to AP_PGM and the pwd and user_id parameters to valid combinations.

If you set AlreadyVerified to YES, make sure that ConversationSecurity is also set to YES.

See Table 2.4 for the correct location for AlreadyVerified. The default is NO.

Username1:REG_SZ:Password1
...
UsernameX:REG_SZ:PasswordX

Sets one or more usernames and passwords to be compared with those sent by the invoking TP. The username and password can each be as many as 10 characters. Both parameters are case sensitive.

See Table 2.4 for the correct location for this entry. This variable is ignored if conversation security is not activated or if the password has already been verified, as described for the AlreadyVerified entry.

Example of Registry Entries for an Invokable TP

For an autostarted invokable TP called BounceTP and running as a service, the following Registry entries might be added to a Windows NT-based client. The entries would be added to HKEY_LOCAL_MACHINE\SYSTEM\    CurrentControlSet\Services, under the subkeys shown in bold.

Note

In the following list, the parameters listed directly under the BounceTP key (such as DisplayName and ErrorControl) are service parameters created when TPSETUP (or similar code) is run to install the TP. TPSETUP or similar code should be used to create these variables (they should not be set manually). For more information about TPSETUP, see Appendix C, "Sample APPC TPs in the SDK."

BounceTP

DisplayName:REG_SZ:BounceTP
ErrorControl:REG_DWORD:0x1
ImagePath:REG_EXPAND_SZ:c:\sna\system\bouncetp.exe
ObjectName:REG_SZ:LocalSystem
Start:REG_DWORD:0x3
Type:REG_DWORD:0x10

Linkage

OtherDependencies:REG_MULTI_SZ:SnaBase

Parameters

SNAServiceType:REG_DWORD:0x5
LocalLU:REG_SZ:JohnDoe
Parameters:REG_SZ:Arg1 Arg2 Arg3
Timeout:REG_DWORD:0x100
ConversationSecurity:REG_SZ:yes
AlreadyVerified:REG_SZ:no
JohnDoe:REG_SZ:SecretPassword


Clients Running Windows Version 3.x
Transaction Programs	19 of 27

Configuring Invokable TPs

Clients Running Windows Version 3.x

On clients running Windows version 3.x, invokable TPs are configured through entries in the WIN.INI file.

Note

With Windows version 3.x, the recommended method for setting environment variables for autostarted invokable TPs is to use the sample TP configuration program, TPSETUP (compile INSTALL.C, the source code for TPSETUP, for the Windows version 3.x environment). When you write an installation program for autostarted invokable TPs, it is recommended that you add code similar to TPSETUP to the installation program. For information about TPSETUP, see Appendix C, "Sample APPC TPs in the SDK."

Table 2.5 lists the section headings and environment variables used (in the WIN.IN file) for invokable TPs on clients running Windows version 3.x:

Table 2.5    Environment Variables for Invokable TPs on Windows-Based Clients

Type of TP		Section in WIN.INI listing TP names only		Section and possible  environment variables defining  TP (some variables are optional)
Autostarted invokable TP on a client running Windows version 3.x		[SNAServerAutoTPs] TPName1=SectionName1 ... TPNameX=SectionNameX		[SectionName1] PathName=path LocalLU=LUalias Parameters=ParameterList TimeOut=number Queued={ yes | no } ConversationSecurity={ yes | no } AlreadyVerified={ yes | no }* Username1=Password1* ... UsernameX=PasswordX*
Operator-started invokable TP on a client running Windows version 3.x		[SNAServerAutoTPs] TPNameN=SectionNameN ... TPNameX=SectionNameX		[SectionNameN] LocalLU=LUalias TimeOut=number Queued=operator ConversationSecurity={ yes | no } AlreadyVerified={ yes | no }* Username1=Password1* ... UsernameX=PasswordX*
* AlreadyVerified and username/password lines are used only if ConversationSecurity is set to yes.
Environment Variables for Clients Running Windows Version 3.x

The following list shows the correct form for the sections and entries to add to the WIN.INI file for autostarted invokable TPs on a client running Windows version 3.x. The section headings are shown enclosed in square brackets; include the brackets when adding the section to the WIN.INI file.

Note

The following list shows possible environment variables; use only the variables that apply to your TP, as shown in Table 2.5.

[SNAServerAutoTPs]

TPNameX=SectionNameX

For all TPs (despite the inclusion of "Auto" in the section name). Associates TPnameX with SectionNameX.  Additional lines may follow TPNameX=SectionNameX, each one using the same syntax to name a different TP and the section containing the information for that TP.

[SectionName]

Forms a section heading for entries applying to one TP; SectionName must match a section name listed under [SNAServerAutoTPs].

PathName=path

Specifies the full path and filename of the executable. The default is TPNAME.EXE.

LocalLU=LUalias

Specifies the alias of the local LU to be used when this TP is started on this computer.

Parameters=ParameterList

Lists strings to be passed as command line parameters for the TP. Separate parameters with spaces. The default is no parameters.

Timeout=number

Specifies the time, in milliseconds, that a RECEIVE_ALLOCATE will wait before timing out. The default is infinity (no limit).

Queued={ yes | no }
Queued=operator

Specifies the type of TP: yes for an autostarted queued TP, no for an autostarted nonqueued TP, or operator for an operator-started TP (which must always be queued). The default is yes.

ConversationSecurity={ yes | no }

Indicates whether this TP supports conversation security. The default is no.

AlreadyVerified={ yes | no }

Indicates whether this TP can be invoked with a user ID and password that have already been verified. AlreadyVerified is ignored if ConversationSecurity is set to no.

For detailed information about the AlreadyVerified variable, see the description for it under "Registry Entries for Clients Running Windows NT," earlier in this chapter.

The default is no.

Username1=Password1*
...
UsernameX=PasswordX*

Sets one or more usernames and passwords to be compared with those sent by the invoking TP. The username and password can each be as many as 10 characters. Both parameters are case sensitive. This variable is ignored if conversation security is not activated or if the password has already been verified, as described for the AlreadyVerified entry.

Translating SNA Service TP Names to ASCII for WIN.INI or SNA.INI

For SNA service TPs on SNA Server clients running Windows version 3.x or OS/2, the line naming the TP in the WIN.INI or SNA.INI file (respectively) must specify the TP name in ASCII. The following paragraphs tell how to convert a TP name to this form. The line should be placed in the [SNAServerAutoTPs] section of the file, as shown in Table 2.5 (earlier in this chapter) or Table 2.6 (later in this chapter).

An SNA service TP name is normally up to 4 bytes in length; the first byte is a hexadecimal number in the range 0x00 to 0x3F, and the remaining bytes are EBCDIC characters. The first byte defines the function class of the TP. Therefore, to convert a service TP name to an ASCII form, convert the first byte as shown in the following table, and convert the EBCDIC values to ASCII letter equivalents.

First byte of TP name  (hexadecimal number)		ASCII character equivalent for WIN.INI
0x07		DDM
0x20		DIA
0x21		SNAD
0x24		FS
0x30		PO
All others		UN
For example, a service TP name of 0x21 0xD7 0xD7 is equivalent to SNADPP (0x21 converts to SNAD and each 0xD7 converts to "P").

Example of WIN.INI Lines for an Invokable TP

For autostarted invokable TPs called BounceTP and TestTP, on a client running Windows version 3.x, the following WIN.INI lines might be added:

[SNAServerAutoTPs]

BounceTP=bnceprms

TestTP=testprms

[bnceprms]

PathName=c:\sna\wbounce.exe

LocalLU=Eric

Parameters=/t

timeout=60000

queued=yes

[testprms]

PathName=c:\sna\testtp.exe

LocalLU=LU1

Parameters=/v

timeout=60000

queued=no


Clients Running OS/2
Transaction Programs	20 of 27

Configuring Invokable TPs

Clients Running OS/2

On OS/2-based clients, invokable TPs are configured through entries in the SNA.INI file. Table 2.6 lists the section headings and environment variables used:

Table 2.6    Environment Variables for Invokable TPs on OS/2-Based Clients

Type of TP		Section in SNA.INI listing TP names only		Section and possible environment variables defining TP (some variables are optional)
Autostarted invokable TP on a client running OS/2		[SNAServerAutoTPs] TPName1=SectionName1 ... TPNameX=SectionNameX		[SectionName1] PathName=path LocalLU=LUalias Parameters=ParameterList TimeOut=number Queued={ yes | no } ConversationSecurity={ yes | no } AlreadyVerified={ yes | no }* Username1=Password1* ... UsernameX=PasswordX* Environment=VariableList NewScreenGroup={ 1 | 0 } IconFile=path SessionType=number PgmControl=number InitXPos=number InitYPos=number InitXSize=number InitYSize=number
Operator-started invokable TP on a client running OS/2		[SNAServerAutoTPs] TPNameN=SectionNameN ... TPNameX=SectionNameX		[SectionNameN] LocalLU=LUalias TimeOut=number Queued=operator ConversationSecurity={ yes | no } AlreadyVerified={ yes | no }* Username1=Password1* ... UsernameX=PasswordX*
* AlreadyVerified and username/password lines are used only if ConversationSecurity is set to yes.
Environment Variables for OS/2-Based Clients

The following list shows the correct form for the sections and entries to add to the SNA.INI file (located in the root SNA Server directory) for autostarted invokable TPs on an OS/2-based client. The section headings are shown enclosed in square brackets; include the brackets when adding the section to the SNA.INI file.

Note

The following list shows possible environment variables; use only the variables that apply to your TP, as shown in Table 2.6.

[SNAServerAutoTPs]

TPNameX=SectionNameX

For all TPs (despite the inclusion of "Auto" in the section name). Associates TPnameX with SectionNameX. Additional lines may follow TPNameX=SectionNameX, each one using the same syntax to name a different TP and the section containing the information for that TP.

[SectionName]

Forms a section heading for entries applying to one TP; SectionName must match a section name listed under [SNAServerAutoTPs].

PathName=path

Specifies the full path and filename of the executable. The default is TPNAME.EXE.

LocalLU=LUalias

Specifies the alias of the local LU to be used when this TP is started on this computer.

Parameters=ParameterList

Lists strings to be passed as command line parameters for the TP. Separate parameters with spaces. The default is no parameters.

Timeout=number

Specifies the time, in milliseconds, that a RECEIVE_ALLOCATE will wait before timing out. The default is infinity (no limit).

Queued={ yes | no }

Queued=operator

Specifies the type of TP: yes for an autostarted queued TP, no for an autostarted nonqueued TP, or operator for an operator-started TP (which must always be queued). The default is yes.

ConversationSecurity={ yes | no }

Indicates whether this TP supports conversation security. The default is no.

AlreadyVerified={ yes | no }

Indicates whether this TP can be invoked with a user ID and password that have already been verified. AlreadyVerified is ignored if ConversationSecurity is set to no.

For detailed information about the AlreadyVerified variable, see the description for it under "Registry Entries for Clients Running Windows NT," earlier in this chapter.

The default is no.

Username1=Password1*
...
UsernameX=PasswordX*

Sets one or more usernames and passwords to be compared with those sent by the invoking TP. The username and password can each be as many as 10 characters. Both parameters are case sensitive. This variable is ignored if conversation security is not activated or if the password has already been verified, as described for the AlreadyVerified entry.

Environment=VariableList

For an autostarted TP, lists the variables to be set in the TP's environment. Separate multiple variables with spaces.

NewScreenGroup={ 1 | 0 }

For an autostarted TP, specifies 1 to indicate that the TP runs in the foreground, or 0 to indicate that the TP runs in the background. The default is 1 (foreground).

IconFile=path

For an autostarted TP, specifies the full path and filename of the icon file. The default is no icon file.

SessionType=number

For an autostarted TP, specifies a value used by OS/2; see the note following. The default is 0.

PgmControl=number

For an autostarted TP, specifies a value used by OS/2; see the note following. The default is 32768.

InitXPos=number

For an autostarted TP, specifies a value used by OS/2; see the note following. The default is 80.

InitYPos=number

For an autostarted TP, specifies a value used by OS/2; see the note following. The default is 80.

InitXSize=number

For an autostarted TP, specifies a value used by OS/2; see the note following. The default is 470.

InitYSize=number

For an autostarted TP, specifies a value used by OS/2; see the note following. The default is 330.

Note

SessionType, PgmControl, InitXPos, InitYPos, InitXSize, and InitYSize are filled directly into the STARTDATA structure passed to the OS/2 DosStartSession call for the new session.

Translating SNA Service TP Names to ASCII

For SNA service TPs on SNA Server clients running OS/2, the line naming the TP in the SNA.INI file must specify the TP name in ASCII. For information about how to convert an SNA service TP name to an ASCII form, see "Translating SNA Service TP Names to ASCII for WIN.INI or SNA.INI," earlier in this chapter.


Clients Running MS-DOS
Transaction Programs	21 of 27

Configuring Invokable TPs

Clients Running MS-DOS

SNA Server does not support invokable TPs on MS-DOS  based clients.


Configuring an SNA Server to Support TPs
Transaction Programs	22 of 27

Configuring an SNA Server to Support TPs

The following sections describe how the SNA Server configuration works with invoking and invokable TPs.


Invoking TPs and the SNA Server Configuration
Transaction Programs	23 of 27

Configuring an SNA Server to Support TPs

Invoking TPs and the SNA Server Configuration

In order for an SNA server to support the beginning of the invoking process (that is, to accept the TP_STARTED and [MC_]ALLOCATE verbs issued by an invoking TP), the following parameters must be configured correctly:

If the invoking TP specifies the LU alias that it uses (in TP_STARTED), that LU alias must match a local APPC LU alias on the supporting SNA server. If the invoking TP leaves the LU alias blank in TP_STARTED, one of two methods for designating a default LU must be carried out on the supporting SNA server. One method is to assign a default local APPC LU to the user or group that starts the invoking TP (that is, the user or group logged on at the system from which TP_STARTED is issued). The other method is to designate one or more LUs as members of the default outgoing local APPC LU pool. SNA Server first attempts to determine the default local APPC LU of the user who started the TP, then attempts to assign an available LU from the default outgoing local APPC LU pool; if these attempts fail, SNA Server rejects the request.

In most situations, the supporting SNA server must contain an appropriate connection to another system (host or peer). Sometimes, for testing purposes, the SNA server contains two local LUs paired together (for invoking and invokable TPs that are in the same domain); in this situation, a connection to a host or peer is not necessary.

If the invoking TP specifies the partner LU alias (in [MC_]ALLOCATE), that LU alias must match an LU alias that is paired with the local LU alias specified in TP_STARTED. If the partner LU alias is left unspecified in [MC_]ALLOCATE, a Default Remote APPC LU must be assigned to the user who started the invoking TP (the Default Remote APPC LU is assigned in SNA Server Admin). If the Default Remote APPC LU is used, it must be paired with the local LU that will be used. Otherwise, [MC_]ALLOCATE fails.

The preceding parameters support the beginning of the invoking process. In order for the invoking process to successfully complete, additional parameters must be configured as described in the next section.


Invokable TPs and the SNA Server Configuration
Transaction Programs	24 of 27

Configuring an SNA Server to Support TPs

Invokable TPs and the SNA Server Configuration

In order for an SNA server to receive allocation requests from an invoking TP on another system, and then route those requests to an invokable TP, certain parameters must be configured correctly:

The SNA server must have a connection to the system from which the invoking TP's request is sent.

The SNA server must have a remote LU capable of receiving the incoming request. This remote LU can be configured either explicitly or implicitly.

When configured explicitly, there is an explicit match between a remote LU alias on the SNA server and the alias of the LU that conveys the invoking TP's request.

When configured implicitly, an implicit incoming remote LU (with its implicit incoming mode) is used. This means that several items must work together. First, the LU alias specified in the incoming request (the LU alias requested for the invokable TP) must match a local LU alias on the SNA server receiving the request. Second, the local LU on the SNA server must have an implicit incoming remote LU assigned to it. The properties of the implicit incoming remote LU will be used for that LU-LU session. For more details about how an implicit incoming remote LU works, see the Microsoft SNA Server Administration Guide.

Appropriate local LUs must be defined in the SNA Server configuration. For descriptions of several ways to set up these local LUs, see the next section.


Possible Arrangements of TPs Within an SNA Network
Transaction Programs	25 of 27

Configuring an SNA Server to Support TPs

Possible Arrangements of TPs Within an SNA Network

If your SNA Server installation contains multiple systems (clients and/or SNA servers), you can place a given invokable TP on more than one system. When an invoking request is received in such an installation, there will (potentially) be a choice of systems on which to run the invokable TP. You can maintain specific control over this choice; alternatively, by following the instructions in "TP Name Not Unique; Local LU Alias Unspecified" (later in this chapter), you can allow the choice to be made randomly by SNA Server (to distribute the load).

You can maintain specific control over this choice of system by setting up invokable TPs with unique names, or by setting up each invokable TP to run only with a specific, unique LU alias. With this arrangement, the information provided by the invoking TP (in the ALLOCATE verb) will specify the particular system on which the invokable TP should run.

You can avoid controlling this choice of system, and allow the choice to be made randomly by SNA Server, by setting the DloadMatchLocalFirst Registry entry to NO, as described in the Microsoft SNA Server Reference, and using invokable TPs that leave the local LU alias unspecified. Then, when an incoming request is received, it is routed randomly, rather than preferentially to the local SNA server; in addition, no matter what LU alias is requested for the invokable TP, there cannot be a mismatch. SNA Server will start one instance of the requested TP, choosing randomly among the available systems.

The following sections describe some of the possible arrangements that can be made for the running of TPs.

TP Name Unique for Each TP

If you want to specify the intended system where the invokable TP will run, one way to do it is to use a unique TP name for each invokable TP. In this arrangement, the invoking TP identifies the intended invokable TP (and system) simply by naming the TP. This makes it unnecessary for an invokable TP to specify any LU alias in Registry or environment variables.

TP Name Not Unique; Local LU Alias Unique

If you want to specify the intended system where the invokable TP will run, another way to do it (besides using unique TP names) is to give the same name to multiple invokable TPs, but associate each TP with a unique local LU alias. To do this, configure each invokable TP (through Registry or environment variables) to use a unique local LU alias. Then set up the invoking TPs so that each one is routed not only to the correct TP name but also to the correct partner LU alias for the intended invokable TP.

TP Name Not Unique; Local LU Alias Unspecified

If it does not matter which system an invokable TP runs on, use the same name for multiple invokable TPs, and in addition, do not specify an LU alias in the Registry or environment variables for the TPs. In such a situation, in the list of available invokable TP names on an SNA server, there are no associated LU aliases. Thus, a request received from an invoking TP cannot cause a mismatch on the LU alias, and will match according to the TP name.

In such a situation, if you set the DloadMatchLocalFirst Registry entry to NO, as described in the Microsoft SNA Server Reference, SNA Server randomly routes the request to one of the available TPs. This spreads the processing load out among multiple systems, and provides hot backup (the ability to take systems on- and offline without disrupting service).


Troubleshooting for Invokable TPs
Transaction Programs	26 of 27

Configuring an SNA Server to Support TPs

Troubleshooting for Invokable TPs

If there are difficulties with starting an invokable TP, but SNA Server seems to be running smoothly otherwise, there may be a mismatch between the information for the invokable TP, the invoking TP, and/or LUs in the SNA Server configuration. That is, there may be a mismatch between the RECEIVE_ALLOCATE parameters, the TP_STARTED and/or ALLOCATE parameters, and/or LU aliases specified in SNA Server Admin. For details about how to specify LU aliases in SNA Server Admin, see the Microsoft SNA Server Administration Guide.


SNA Server Features That Simplify APPC Configuration
Transaction Programs	27 of 27

Configuring an SNA Server to Support TPs

SNA Server Features That Simplify APPC Configuration

There are several features in SNA Server that can simplify configuration for APPC:

The implicit incoming remote LU and the implicit incoming mode, which allow SNA Server to accept requests that arrive by unrecognized remote LUs and modes.

The default local APPC LU and the default remote APPC LU, which allow LU aliases to be associated with user or group names, simplifying the routing of incoming requests and the configuration of client systems.

The default outgoing local APPC LU pool, which allows LUs to be allocated dynamically to any invoking TP that does not specify a local LU.

Automatic partnering, which automatically creates LU-LU pairs and assigns modes to the pairs.

For more information about these features, see the Microsoft SNA Server Administration Guide.


APPC Management Verbs
Chapter 3	1 of 4

APPC Management Verbs

This chapter describes the APPC management verbs:

CNOS (Change Number of Sessions)

DISPLAY

The management verbs allow you to establish APPC LU 6.2 session limits and obtain configuration information and current operating values for the SNA node. The description of the verbs provides:

A definition of the verb.

The structure defining the VCB used by the verb. The structure is contained in the WINAPPC.H file. The length of each VCB field is in bytes. Fields beginning with reserv, for example, reserv2, are reserved.

The parameters (VCB fields) supplied to and returned by APPC. For each parameter, the following information is provided:

Description

Possible values

Additional information

The conversation state(s) in which the verb can be issued.

The state(s) to which the conversation can change upon return from the verb. Conditions that do not cause a state change are not noted. For example, parameter checks and state checks do not cause a state change.

Additional information describing the verb.

Most parameters supplied to and returned by APPC are hexadecimal values. To simplify coding, these values are represented by meaningful symbolic constants, which are established by #define statements in the WINAPPC.H header file. For example, the opcode (operation code) parameter of MC_SEND_DATA is the hexadecimal value represented by the symbolic constant AP_M_SEND_DATA. Use only the symbolic constants when writing TPs.


CNOS (Change Number of Sessions)
APPC Management Verbs	2 of 4

CNOS (Change Number of Sessions)

Establishes APPC LU 6.2 session limits.

Syntax

opcode	unsigned short int

reserv2	unsigned char

primary_rc	unsigned short int

secondary_rc	unsigned long int

key	unsigned char

lu_alias	unsigned char

partner_lu_alias	unsigned char

fqplu_name	unsigned char

reserv3	unsigned char

mode_name	unsigned char

mode_name_select	unsigned int

set_negotiable	unsigned char

reserv4	unsigned int

reserv5	unsigned int

plu_mode_sess_lim	unsigned short int

min_conwinners_source	unsigned short int

min_conwinners_target	unsigned short int

auto_act	unsigned short int

drain_target	unsigned int

drain_source	unsigned int

responsible	unsigned int

reserv6	unsigned int

reserv7	unsigned int

Parameter	Description

opcode	Supplied parameter; CNOS.

key	Supplied parameter; specifies either the master or service key, if the keylock feature has been secured.

lu_alias	Supplied parameter; provides the 8-byte ASCII name used locally for the LU.

partner_lu_alias	Supplied parameter; provides the 8-byte ASCII name used locally for the partner LU.

fqplu_name	Supplied parameter; provides the partner LU name when no partner_lu_alias name is defined at the local node and the partner LU is located at a different node.

mode_name	Supplied parameter; specifies the EBCDIC mode name to be used when the value of mode_name_select is ONE.

mode_name_select	Supplied parameter; specifies the modem for which your program is setting or resetting the session limits and contention-winner polarities. Allowed values are ALL or ONE.

set_negotiable	Supplied parameter; specifies whether APPC is to change the current setting for the maximum negotiable session limit. Allowed values are YES and NO.

plu_mode_sess_lim	Supplied parameter; specifies the session limit when the value for set_negotiable is YES.

min_conwinners_source	Supplied parameter; specifies the number of sessions of which the LU is guaranteed to be the contention winner. Allowed values are 0 or greater.

min_conwinners_target	Supplied parameter; specifies the minimum number of sessions of which the target LU is guaranteed to be the contention winner. Allowed values are 0 or greater.

auto_act	Supplied parameter; specifies the number of the local LU’s contention-winner sessions for APPC to activate automatically. See “Remarks” later in this section before using this parameter.

drain_target	Supplied parameter; specifies whether the target LU can drain its waiting (outbound) allocation requests. Allowed values are YES and NO.

drain_source	Supplied parameter; specifies whether the source LU can drain its waiting (outbound) allocation requests. Allowed values are YES and NO.

responsible	Supplied parameter; specifies which LU is responsible for deactivating the sessions as a result of resetting the session limit for parallel-session connections. Allowed values are SOURCE and TARGET.

Return Codes

AP_OK

Primary return code; the verb executed successfully:

AP_CNOS_ACCEPTED

Secondary return code; APPC accepts the session limits and responsibility as specified.

AP_CNOS_NEGOTIATED

Secondary return code; APPC accepts the session limits and responsibility as negotiable by the partner LU. Values that can be negotiated are:

plu_mode_session_limit

min_conwinners_source

min_conwinners_target

responsible

drain_target

AP_ALLOCATION_ERROR

Primary return code; APPC has failed to allocate a conversation. The conversation state is set to RESET.

This code may be returned through a verb issued after [MC_]ALLOCATE.

AP_ALLOCATION_FAILURE_NO_RETRY

Secondary return code; the conversation cannot be allocated because of a permanent condition, such as a configuration error or session protocol error. To determine the error, the system administrator should examine the error log file. Do not retry the allocation until the error has been corrected.

AP_ALLOCATION_FAILURE_RETRY

Secondary return code; the conversation could not be allocated because of a temporary condition, such as a link failure. The reason for the failure is logged in the system error log. Retry the allocation.

AP_CNOS_LOCAL_RACE_REJECT

Primary return code; APPC is currently processing a CNOS verb issued by a local LU.

AP_CNOS_PARTNER_LU_REJECT

Primary return code; the partner LU rejected a CNOS request from the local LU:

AP_CNOS_MODE_CLOSED

Secondary return code; the local LU cannot negotiate a nonzero session limit because the local maximum session limit at the partner LU is zero.

AP_CNOS_MODE_NAME_REJECT

Secondary return code; the partner LU does not recognize the specified mode name.

AP_CNOS_COMMAND_RACE_REJECT

Secondary return code; the local LU is currently processing a CNOS verb issued by the partner LU.

AP_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 physical unit (PU) 2.1 node has been broken (a local area network [LAN] error).

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

The system administrator should examine the error log to determine the reason for the ABEND.

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

When this return code is used with [MC_]ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there isn’t a node available that can satisfy the [MC_]ALLOCATE request.

When [MC_]ALLOCATE produces this return code for an SNA Server system, there are two secondary return codes as follows:

X'F0000001'

Secondary return code; no nodes have been started.

X'F0000002'

Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:

The node with the local LU is not started.

The local LU is not configured.

AP_INVALID_KEY

Primary return code; the supplied key was incorrect.

AP_INVALID_VERB_SEGMENT

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

AP_PARAMETER_CHECK

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

AP_ALL_MODE_MUST_RESET

Secondary return code; APPC does not permit a nonzero session limit when the mode_name_select parameter indicates ALL.

AP_AUTOACT_EXCEEDS_SESSLIM

Secondary return code; on the CNOS verb, the value for auto_activate is greater than the value for partner_lu_mode_session_limit.

AP_BAD_LU_ALIAS

Secondary return code; APPC cannot find the specified lu_alias among those defined.

AP_BAD_PARTNER_LU_ALIAS

Secondary return code; APPC did not recognize the supplied partner_lu_alias.

AP_BAD_SNASVCMG_LIMITS

Secondary return code; your program specified invalid settings for partner_lu_mode_session_limit, min_conwinners_source, or min_conwinners_target when mode_name was supplied.

AP_CHANGE_SRC_DRAINS

Secondary return code; APPC does not permit mode_name_select (ONE) and drain_source (YES) when drain_source (NO) is currently in effect for the specified mode.

AP_CNOS_IMPLICIT_PARALLEL

Secondary return code; APPC does not permit a program to change the session limit for a mode other than the SNASVCMG mode for the implicit partner template when the template specifies parallel sessions. (The term template is used because many of the actual values are yet to be filled in).

AP_CPSVCMG_MODE_NOT_ALLOWED

Secondary return code; the mode named CPSVCMG cannot be specified as the mode_name on the deactivate session verb.

AP_EXCEEDS_MAX_ALLOWED

Secondary return code; your program issued a CNOS verb, specifying a partner_lu_mode_session_limit number and set_negotiable (NO).

AP_MIN_GT_TOTAL

Secondary return code; the sum of min_conwinners_source and min_conwinners_target specifies a number greater than partner_lu_mode_session_limit.

AP_MODE_CLOSED

Secondary return code; the local LU cannot negotiate a nonzero session limit because the local maximum session limit at the partner LU is zero.

AP_RESET_SNA_DRAINS

Secondary return code; SNASVCMG does not support the drain parameter values.

AP_SINGLE_NOT_SRC_RESP

Secondary return code; for a single-session CNOS verb, APPC permits only the local (source) LU to be responsible for deactivating sessions.

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

AP_STATE_CHECK

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

AP_CANT_RAISE_LIMITS

Secondary return code; APPC does not permit setting session limits to a nonzero value unless the limits currently are zero.

AP_LU_DETACHED

Secondary return code; a command has reset the definition of the local LU before CNOS tried to specify the LU.

AP_SNASVCMG_RESET_NOT_ALLOWED

Secondary return code; your local program attempted to issue the CNOS verb for the mode named SNASVCMG, specifying a session limit of 0.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC verb from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

Remarks

CNOS identifies an LU by alias alone. If the same local LU alias is used multiple times in a domain (for backup or other purposes) and that LU alias is specified through CNOS, the verb may flow to a different LU than the one intended.

If CNOS is not issued to set the mode session limit before a program issues its first APPC [MC_]ALLOCATE, or [MC_]SEND_CONVERSATION, or Common Programming Interface for Communications (CPI-C) CMALLC call for a given partner LU and mode, APPC will internally generate one using the value from the mode definition.

When setting the limits for a parallel-session connection, the two LUs negotiate the mode session limits, drain settings, and responsibility values. APPC updates these parameters in CNOS to reflect the settings agreed to by both LUs during negotiation. Your program can issue DISPLAY to obtain the negotiated values for the mode session limit.

No CNOS negotiation occurs when setting the limits for a single session (that is, the two LUs do not negotiate drain settings or responsibility values). Therefore, coordinate the mode definition parameter settings between partner LUs using a single-session connection by defining a single session mode at each node.

As part of setting up the initial limits, CNOS also sets the guaranteed (that is, the minimum) number of contention-winner and contention-loser sessions and sets the automatic activation count for the source LU’s contention-winner sessions. The action of CNOS normally affects only the group of sessions with the specified mode name between the source LU and the target LU. Alternatively, one CNOS can reset the session limits of all modes for a partner LU.

APPC enforces the new mode session limit and the contention-winner polarities until one side or the other changes them by issuing a subsequent CNOS verb. The CNOS transaction is invisible at the target LU’s API, regardless of which LU is the target. The results of the CNOS transaction can be obtained using DISPLAY.

Setting a Session Limit to 0

After CNOS raises the session limit above 0, it can reset the limit to 0 only. It cannot set the session limit to a value that is not 0, and it cannot redistribute the number of sessions allocated as the contention winners and losers. Therefore, your program cannot change the mode session limits if the two LUs have already set the limits to a nonzero value, regardless of which LU initiated the CNOS transaction.

A program can change the session limits from a non-zero value, as long as the program first changes the session limit to 0. For example, if the session limit is 8, a program can change it to 6 by first issuing CNOS and changing the session limit to 0, and then issuing CNOS again and setting the session limit to 6.

APPC may activate one or more LU-LU sessions with the specified mode name as a result of initializing the session limit. You cannot use CNOS to activate sessions between two LUs on the same server. APPC deactivates all LU-LU sessions for the specified mode name (or for all mode names for a partner LU) as a result of resetting the session limit to 0. APPC deactivates each session as it becomes free and does not interrupt active conversations.

A separate value, the maximum negotiable session limit, is used in CNOS negotiations. If set_negotiable value is YES, the mode session limit value given in this CNOS verb also sets the maximum negotiable session limit.

The lu_alias and partner_lu_alias parameters are 8-byte ASCII character strings. If the name is fewer than 8 bytes, it must be padded on the right with ASCII spaces.

You can specify the SNA-defined mode name SNASVCMG for mode_name. Use this mode only in a CNOS transaction when the source LU and the target LU use parallel user sessions. However, when resetting the session limits to 0 for the SNASVCMG PU 2.1 node, the session limits of all other modes between the two LUs must be reset first. The PU 2.1 node-name is a type A EBCDIC character string. A mode name consisting of all spaces is supported. The SNA-defined mode name CPSVCMG is not allowed.

When specifying plu_mode_session_limit, if the mode session limit is currently greater than 0, the value of this parameter must be 0. CNOS can raise the limit above 0, but the next CNOS must set the value to 0. A single CNOS cannot change the mode session limit from one nonzero number to another.

When raising the mode session limit above 0 for a parallel-session connection, the target LU can negotiate its parameter to a value greater than 0 and less than the specified session limit. The specified or negotiated limit then becomes the new mode session limit and is returned in this field.

The value specified for this parameter must be greater than or equal to the sum of the values specified in the CNOS min_conwinners_source and min_conwinners _target parameters.

Do not reset the SNASVCMG session limit to 0 until all other mode session limits between the two LUs are reset to 0 and the count of active sessions for all modes (except SNASVCMG) for the partner LU is 0.

The mode session limit should be large enough to accommodate all active conversations in the mode for all TPs.

For min_conwinners_source and min_conwinners_target, the sum of both parameters cannot exceed the mode session limit. For single-session connections, these parameters specify the desired contention-winner sessions for the target and source LUs. For the SNASVCMG mode name (with a mode session limit of 2 or 1), the specified minimum number of contention-winner sessions for the target LU must be 1. For the source LU, with a number session limit of 2, the number must be 1. With a mode session limit of 1, the number must be 0. APPC uses these parameters only when the mode session limit is set to a nonzero value.

APPC uses auto_activate only when the mode session limit is set to a nonzero value. If the value is greater than the min_conwinners_source value, APPC uses the new minimum number of contention winners for the source LU as the auto-activation limit.

Caution

This parameter may conflict with the on-demand definition of a connection. Autoactivations by either peer partner may re-establish sessions and connections, possibly resulting in a thrashing situation. Therefore, avoid specifying autoactivation between peer PU 2.1 nodes using on-demand connections.

Whether an LU deactivates a session immediately after the current conversation or after all queued conversations are complete depends on the drain_source and drain_target parameters.

If an LU is to drain its waiting (outbound) allocation requests, it continues to allocate conversations to active sessions. The responsible LU deactivates a session only when the conversation allocated to the session is deallocated and no request is waiting for allocation to any session with the specified mode name between the two LUs. The allocation of a waiting request takes precedence over the deactivation of a session.

If an LU is not to drain its waiting (outbound) allocation requests, the responsible LU deactivates a session as soon as the conversation allocated to the session is deallocated. If no conversation is allocated to the session, the responsible LU deactivates the session immediately. However, this verb does not force deallocation of active conversations.

The responsible and mode_name_select parameters are interrelated as follows:

APPC ignores the responsible parameter for mode names for which the session limit is currently 0 if this CNOS verb specifies mode_name_select (ALL).

If CNOS specifies mode_name_select (ONE) with a mode session limit of 0 and the current session limit for that mode name is already 0, the responsible parameter must specify the same LU (SOURCE or TARGET) that is currently responsible for deactivating sessions. APPC uses this parameter only when CNOS specifies a mode session limit of 0.

For parallel-session connections, the drain_source and mode_name_select parameters are interrelated as follows:

If CNOS specifies mode_name_select (ALL) and drain_source (YES), APPC ignores drain_source for those mode names for which the session limit is currently 0.

If CNOS specifies mode_name_select (ALL) and drain_source (NO), APPC accepts drain_source for all mode names. APPC ends draining for any mode currently draining its requests.

If CNOS specifies mode_name_select (ONE), and drain_source (YES) is currently in effect, drain_source (NO) directs APPC to end the draining at the source LU for requests for the specified mode_name.

If CNOS specifies mode_name_select (ONE) and drain_source (NO) is currently in effect, your program must specify drain_source (NO) again.

For parallel-session connections, the drain_target parameter and the mode_name_select parameter are interrelated as follows:

If CNOS specifies mode_name_select (ALL) and drain_target (YES), APPC ignores drain_target for the mode names for which the session limit is currently zero.

If CNOS specifies mode_name_select (ALL) and drain target (NO), APPC accepts drain_target for all mode names, regardless of the current session limit. Any draining of waiting (outbound) allocation requests at the target LU is ended.

If CNOS specifies mode_name_select (ONE) and drain_target (YES) is currently in effect, drain_target (NO) ends the target LU’s draining.

If CNOS specifies mode_name_select (ONE) and drain_target (YES) and drain_target (NO) is currently in effect, the target LU can either accept drain_target (YES) or negotiate the parameter to NO. After the target LU accepts the drain_target (YES) parameter, it can drain any remaining waiting (outbound) allocation requests.


DISPLAY
APPC Management Verbs	3 of 4

DISPLAY

Returns configuration information and current operating values for the SNA node.

Microsoft recommends that you use GetAPPCConfig to obtain system configuration information relating to APPC LUs. 5250 emulator users, in particular, should use the GetAPPCConfig extension. For more information on using GetAPPCConfig, see Chapter 7, “SNA Server-Specific Enhancements for the Windows Environment.”

Note

Because of the nature of client/server architecture, the SNA Server version of DISPLAY contains important differences from the IBM Extended Services for OS/2 version 1.0 (IBM ES for OS/2 version 1.0) on which it was based. These differences are described in “DISPLAY Differences,” later in this section. For a complete description of DISPLAY, see the IBM system management verb manual. For information on configuring DISPLAY in SNA Server Admin, see the Microsoft SNA Server Administration Guide.

For applications that use the APPC DISPLAY verb in IBM ES for OS/2 version 1.0 compatibility mode and that do not use the SNA Server extensions for enumerating all active servers and connections, SNA Server will randomly choose a default DISPLAY connection, unless a specific default DISPLAY connection has been configured in SNA Server Admin. This connection is used as the basis for all DISPLAY requests. For information about specifying the default DISPLAY connection, see the Microsoft SNA Server Administration Guide.

Syntax

opcode	unsigned short int

reserv2	unsigned char

primary_rc	unsigned short int

secondary_rc	unsigned long int

init_sect_len	unsigned long int

buffer_len	unsigned long int

buffer_ptr	unsigned char far*

num_sections	unsigned long int

display_len	unsigned long int

area_needed	unsigned long int

sna_global_info	unsigned char

lu_62_info	unsigned char

am_info	unsigned char

tp_info	unsigned char

sess_info	unsigned char

link_info	unsigned char

lu_0_3_info	unsigned char

gw_info	unsigned char

x25_physical_link_info	unsigned char

sys_def_info	unsigned char

adapter_info	unsigned char

lu_def_info	unsigned char

plu_def_info	unsigned char

mode_def_info	unsigned char

link_def_info	unsigned char

ms_info	unsigned char

sna_global_info_secct	struct far

lu_62_info_sect	struct far

am_info_sect	struct far

tp_info_sect	struct far

sess_info_sect	struct far

link_info_sect	struct far

lu_0_3_info_sect	struct far

gw_info_sect	struct far

x25_physical_link_info_sect	struct far

sys_def_info_sect	struct far

adapter_info_sect	struct far

lu_def_info_sect	struct far

plu_def_info_sect	struct far

mode_def_info_sect	struct far

link_def_info_sect	struct far

ms_info_sect	struct far

Parameter	Description

opcode	Supplied parameter; DISPLAY.

init_sect_len	Supplied parameter; specifies the number of bytes in the VCB, up to the beginning of information pointers.

Supplied parameter; specifies the length (0 to 65535 bytes) of the display data buffer that is to contain the returned address.

buffer_ptr	Supplied parameter; provides the address of the buffer that will contain the requested information.

num_sections	Supplied parameter; specifies the maximum number of information sections that can be returned by the verb.

display_len	Returned parameter; provides the total number of bytes returned into the display data buffer.

area_needed	Returned parameter; provides the total number of bytes needed for displayed data.

sna_global_info	Supplied parameter; specifies if global information is requested. Allowed values are YES and NO.

lu_62_info	Supplied parameter; specifies if information on all active LUs, their partners, and their modes is requested. Allowed values are YES and NO.

am_info	Supplied parameter; specifies if information on the defined TP is requested. Allowed values are YES and NO.

tp_info	Supplied parameter; specifies if information on the active TPs and any active conversations is requested. Allowed values are YES and NO.

sess_info	Supplied parameter; specifies if information on sessions is requested. Allowed values are YES and NO.

link_info	Supplied parameter; specifies if information on the active SNA logical lines is requested. Allowed values are YES and NO.

lu_0_3_info	Supplied parameter; specifies if information on logical units type 0, 1, 2, and 3 is requested. Allowed values are YES and NO.

gw_info	Supplied parameter; specifies if information on the SNA gateway is requested. Allowed values are YES and NO.

x25_physical_link_info	Supplied parameter; specifies if X.25 information is required. Allowed values are YES and NO.

sys_def_info	Supplied parameter; specifies if information about the default LU, node names, and default parameters for inbound and outbound implicit partners is requested. Allowed values are YES and NO.

adapter_info	Supplied parameter; specifies if information about the configured communications adapters is requested. Allowed values are YES and NO.

lu_def_info	Supplied parameter; specifies if information about the defined LUs is requested. Allowed values are YES and NO.

plu_def_info	Supplied parameter; specifies if information about the defined partner LUs is requested. Allowed values are YES and NO.

mode_def_info	Supplied parameter; specifies if information about the defined nodes is requested. Allowed values are YES and NO.

link_def_info	Supplied parameter; specifies if information about the defined logical links is requested. Allowed values are YES and NO.

ms_info 	Supplied parameter; specifies if information about management services is requested. Allowed values are YES and NO.

sna_global_info_sect	Returned parameter; indicates the address of the beginning of SNA global information in the data buffer.

lu_62_info_sect	Returned parameter; indicates the address of the beginning of LU 6.2 information in the data buffer.

am_info_sect	Returned parameter; indicates the address of the beginning of the Attach Manager information in the data buffer.

tp_info_sect	Returned parameter; indicates the address of the beginning of TP information in the data buffer.

sess_info_sect	Returned parameter; indicates the address of the beginning of session information in the data buffer.

link_info_sect	Returned parameter; indicates the address of the beginning of link information in the data buffer.

lu_0_3_info_sect	Returned parameter; indicates the address of the beginning of LU information in the data buffer.

gw_info_sect	Returned parameter; indicates the address of the beginning of gateway information in the data buffer.

x25_physical_link_ info_sect	Returned parameter; indicates the address of the beginning of X.25 information in the data buffer.

sys_def_info_sect	Returned parameter; indicates the address of the beginning of system default information in the data buffer.

adapter_info_sect	Returned parameter; indicates the address of the beginning of adapter information in the data buffer.

lu_def_info_sect	Returned parameter; indicates the address of the beginning of local LU definition information in the data buffer.

plu_def_info_sect	Returned parameter; indicates the address of the beginning of partner LU definition information in the data buffer.

mode_def_info_sect	Returned parameter; indicates the address of the beginning of mode definition information in the data buffer.

link_def_info_sect	Returned parameter; indicates the address of the beginning of link definition information in the data buffer.

ms_info_sect	Returned parameter; indicates the address of the beginning of management services information in the data buffer.


DISPLAY Differences
APPC Management Verbs	4 of 4

DISPLAY

DISPLAY Differences

This section describes the differences between the data returned by the SNA Server version of DISPLAY and the IBM ES for OS/2 version 1.0 on which it was based.

SNA Server’s extensions on the IBM ES for OS/2 version 1.0 DISPLAY verb are defined. These extensions are necessary because of the client/server architecture of SNA Server.

Each information type is listed separately. A list of the differences in the information returned for the information type is provided, followed by any additional comments.

Note

SNA Server does not support all of the information types supported by IBM ES for OS/2 version 1.0. If an information type is not listed in this section, it is not supported by SNA Server.

SNA Server Extensions

The SNA Server DISPLAY verb is compatible with the IBM ES for OS/2 version 1.0 DISPLAY verb. However, since IBM ES for OS/2 version 1.0 is a single-server system and SNA Server is a multiple-server client/server system, DISPLAY has been extended to allow the user to target the SNA Server by which the DISPLAY verb will be processed.

To direct a DISPLAY verb at a particular SNA server, place the ASCII string CSEXTNID followed by the computer name of the SNA server at the start of the buffer pointed to by buffer_ptr. The computer name is a 32-byte ASCII string and can be 0 or padded with spaces.

Because the local node ID is configured on a per-node basis for IBM ES for OS/2 version 1.0 and can be different for each connection in SNA Server, SNA Server also allows you to specify an optional connection name. This is an 8-byte ASCII string, which is placed after the 32-byte computer name. Again, the string can be 0 or padded with spaces. The following example illustrates the CSEXTNID extension:

csextnid computername 00000000000000000000 name

If you do not specify a connection name, SNA Server returns information about the first connection configured for the SNA Server system.

If you do not specify a computer name, SNA Server will randomly choose a default DISPLAY computer and connection, unless a specific default DISPLAY connection has been configured in SNA Server Admin. DISPLAY will behave as if you specified the connection and the computer name of the server that owns the verb. For additional information about using default LUs, see the Microsoft SNA Server Administration Guide.

SNA Server also allows you to use DISPLAY to return a list of active servers. To do so, place the string CSEXTNIDCSLISTND in the DISPLAY buffer and set the supplied parameters sna_global_info, lu62_info, and so on, to AP_NO. The information is returned in the DISPLAY buffer in the following format:

#activenodes	- 2 bytes

node_name 1	- 8 bytes

box_name 1	- 32 bytes

.

node_name m

box_name m

In the current version, node_name will always be SNASERVR. The box_name is the computer name of the server.

Differences by Information Type

Differences to the SNA Server DISPLAY are described in this section by information type.

SNA Global Information

IBM ES for OS/2 version 1.0 definition:

Parameter	Information returned

version	EE version number

release	EE release number

appc_version	NS/2 version number

appc_release	NS/2 release number

ns_csd_level	Last 4 digits of corrective service disk number

net_name	Network name (first part of fully qualified cp_name)

cp_name	Node name (second part of fully qualified cp_name)

alias_cp_name	Node name (local name for CP)

node_id	4-byte hex exchange ID

node_type	NN or EN

product_set_id	Computer data

SNA Server data returned:

Parameter	Information returned

version	Major operating system (OS) version number

release	Minor OS version number

appc_version	SNA Server major version number

appc_release	SNA Server minor version number

ns_csd_level	Set to 0

net_name	Node network name

cp_name	CP name associated with connection

alias_cp_name	Node name

node_id	Node ID to send

node_type	Set to LEN

product_set_id	Set to EBCDIC zeros

SNA Server returns version/release as the major and minor OS version numbers from GetVersion (for Windows NT or Windows version 3.x systems) or GetDosVersion (for OS/2).

Because SNA Server has no information on the computer type, serial number, and manufacturing, product_set_id is set to EBCDIC zeros.

SNA Server does not support APPN [image] node types so the node type is returned as '1', a LEN node, and not '2' or '3', NN or EN nodes, as defined by IBM ES for OS/2 version 1.0.

LU 6.2 Information

IBM ES for OS/2 version 1.0 definition:

Parameter	Information returned

For local LU group, default_lu	LU used if none specified

For partner LU group, implicit_partner	Indicates if implicit-partner LU was created as a result of receiving a session activation request from an unconfigured partner LU

For mode group, implicit_mode	Indicates if implicit-mode was created as a result of receiving a session activation request specifying an unconfigured mode

SNA Server data returned:

Parameter	Information returned

For local LU group, default_lu	Set to NO

For partner LU group, implicit_partner	Indicates the partner LU group was configured as an implicit primary logical unit (PLU)

For mode group, implicit_mode	Indicates the mode group was configured as an implicit mode

For SNA Server, there is no concept of a default local LU. Therefore, the default_lu flag which is set to YES for the node in IBM ES for OS/2 version 1.0, is set to NO.

SNA Server returns information on all the configured LU 6.2s in the system, including the implicit PLU and all instances of implicit modes. IBM ES for OS/2 version 1.0 only returns information on those that are in use or have been in use.

Session Information

IBM ES for OS/2 version 1.0 definition:

Parameter	Information returned

link_id	Name of local logical link station

type_of_session	SSCP_PU_SESSION, SSCP_LU_SESSION, or LU_LU_SESSION

fq_pc_id	Fully qualified procedure correlation identifier of the session

conversation_group_id	Unique identifier of the session

type_of_pacing	FIXED or ADAPTIVE

SNA Server data returned:

Parameter	Information returned

link_id	Connection name

type_of_session	SSCP_PU_SESSION is never returned

fq_pc_id	Set to 0

conversation_group_id	Set to 0

Always returns FIXED

Active Link Information

NS/2 definition:

Parameter	Information returned

link_name	Local logical link station

dlc_name	Data link control (DLC) name set to one of the following:

   ETHERAND

   IBMTRNET

   IBMPCNET

   SDLC

   TWINAX

   X25DLC

adapter_name	Adapter number for this link

fq_adj_cp_name	Fully qualified cp_name in adjacent node

adjacent_node_type	NN, EN, or LEN

cp_cp_session_support	Specifies whether the link supports CP-CP sessions

connection_type	HOST, PEER, or BOTH

tg_number	Transmission group number

effective_capacity	Highest bit rate transmission supported

cost_per_connect_time	Relative value of using link

cost_per_byte	Relative cost of transmitting byte over link

propagation_delay	Indicates amount of time for signal to travel length of link. Set to one of the following:

   MINIMUM

   LAN

   TELEPHONE

   PACKET_SWITCHED

   SATELLITE

   MAXIMUM

security	Set to one of the following:

   NONSECURE

   PUBLIC_SWITCHED_NETWORK

   UNDERGROUND_CABLE

   SECURE_CONDUIT

   GUARDED_CONDUIT

   ENCRYPTED

   GUARDED_RADIATION

user_defined_1	User-defined TG characteristics

user_defined_2	User-defined TG characteristics

user_defined_3	User-defined TG characteristics

SNA Server data returned:

Parameter	Information returned

link_name	Connection name

dlc_name	DLC name set to one of the following:

   IBMTRNET

   SDLC

   DFT

   X25DLC

adapter_name	Always set to 0

fq_adj_cp_name	Always set to EBCDIC spaces

adjacent_node_type	Always set to LEN

cp_cp_session_support	Always set to NO

connection_type	HOST or PEER from connection configuration

tg_number	Always returns 0

effective_capacity	Always set to 0

cost_per_connect_time	Always set to 0

cost_per_byte	Always set to 0

propagation_delay	Always set to MAXIMUM

security	Always set to NONSECURE

user_defined_1	Always set to 0

user_defined_2	Always set to 0

Always set to 0

LU 0 to 3 Information

IBM ES for OS/2 version 1.0 definition:

Parameter	Information returned

lu_dlc_name	DLC name set to one of the following:

   ETHERAND

   IBMTRNET

   IBMPCNET

   SDLC

   TWINAX

   X25DLC

lu_adapter_number	Adapter number for host link

link_id	Name of local logical link station being used

SNA Server data returned:

Parameter	Information returned

lu_dlc_name	DLC name set to one of the following:

   IBMTRNET

   SDLC

   DFT

   X25DLC

lu_adapter_number	Always set to 0

Name of connection

System Default Information

IBM ES for OS/2 version 1.0 definition:

Parameter	Information returned

default_mode_name	Mode name used for undefined mode name is sent or received

default_local_lu_name	Alias or local default LU

implicit_partner_lu_support	Indicates if implicit partner LU support is enabled

maximum_held_alerts	Number of alerts that will be held by NS/2 if there is no active link to a focal point

default_tp_conversation_security_rqd	Specifies if conversation security is used for default TPs

maximum_mc_ll_send_size	Maximum length of a logical record used on a Mapped conversation for sending data to either the inbound or outbound implicit remote LU

directory_for_inbound_attaches	Name of OS/2 directory used by Attach Manager

default_tp_operation	Set to one of the following:

   QUEUED_OPERATOR_STARTED

   QUEUED_OPERATOR_PRELOADED

   QUEUED_AM_STARTED

   NONQUEUED_AM_STARTED

default_tp_program_type	Set to one of the following:

   BACKGROUND

   FULL_SCREEN

   PRESENTATION_MANAGER

   VIO_WINDOWABLE

SNA Server data returned:

Parameter	Information returned

default_mode_name	Always set to NULL

default_local_lu_name	Always set to spaces

implicit_partner_lu_support	Always set to NO

maximum_held_alerts	Always set to 0

default_tp_conversation_security_rqd	Always set to NO

maximum_mc_ll_send_size	Always set to 16,384

directory_for_inbound_attaches	Always returned '*' and indicates that the current path should be used

default_tp_operation	Always set to QUEUED_AM_STARTED

Always set to FULL_SCREEN

LU 6.2 Definition Information

There are no differences for this information type.

Partner Definition Information

IBM ES for OS/2 version 1.0 definition:

Parameter	Information returned

maximum_mc_ll_send_size	Maximum length of a logical record used on a Mapped conversation for sending data to the partner LU

number_of_alternate_aliases	Specifies number of alternate aliases configured

SNA Server data returned:

Parameter	Information returned

maximum_mc_ll_send_size	Always set to 16,384

Always set to 0

Mode Definition Information

IBM ES for OS/2 version 1.0 definition:

Parameter	Information returned

cos_name	Name of class of service

SNA Server data returned:

Parameter	Information returned

 Set to EBCDIC spaces

Link Definition Information

IBM ES for OS/2 version 1.0 definition:

Parameter	Information returned

link_name	Local logical link station

fq_adj_cp_name	Fully qualified cp_name in adjacent node

adjacent_node_type	LEARN, LEN, or NN

preferred_nn_server	Adjacent NN should be the first node on which CP-CP sessions are established

dlc_name	DLC name set to one of the following:

   ETHERAND

   IBMTRNET

  IBMPCNET

   SDLC

   TWINAX

   X25DLC

adapter_number	Adapter number for this link

cp_cp_session_support	Specifies whether the link supports CP-CP sessions

connection_type	HOST, PEER, or BOTH

tg_number	Transmission group number

cost_per_connect_time	Relative value of using link

cost_per_byte	Relative cost of transmitting byte over link

init_self_support	Indicates that the node supports receiving INIT_SELF over this link

effective_capacity	Highest bit rate transmission supported

security	Set to one of the following:

   NONSECURE

   PUBLIC_SWITCHED_NETWORK

   UNDERGROUND_CABLE

   SECURE_CONDUIT

   GUARDED_CONDUIT

   ENCRYPTED

   GUARDED_RADIATION

propagation_delay	Indicates amount of time for signal to travel length of link. Set to one of the following:

   MINIMUM

   LAN

   TELEPHONE

   PACKET_SWITCHED

   SATELLITE

   MAXIMUM

user_defined_1	User-defined TG characteristics

user_defined_2	User-defined TG characteristics

user_defined_3	User-defined TG characteristics

SNA Server data returned:

Parameter	Information returned

link_name	Connection name

fq_adj_cp_name	Always set to EBCDIC spaces

adjacent_node_type	Always set to LEN

dlc_name	DLC name set to one of the following:

  IBMTRNET

   SDLC

   DFT

   X25DLC

adapter_number	Always set to 0

cp_cp_session_support	Always set to NO

connection_type	HOST or PEER from connection configuration

tg_number	Always returns 0

cost_per_connect_time	Always set to 0

cost_per_byte	Always set to 0

effective_capacity	Highest bit rate transmission supported

security	Always set to NONSECURE

propagation_delay	Always set to MAXIMUM

user_defined_1	Always set to 0

user_defined_2	Always set to 0

user_defined_3	Always set to 0

Return Codes

AP_OK

Primary return code; the verb executed successfully.

AP_PARAMETER_CHECK

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

DISPLAY_INVALID_CONSTANT

Secondary return code; the value supplied for NUM_SECTIONS or INIT_SEC_LEN is invalid.

AP_STATE_CHECK

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

AP_DISPLAY_INFO_EXCEEDS_LENGTH

Secondary return code; the returned DISPLAY information did not fit in the buffer.

AP_INVALID_DATA_SEGMENT

Secondary return code; the segment containing the data buffer is too small for the specified data length.

AP_COMM_SUBSYSTEM_ABENDED

Primary return code; indicates one of the following conditions:

The node used by this conversation has encountered an ABEND.

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

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

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

AP_INVALID_VERB_SEGMENT

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

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

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

Remarks

DISPLAY identifies an LU by alias alone. If the same local LU alias is used multiple times in a domain (for backup or other purposes) and that LU alias is specified through DISPLAY, the verb may flow to a different LU than the one intended.

The display verb requires a user-supplied buffer for the return of system information. If the buffer is not large enough, APPC returns the DISPLAY_INFO_EXCEEDS_LENGTH return code, along with the size actually needed at the time of the request (in the required_length parameter). One possible strategy for the use of this verb follows:

If the display_buffer_length value is less than the require_length value returned by APPC, and the required length is less than 64 kilobytes (K), then increase the size of the display buffer to equal or greater than the required_length value.

If the required_length value is greater than 64 K, you can choose to request each information section individually. Or, you can take the following steps:

1.	Process the information sections with complete information, whose total number displayed equals the total actual number.

2.	Choose a subset of the information sections you requested that contains incomplete information, and reissue the verb requesting those information sections.

3.	Repeat steps 1 and 2 as needed.

Note

If an individual information section is greater than 64 K, then you cannot get all of the requested information from APPC.


APPC TP Verbs
Chapter 4	1 of 4

APPC TP Verbs

This chapter describes the APPC TP verbs:

GET_TP_PROPERTIES

TP_ENDED

TP_STARTED

The description of the verbs provides:

A definition of the verb.

The structure defining the VCB used by the verb. The structure is contained in the WINAPPC.H file. The length of each VCB field is in bytes. Fields beginning with reserv, for example, reserv2, are reserved.

The parameters (VCB fields) supplied to and returned by APPC. For each parameter, the following information is provided:

Description

Possible values

Additional information

The conversation state(s) in which the verb can be issued.

The state(s) to which the conversation can change upon return from the verb. Conditions that do not cause a state change are not noted. For example, parameter checks and state checks do not cause a state change.

Additional information describing the use of the verb.

Most parameters supplied to and returned by APPC are hexadecimal values. To simplify coding, these values are represented by meaningful symbolic constants, which are established by #define statements in the WINAPPC.H header file. For example, the opcode (operation code) parameter of MC_SEND_DATA is the hexadecimal value represented by the symbolic constant AP_M_SEND_DATA. Use only the symbolic constants when writing TPs.


GET_TP_PROPERTIES
APPC TP Verbs	2 of 4

GET_TP_PROPERTIES

Returns attributes of the TP and the current transaction.

Syntax

opcode	unsigned short int
opext (reserved)	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
tp_name	unsigned char [64]
lu_alias	unsigned char [8]
LUW_ID_OVERLAY	structured as:
fq_length	unsigned char
fq_luw_name	unsigned char [17]
instance	unsigned char [6]
sequence	unsigned char [2]
fqlu_name	unsigned char [17]
reserve3	unsigned char [10]
user_id	unsigned char [10]
Parameter		Description
opcode		Supplied parameter; AP_GET_TP_PROPERTIES.
tp_id		Supplied parameter; identifies the local TP. The value of this parameter was returned by TP_STARTED in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
tp_name		Returned parameter; supplies the TP name of the TP that issued the verb. The name is returned as a 64-byte EBCDIC string, padded on the right with EBCDIC spaces, if necessary.
lu_alias		Returned parameter; supplies the alias name assigned to the local LU. It is returned as an 8-byte ASCII string padded on the right with ASCII spaces.
luw_id		Returned parameter; supplies the logical unit-of-work identifier for the transaction in which the TP is participating. Several TPs may be involved in a transaction. This ID, which is assigned on behalf of the TP initiating the transaction allows the conversation that makes up the transaction to be logically connected. The luw_id is a structure with the following fields: fq_length, a one-byte length of the fully qualified LU name for the LU of the originating TP.
luw_id		fq_luw_name, the fully qualified name of the LU for the originating TP. The name is returned as a 17-byte EBCDIC string, comprising the NETID, a period, and the LU name. If the length of the name is fewer than 17 bytes, the instance and sequence numbers follow immediately (note that because of this, you should not use the fields of the structure LUW_ID_OVERLAY to access those values. These are provided for compatibility only).
		instance, a 6-byte string uniquely generated by the LU for the originating TP. sequence, a 2-byte number that indicates the segment of unit-of-work. (This is always set to 1, as sync-point is not supported.) If the luw_id length is fewer than 26 bytes, it is padded on the right with EBCDIC spaces.
fqlu_name		Returned parameter; supplies the fully qualified name of the local LU. The name is returned as a 17-byte EBCDIC string, comprising the NETID, a period, and the LU name. The name is padded on the right with EBCDIC spaces, if necessary.
user_id		Returned parameter; supplies the user_id supplied by the initiating TP in the allocation request. The name is returned as a 10-byte EBCDIC string, padded on the right with EBCDIC spaces, if necessary.
Return Codes

AP_OK

Primary return code; the verb executed successfully.

AP_PARAMETER_CHECK

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

AP_BAD_TP_ID

Secondary return code; the value of tp_id did not match a TP identifier assigned by APPC.

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

The system administrator should examine the error log to determine the reason for the ABEND.

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

When this return code is used with [MC_]ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there isn’t a node available that can satisfy the [MC_]ALLOCATE request.

When [MC_]ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:

X'F0000001'

Secondary return code; no nodes have been started.

X'F0000002'

Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:

The node with the local LU is not started.

The local LU is not configured.

AP_INVALID_VERB_SEGMENT

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

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

AP_TP_BUSY

Primary return code; the local TP has issued a call to APPC while APPC was processing another call for the same TP. This may occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same tp_id.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

Remarks

This verb relates to the TP rather than a specification conversation, so the TP can issue the verb in any state. There is no state change.

The luw_id parameter contains fields for fq_length (the length of the fully qualified LU name of the LU originating the TP), fq_luw_name (the fully qualified name of the LU originating the TP), instance (generated uniquely by the LU originating the TP), and sequence (always set to 1 and indicating the segment of unit-of-work).


TP_ENDED
APPC TP Verbs	3 of 4

TP_ENDED

Issued by both the invoking and invoked TP, TP_ENDED notifies APPC that the TP is ending.

For the Windows version 3.x system, Microsoft recommends that you use the WinAsyncAPPC rather than the blocking version of these calls. For more information on using the Windows extension, see Chapter 6, “APPC Extensions for the Windows Environment.”

Syntax

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
type	unsigned char
Parameter		Description
opcode		Supplied parameter; AP_TP_ENDED.
tp_id		Supplied parameter; identifies the local TP. The value of this parameter was returned by TP_STARTED for the invoking TP or by RECEIVE_ALLOCATE for the invoked TP.
type		Supplied parameter; provides the type of termination to be performed. The following are allowed values: AP_HARD indicates that all active verbs for the TP are terminated; the session(s) being used by the conversation(s) are ended. Both the local TP and the partner TP may receive conversation failure return codes (AP_DEALLOC_ABEND for Mapped conversations and AP_DEALLOC_ABEND_PROG for Basic conversations). AP_SOFT indicates that the TP waits for all active verbs to complete; the session being used by the conversation remains active.
Return Codes

AP_OK

Primary return code; the verb executed successfully.

AP_PARAMETER_CHECK

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

AP_BAD_TP_ID

Secondary return code; APPC did not recognize the tp_id as an assigned TP identifier.

AP_BAD_TYPE

Secondary return code; the specified end_type value was not recognized by APPC.

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

The system administrator should examine the error log to determine the reason for the ABEND.

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

AP_INVALID_VERB_SEGMENT

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

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

AP_TP_BUSY

Primary return code; the local TP has issued a call to APPC while APPC was processing another call for the same TP. This may occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same tp_id.

AP_THREAD_BLOCKING

Primary return code; the calling thread is already in a blocking call.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

Remarks

In response to TP_ENDED, APPC frees the resources used by the TP. After this verb executes, the TP identifier is no longer valid; the TP cannot issue any more APPC conversation verbs.

The conversation can be in any state when the TP issues this verb.

If the conversation is in SEND state, TP_ENDED performs the function of [MC_]DEALLOCATE with dealloc_type set to AP_FLUSH.

If the conversation is in a state other than RESET or SEND, TP_ENDED per-forms the function of [MC_]DEALLOCATE with dealloc_type set to AP_ABEND (for a Mapped conversation) or AP_ABEND_PROG (for a Basic conversation).

After successful execution (primary_rc is AP_OK), there is no APPC state.


TP_STARTED
APPC TP Verbs	4 of 4

TP_STARTED

Issued by the invoking TP, TP_STARTED notifies APPC that the TP is starting.

For the Windows version 3.x system, Microsoft recommends that you use WinAsyncAPPC rather than the blocking version of these calls. For more information on using the Windows extension, see Chapter 6, “APPC Extensions for the Windows Environment.”

Syntax

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
lu_alias	unsigned char [8]
tp_id	unsigned char [8]
tp_name	unsigned char [64]
Parameter		Description
opcode		Supplied parameter; AP_TP_STARTED.
lu_alias		Supplied parameter; provides the alias by which the local LU is known to the local TP. The name must match an LU alias established during configuration. APPC checks the LU alias against the current SNA Server configuration file. Due to the client-server architecture used by SNA Server, however, this parameter is not validated until an ALLOCATE is performed. Refer to [MC_]ALLOCATE in Chapter 5 for more information. This parameter is an 8-byte ASCII character string. It can consist of characters from the type G ASCII character set: Uppercase letters Numerals from 0 through 9 Spaces Special characters $, #, % and @ The first character of this string cannot be a space. If the value of this parameter is fewer than eight bytes, pad it on the right with ASCII space (X'20'). To use an LU from the default LU pool, set this field to eight hexadecimal zeros. For more information, see “Default LUs” later in this section.
tp_id		Returned parameter; identifies the newly established TP.
tp_name		Supplied parameter; specifies the name of the local TP. Under the SNA Server implementation of APPC, this parameter is ignored when issued by TP_STARTED. However, this parameter is required if the program runs under the IBM ES for OS/2 version 1.0 implementation of APPC.
		This parameter is a 64-byte EBCDIC character string and is case sensitive. The tp_name parameter can consist of characters from the type AE EBCDIC character set: Uppercase and lowercase letters Numerals from 0 through 9 Special characters $, #, @, and period (.) If the TP name is fewer than 64 bytes, use EBCDIC spaces (X'40') to pad it on the right. The SNA convention for naming a service TP is up to four characters. The first character is a hexadecimal byte between X'00' and X'3F'.
Return Codes

AP_OK

Primary return code; the verb executed successfully.

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

The system administrator should examine the error log to determine the reason for the ABEND.

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

When this return code is used with [MC_]ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there isn’t a node available that can satisfy the [MC_]ALLOCATE request.

When [MC_]ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:

X'F0000001'

Secondary return code; no nodes have been started.

X'F0000002'

Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:

The node with the local LU is not started.

The local LU is not configured.

AP_INVALID_VERB_SEGMENT

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

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

AP_TP_BUSY

Primary return code; the local TP has issued a call to APPC while APPC was processing another call for the same TP.

AP_THREAD_BLOCKING

Primary return code; the calling thread is already in a blocking call.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

Remarks

In response to TP_STARTED, APPC generates a TP identifier for the invoking TP. This identifier is a required parameter for subsequent APPC verbs issued by the invoking TP.

This must be the first APPC verb issued by the invoking TP. Consequently, no prior APPC state exists.

If the verb executes successfully (primary_rc is AP_OK), the state changes to RESET.

Default LUs

Any LU can be configured to be in a pool of default local LUs available for use by invoking TPs.

For a user or group who will be using TPs, 5250 emulators, and/or APPC applications, you can assign a default local APPC LU and a default remote APPC LU. If the invoking TP specifies the LU alias that it uses (in TP_STARTED), that LU alias must match a local APPC LU alias on the supporting SNA server. If the invoking TP leaves the LU alias blank in TP_STARTED, one of two methods for designating a default LU must be carried out on the supporting SNA server. One method is to assign a default local APPC LU to the user or group that starts the invoking TP (that is, the user or group logged on at the system from which TP_STARTED is issued). The other method is to designate one or more LUs as members of the default outgoing local APPC LU pool. SNA Server first attempts to determine the default local APPC LU of the associated user or group, then attempts to assign an available LU from the default outgoing local APPC LU pool; if these attempts fail, SNA Server rejects the request.

In AS/400 environments, the ability to assign default APPC LUs to users or groups is especially useful because it gives the administrator centralized control over these LU assignments. In such environments, for each user or group, assign both a default local APPC LU and a default remote APPC LU. Assigning a default local APPC LU for each user fulfills the normal AS/400 procedure of assigning local LUs on a per-user basis. Assigning a default remote APPC LU is equivalent to assigning a default AS/400 for the user to connect to, since the remote LU designates the AS/400. By making these assignments, the administrator can centrally control the default AS/400 that a 5250 emulator user connects to.

For more information, see the Microsoft SNA Server Administration Guide.


APPC Conversation Verbs
Chapter 5	1 of 18

APPC Conversation Verbs

This chapter describes the APPC conversation verbs and provides:

A definition of the verb.

The structure defining the VCB used by the verb. The structure is contained in the WINAPPC.H file. The length of each VCB field is in bytes. Fields beginning with reserv, for example, reserv2, are reserved.

The parameters (VCB fields) supplied to and returned by APPC. For each parameter, the following information is provided:

Description

Possible values

Additional information

The conversation state(s) in which the verb can be issued.

The state(s) to which the conversation can change upon return from the verb. Conditions that do not cause a state change are not noted. For example, parameter checks and state checks do not cause a state change.

Additional information describing the use of the verb.

Mapped and Basic conversation verbs are listed together in this chapter as a single entry. Mapped conversation verbs are preceded by an MC_ designator. For example, you will find both the Mapped conversation verb MC_ALLOCATE and the Basic conversation verb ALLOCATE listed together under the entry [MC_]ALLOCATE.

Most parameters supplied to and returned by APPC are hexadecimal values. To simplify coding, these values are represented by meaningful symbolic constants, which are established by #define statements in the WINAPPC.H header file. For example, the opcode (operation code) parameter of MC_SEND_DATA is the hexadecimal value represented by the symbolic constant AP_M_SEND_DATA. Use only the symbolic constants when writing TPs.


[MC_]ALLOCATE
APPC Conversation Verbs	2 of 18

[MC_]ALLOCATE

Issued by the invoking TP, this verb allocates a session between the local LU and partner LU and (in conjunction with RECEIVE_ALLOCATE) establishes a conversation between the invoking TP and the invoked TP. After this verb executes successfully, APPC generates a conversation identifier (conv_id). The conv_id is a required parameter for all other APPC conversation verbs.

For the Windows version 3.x system, Microsoft recommends that you use WinAsyncAPPC rather than the blocking version of these calls. For more information on using the Windows extension, see Chapter 6, "APPC Extensions for the Windows Environment."

Syntax

For a Mapped conversation:

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
reserv3	unsigned char
sync_level	unsigned char
reserv4	unsigned char [2]
rtn_ctl	unsigned char
reserv4a	unsigned char
conv_group_id	unsigned long int
sense_data	unsigned long int
plu_alias	unsigned char [8]
mode_name	unsigned char [8]
tp_name	unsigned char [64]
security	unsigned char
reserv6	unsigned char [11]
pwd	unsigned char [10]
user_id	unsigned char [10]
pip_dlen	unsigned short int
pip_dptr	unsigned char far *
reserv6a	unsigned char
fqplu_name	unsigned char [17]
reserv7	unsigned char [8]
For a Basic conversation:

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
conv_type	unsigned char
sync_level	unsigned char
reserv3	unsigned char [2]
rtn_ctl	unsigned char
reserv3a	unsigned char
conv_group_id	unsigned long int
sense_data	unsigned long int
plu_alias	unsigned char [8]
mode_name	unsigned char [8]
tp_name	unsigned char [64]
security	unsigned char
reserv5	unsigned char [11]
pwd	unsigned char [10]
user_id	unsigned char [10]
pip_dlen	unsigned short int
pip_dptr	unsigned char far *
reserv5a	unsigned char
fqplu_name	unsigned char [17]
reserv6	unsigned char [8]
Parameter		Description
opcode		Supplied parameter; allowed values include AP_M_ALLOCATE for MC_ALLOCATE and AP_B_ALLOCATE for ALLOCATE.
opext		Supplied parameter; allowed values include AP_MAPPED_CONVERSATION for MC_ALLOCATE and AP_BASIC_CONVERSATION for ALLOCATE.
tp_id		Supplied parameter; identifies the local TP. The value of this parameter was returned by TP_STARTED.
conv_id		Returned parameter; identifies the conversation established between the two TPs.
conv_type		Supplied parameter; used only by ALLOCATE to specify the type of conversation to allocate and is either AP_BASIC _CONVERSATION or AP_MAPPED_CONVERSATION. If ALLOCATE establishes a Mapped conversation, the local TP must issue Basic-conversation verbs and provide its own mapping layer to convert data records to logical records and logical records to data records. The partner TP may issue Basic-conversation verbs and provide the mapping layer, or it may use Mapped-conversation verbs (if the partner TP is using an implementation of APPC that supports Mapped-conversation verbs). For more information, see your IBM SNA manual(s).
sync_level		Supplied parameter; specifies the synchronization level of the conversation. It determines whether the TPs can request confirmation of receipt of data and confirm receipt of data. Use AP_CONFIRM_SYNC_LEVEL to specify that the TPs can use confirmation processing in this conversation. Use AP_NONE to specify that confirmation processing will not be used in this conversation.
rtn_ctl		Supplied parameter; specifies when the local LU, acting on a session request from the local TP, should return control to the local TP. For information about sessions, see Chapter 2, "Transaction Programs." Use AP_IMMEDIATE to specify that the LU allocates a contention-winner session, if one is immediately available, and returns control to the TP. Use AP_WHEN_SESSION_ALLOCATED to specify that the LU does not return control to the TP until it allocates a session or encounters one of the errors documented in "Returns" later in this section. (If the session limit is 0, the LU returns control immediately.) If a session is not available, the TP waits for one. Use AP_WHEN_SESSION_FREE to specify that the LU allocates a contention-winner or contention-loser session, if one is available or able to be activated, and returns control to the TP. If an error occurs, (as documented in "Returns" later in this section) the call will return immediately with the error in the primary_rc and secondary_rc fields.
		Use AP_WHEN_CONWINNER_ALLOC to specify that the LU does not return control until it allocates a contention-winner session or encounters one of the errors documented in "Returns" later in this section. (If the session limit is 0, the LU returns control immediately.) If a session is not available, the TP waits for one.
rtn_ctl		Use AP_WHEN_CONV_GROUP_ALLOC to specify that the LU does not return control to the TP until it allocates the session specified by conversation_group_id or encounters one of the errors documented in "Returns" later in this section. If a session is not available, the TP waits for it to become free. Note that AP_IMMEDIATE is the only value for rtn_ctl that will never cause a new session to start. For values other than AP_IMMEDIATE, if an appropriate session is not immediately available, SNA Server will try to start one. This will cause the ondemand connection to be activated.
conv_group_id		Supplied/returned parameter, specifies the ID of the conversation group from which the session should be allocated. The conv_group _id is required only if rtn_ctl is set to WHEN_CONV_GROUP _ALLOC. When rtn_ctl specifies a different value and the return_code is AP_OK, this is a returned value.
sense_data		Returned parameter; indicates an allocation error (retry or no-retry).
plu_alias		Supplied parameter; specifies the alias by which the partner LU is known to the local TP. The plu_alias must match the name of a partner LU established during configuration. The parameter is an 8-byte ASCII character string. It can consist of characters from the type G ASCII character set: Uppercase letters Numerals 0 through 9 Spaces Special characters $, #, %, and @ The first character of this string cannot be a space. If the value of this parameter is fewer than eight bytes, pad it on the right with ASCII spaces (X'20'). If you want to specify the partner LU with the fqplu_name parameter, fill this parameter with binary zeroes. For a user or group using TPs, 5250 emulators, and/or APPC applications, the system administrator can assign default local and remote LUs. In this case, the field is left blank or null and the default LUs are accessed when the user or group member starts an APPC program. For more information on default LUs, see the Microsoft SNA Server Administration Guide.
mode_name		Supplied parameter; specifies the name of a set of networking characteristics defined during configuration. The value of mode_name must match the name of a mode associated with the partner LU during configuration. The parameter is an 8-byte EBCDIC character string. It can consist of characters from the type A EBCDIC character set: Uppercase letters Numerals 0 through 9 Special characters $, #, and @
		The first character in the string must be an uppercase letter or a special character. Do not use SNASVCMG in a Mapped conversation. SNASVCMG is a reserved mode_name used internally by APPC. Using this name in a Basic conversation is not recommended.
tp_name		Supplied parameter; specifies the name of the invoked TP. The value of tp_name specified by [MC_]ALLOCATE in the invoking TP must match the value of tp_name specified by RECEIVE_ALLOCATE in the invoked TP. The parameter is a 64-byte EBCDIC character string and is case sensitive. The tp_name parameter can consist of characters from the type AE EBCDIC character set: Uppercase and lowercase letters Numerals 0 through 9 Special characters $, #, @, and period (.) If tp_name is fewer than 64 bytes, use EBCDIC spaces (X'40') to pad it on the right. The SNA convention for naming a service TP is up to four characters. The first character is a hexadecimal byte between X'00' and X'3F'. The other characters are from the type AE EBCDIC character set.
security		Supplied parameter; provides the information that the partner LU requires to validate access to the invoked TP. Based on the conversation security established for the invoked TP during configuration, use one of the following values: AP_NONE for an invoked TP that uses no conversation security. AP_PGM for an invoked TP that uses conversation security and thus requires a user ID and password. Supply this information through the user_id and pwd parameters.
security		AP_SAME for a TP that has been invoked with a valid user ID and password, which in turn invokes another TP. For example, assume that TP A invokes TP B with a valid user ID and password, and TP B in turn invokes TP C. If TP B specifies the value AP_SAME, APPC will send the LU for TP C the user ID from TP A and an already-verified indicator. This indicator tells TP C to not require the password (if TP C is configured to accept an already-verified indicator).
pwd		Supplied parameter; provides the password associated with user_id. The pwd parameter is required only if security is set to AP_PGM. It must match the password for user_id that was established during configuration.
		The pwd parameter is a 10-byte EBCDIC character string and is case sensitive. It can consist of characters from the type AE EBCDIC character set: Uppercase and lowercase letters Numerals 0 through 9 Special characters $, #, @, and period (.) If the password is fewer than 10 bytes, use EBCDIC spaces (X'40') to pad it on the right.
user_id		Supplied parameter; provides the user ID required to access the partner TP. It is required only if the security parameter is set to AP_PGM. The user_id parameter is a 10-byte EBCDIC character string and is case sensitive. It must match one of the user IDs configured for the partner TP. The parameter can consist of characters from the type AE EBCDIC character set: Uppercase and lowercase letters Numerals 0 through 9 Special characters $, #, @, and period (.) If user_id is fewer than 10 bytes, use EBCDIC spaces (X'40') to pad it on the right.
pip_dlen		Supplied parameter; specifies the length of the program initialization parameters (PIP) to be passed to the partner TP. The range is from 0 through 32,767.
pip_dptr		Supplied parameter; specifies the address of the buffer containing PIP data. Use this parameter only if pip_dlen is greater than 0. PIP data can consist of initialization parameters or environmental setup information required by a partner TP or remote operating system. The PIP data must follow the GDS format. For more information, see your IBM SNA manual(s). For Windows NT and Windows, the data buffer can reside in a static data area or in a globally allocated area. The data buffer must fit entirely within this area. For OS/2, the PIP data buffer must reside on an unnamed, shared segment, which is allocated by the function DosAllocSeg with Flags equal to 1. The PIP data buffer must fit entirely on the segment.
fqplu_name		Supplied parameter; specifies the fully qualified name of the partner LU. This must match the fully qualified name of the local LU defined in the remote node. The parameter consists of two type A EBCDIC character strings for the NETID and the LU name of the partner LU. The names are separated by an EBCDIC period ('.'). The NETID may be omitted. If this is the case, omit the period as well. This name must be provided if no plu_alias is specified. It can consist of characters from the type A EBCDIC character set: Uppercase letters Numerals 0 through 9 Special characters $, #, and @ If the value of this parameter is fewer than 17 bytes, pad it on the right with EBCDIC spaces (X'40').
Return Codes

AP_OK

Primary return code; the verb executed successfully.

AP_UNSUCCESSFUL

Primary return code; the supplied parameter rtn_ctl specified immediate (AP_IMMEDIATE) return of control to the TP, and the local LU did not have an available contention-winner session.

AP_PARAMETER_CHECK

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

AP_BAD_RETURN_CONTROL

Secondary return code; the value specified for rtn_ctl was invalid.

AP_BAD_SECURITY

Secondary return code; the value specified for security was invalid.

AP_BAD_SYNC_LEVEL

Secondary return code; the value specified for sync_level was invalid.

AP_BAD_TP_ID

Secondary return code; the value specified for tp_id was invalid.

AP_PIP_LEN_INCORRECT

Secondary return code; the value of pip_dlen was greater than 32,767.

AP_UNKNOWN_PARTNER_MODE

The value specified for mode_name was invalid.

AP_BAD_PARTNER_LU_ALIAS

APPC did not recognize the supplied partner_lu_alias.

AP_BAD_CONV_TYPE (for a Basic conversation)

Secondary return code; the value specified for conv_type was invalid.

AP_NO_USE_OF_SNASVCMG (for a Mapped conversation)

Secondary return code; SNASVCMG is not a valid value for mode_name.

AP_INVALID_DATA_SEGMENT

Secondary return code; the PIP data was longer than the allocated data segment, or the address of the PIP data buffer was wrong.

AP_ALLOCATION_ERROR

Primary return code; APPC has failed to allocate a conversation. The conversation state is set to RESET.

This code may be returned through a verb issued after [MC_]ALLOCATE.

AP_ALLOCATION_FAILURE_NO_RETRY

Secondary return code; the conversation cannot be allocated because of a permanent condition, such as a configuration error or session protocol error. To determine the error, the system administrator should examine the error log file. Do not retry the allocation until the error has been corrected.

AP_ALLOCATION_FAILURE_RETRY

Secondary return code; the conversation could not be allocated because of a temporary condition, such as a link failure. The reason for the failure is logged in the system error log. Retry the allocation.

AP_COMM_SUBSYSTEM_ABENDED

Primary return code; this 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.

The system administrator should examine the error log to determine the reason for the ABEND.

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

When this return code is used with [MC_]ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there isn't a node available that can satisfy the [MC_]ALLOCATE request.

When [MC_]ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:

X'F0000001'

Secondary return code; no nodes have been started.

X'F0000002'

Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:

The node with the local LU is not started.

The local LU is not configured.

AP_INVALID_VERB_SEGMENT

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

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

AP_CONV_BUSY

Primary return code; there can only be one outstanding conversation verb at a time on any conversation. This may occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same conv_id.

AP_THREAD_BLOCKING

Primary return code; the calling thread is already in a blocking call.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

Remarks

MC_ALLOCATE establishes a Mapped conversation. ALLOCATE can establish either a Basic or Mapped conversation.

The conversation state is RESET when the TP issues this verb. After successful execution, (primary_rc is AP_OK), the state changes to SEND. If the verb does not execute, the state remains unchanged.

Several parameters of [MC_]ALLOCATE are EBCDIC or ASCII strings. A TP can use the CSV CONVERT to translate a string from one character set to the other.

To send the [MC_]ALLOCATE request immediately, the invoking TP can issue [MC_]FLUSH or [MC_]CONFIRM immediately after [MC_]ALLOCATE. Otherwise, the [MC_]ALLOCATE request accumulates with other data in the local LU's send buffer until the buffer is full.

By issuing [MC_]CONFIRM after [MC_]ALLOCATE, the invoking TP can immediately determine whether the allocation was successful (if sync_level is set to AP_CONFIRM_SYNC_LEVEL).

Normally, the value of the [MC_]ALLOCATE mode_name parameter must match the name of a mode configured for the invoked TP's node and associated during configuration with the partner LU.

If one of the modes associated with the partner LU on the invoked TP's node is an implicit mode, the session established between the two LUs will be of the implicit mode when no mode name associated with the partner LU matches the value of mode_name.


[MC_]CONFIRM
APPC Conversation Verbs	3 of 18

[MC_]CONFIRM

Sends the contents of the local LU's send buffer and a confirmation request to the partner TP.

For the Windows version 3.x system, Microsoft recommends that you use WinAsyncAPPC rather than the blocking version of these calls. For more information on using the Windows extension, see Chapter 6, "APPC Extensions for the Windows Environment."

Syntax

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
rts_rcvd	unsigned char
Parameter		Description
opcode		Supplied parameter; allowed values include AP_M_CONFIRM for MC_CONFIRM and AP_B_CONFIRM for CONFIRM.
opext		Supplied parameter; allowed values include AP_MAPPED _CONVERSATION for MC_CONFIRM and AP_BASIC _CONVERSATION for CONFIRM.
tp_id		Supplied parameter; identifies the local TP. The value of this parameter was returned by TP_STARTED in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
conv_id		Supplied parameter; specifies the conversation identifier. The value of this parameter was returned by [MC_]ALLOCATE in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
rts_rcvd		Returned parameter; indicates whether the partner TP issued [MC_]REQUEST_TO_SEND, which requests the local TP to change the conversation to RECEIVE state. To change to RECEIVE state for the Windows NT operating system, the local TP can use [MC_]PREPARE_TO_RECEIVE, [MC_]RECEIVE_AND _WAIT, or [MC_]RECEIVE_AND_POST. For the Windows graphical environment, the local TP can use [MC_]PREPARE_TO _RECEIVE or [MC_]RECEIVE_AND_WAIT. For the OS/2 operating system, the local TP can use [MC_]RECEIVE_AND_POST.
Return Codes

AP_OK

Primary return code; the verb executed successfully.

AP_PARAMETER_CHECK

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

AP_BAD_CONV_ID

Secondary return code; the value of conv_id did not match a conversation identifier assigned by APPC.

AP_BAD_TP_ID

Secondary return code; the value of tp_id did not match a TP identifier assigned by APPC.

AP_CONFIRM_ON_SYNC_LEVEL_NONE

Secondary return code; the local TP attempted to use [MC_]CONFIRM in a conversation with a synchronization level of AP_NONE. The synchronization level, established by [MC_]ALLOCATE, must be AP_CONFIRM_SYNC_LEVEL.

AP_STATE_CHECK

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

AP_CONFIRM_BAD_STATE

Secondary return code; the conversation was not in SEND state.

AP_CONFIRM_NOT_LL_BDY

Secondary return code; the conversation for the local TP was in SEND state, and the local TP did not finish sending a logical record.

AP_ALLOCATION_ERROR

Primary return code; APPC has failed to allocate a conversation. The conversation state is set to RESET.

This code may be returned through a verb issued after [MC_]ALLOCATE.

The associated secondary return codes are as follows:

AP_ALLOCATION_FAILURE_NO_RETRY

Secondary return code; the conversation cannot be allocated because of a permanent condition, such as a configuration error or session protocol error. To determine the error, the system administrator should examine the error log file. Do not retry the allocation until the error has been corrected.

AP_ALLOCATION_FAILURE_RETRY

Secondary return code; the conversation could not be allocated because of a temporary condition, such as a link failure. The reason for the failure is logged in the system error log. Retry the allocation.

AP_CONVERSATION_TYPE_MISMATCH

Secondary return code; the partner LU or TP does not support the conversation type (Basic or Mapped) specified in the allocation request.

AP_PIP_NOT_ALLOWED

Secondary return code; the allocation request specified PIP data, but either the partner TP does not require this data, or the partner LU does not support it.

AP_PIP_NOT_SPECIFIED_CORRECTLY

Secondary return code; the partner TP requires PIP data, but the allocation request specified either no PIP data or an incorrect number of parameters.

AP_SECURITY_NOT_VALID

Secondary return code; the user ID or password specified in the allocation request was not accepted by the partner LU.

AP_SYNC_LEVEL_NOT_SUPPORTED

Secondary return code; the partner TP does not support the sync_level (AP_NONE or AP_CONFIRM_SYNC_LEVEL) specified in the allocation request, or the sync_level was not recognized.

AP_TP_NAME_NOT_RECOGNIZED

Secondary return code; the partner LU does not recognize the TP name specified in the allocation request.

AP_TRANS_PGM_NOT_AVAIL_NO_RETRY

Secondary return code; the remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition is permanent. The reason for the error may be logged on the remote node. Do not retry the allocation until the error has been corrected.

AP_TRANS_PGM_NOT_AVAIL_RETRY

Secondary return code; the remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition may be temporary, such as a time-out. The reason for the error may be logged on the remote node. Retry the allocation.

AP_COMM_SUBSYSTEM_ABENDED

Primary return code; this 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 has encountered an ABEND.

The system administrator should examine the error log to determine the reason for the ABEND.

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

When this return code is used with [MC_]ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there isn't a node available that can satisfy the [MC_]ALLOCATE request.

When [MC_]ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:

X'F0000001'

Secondary return code; no nodes have been started.

X'F0000002'

Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:

The node with the local LU is not started.

The local LU is not configured.

AP_CONV_FAILURE_NO_RETRY

Primary return code; the conversation was terminated because of a permanent condition, such as a session protocol error. The system administrator should examine the system error log to determine the cause of the error. Do not retry the conversation until the error has been corrected.

AP_CONV_FAILURE_RETRY

Primary return code; the conversation was terminated because of a temporary error. Restart the TP to see if the problem occurs again. If it does, the system administrator should examine the error log to determine the cause of the error.

AP_CONVERSATION_TYPE_MIXED

Primary return code; the TP has issued both Basic and Mapped conversation verbs. Only one type can be issued in a single conversation.

AP_INVALID_VERB_SEGMENT

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

AP_PROG_ERROR_PURGING

Primary return code; while in RECEIVE, PENDING, PENDING_POST (Windows NT and OS/2 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state, the partner TP issued one of the following verbs:

SEND_ERROR with err_type set to AP_PROG

MC_SEND_ERROR

Data sent but not yet received is purged.

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

AP_CONV_BUSY

Primary return code; there can only be one outstanding conversation verb at a time on any conversation. This may occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same conv_id.

AP_THREAD_BLOCKING

Primary return code; the calling thread is already in a blocking call.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

AP_DEALLOC_ABEND (for a Mapped conversation)

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner TP issued MC_DEALLOCATE with dealloc_type set to AP_ABEND.

The partner TP encountered an ABEND, causing the partner LU to send an MC_DEALLOCATE request.

AP_DEALLOC_ABEND_PROG (for a Basic conversation)

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_PROG.

The partner TP has encountered an ABEND, causing the partner LU to send a DEALLOCATE request.

AP_DEALLOC_ABEND_SVC (for a Basic conversation)

Primary return code; the conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_SVC.

AP_DEALLOC_ABEND_TIMER (for a Basic conversation)

Primary return code; the conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_TIMER.

AP_SVC_ERROR_PURGING (for a Basic conversation)

Primary return code; the partner TP (or partner LU) issued SEND_ERROR with err_type set to AP_SVC while in RECEIVE, PENDING_POST (Windows NT and OS/2 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state. Data sent to the partner TP may have been purged.

Remarks

In response to [MC_]CONFIRM, the partner TP normally issues [MC_]CONFIRMED to confirm that it has received the data without error. (If the partner TP encounters an error, it issues [MC_]SEND_ERROR or abnormally deallocates the conversation.)

The TP can issue [MC_]CONFIRM only if the conversation's synchronization level, established by [MC_]ALLOCATE, is AP_CONFIRM_SYNC_LEVEL.

The conversation must be in SEND state when the TP issues this verb. State changes, summarized in the following table, are based on the value of the primary_rc.

primary_rc	New state
AP_OK	NO CHANGE
AP_ALLOCATION_ERROR	RESET
AP_COMM_SUBSYSTEM_ABENDED	RESET
AP_COMM_SUBSYSTEM_NOT_LOADED	RESET
AP_CONV_FAILURE_RETRY	RESET
AP_CONV_FAILURE_NO_RETRY	RESET
AP_DEALLOC_ABEND	RESET
AP_DEALLOC_ABEND_PROG	RESET
AP_DEALLOC_ABEND_SVC	RESET
AP_DEALLOC_ABEND_TIMER	RESET
AP_PROG_ERROR_PURGING	RECEIVE
AP_SVC_ERROR_PURGING	RECEIVE
[MC_]CONFIRM waits for a response from the partner TP. A response is generated by one of the following verbs in the partner TP:

[MC_]CONFIRMED

[MC_]SEND_ERROR

MC_DEALLOCATE with dealloc_type set to AP_ABEND

DEALLOCATE with dealloc_type set to AP_ABEND_PROG, AP_ABEND_SVC, or AP_ABEND_TIMER

TP_ENDED

By issuing [MC_]CONFIRM after [MC_]ALLOCATE, the invoking TP can immediately determine whether the allocation was successful (if sync_level is set to AP_CONFIRM_SYNC_LEVEL).

Normally, the value of the [MC_]ALLOCATE mode_name parameter must match the name of a mode configured for the invoked TP's node and associated during configuration with the partner LU.

If one of the modes associated with the partner LU on the invoked TP's node is an implicit mode, the session established between the two LUs will be of the implicit mode when no mode name associated with the partner LU matches the value of mode_name. For more information, see the Microsoft SNA Server Administration Guide.

Several parameters of [MC_]ALLOCATE are EBCDIC or ASCII strings. A TP can use the CSV CONVERT to translate a string from one character set to the other. For more information, see Chapter 8, "Common Service Verbs."

To send the [MC_]ALLOCATE request immediately, the invoking TP can issue [MC_]FLUSH or [MC_]CONFIRM immediately after [MC_]ALLOCATE. Otherwise, the [MC_]ALLOCATE request accumulates with other data in the local LU's send buffer until the buffer is full.


[MC_]CONFIRMED
APPC Conversation Verbs	4 of 18

[MC_]CONFIRMED

Responds to a confirmation request from the partner TP. It informs the partner TP that the local TP has not detected an error in the received data. Because the TP issuing the confirmation request waits for a confirmation, [MC_]CONFIRMED synchronizes the processing of the two TPs.

For the Windows version 3.x system, Microsoft recommends that you use WinAsyncAPPC rather than the blocking version of these calls. For more information on using the Windows extension, see Chapter 6, "APPC Extensions for the Windows Environment."

Syntax

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
Parameter		Description
opcode		Supplied parameter; allowed values include AP_M_CONFIRMED for MC_CONFIRMED and AP_B_CONFIRMED for CONFIRMED.
opext		Supplied parameter; allowed values include AP_MAPPED _CONVERSATION for MC_CONFIRMED and AP_BASIC _CONVERSATION for CONFIRMED.
tp_id		Supplied parameter; identifies the local TP. The value of this parameter is returned by TP_STARTED in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
conv_id		Supplied parameter; provides the conversation identifier. The value of this parameter is returned by [MC_]ALLOCATE in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
Return Codes

AP_OK

Primary return code; the verb executed successfully.

AP_PARAMETER_CHECK

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

AP_BAD_CONV_ID

Secondary return code; the value of conv_id did not match a conversation identifier assigned by APPC.

AP_BAD_TP_ID

Secondary return code; the value of tp_id did not match a TP identifier assigned by APPC.

AP_STATE_CHECK

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

AP_CONFIRMED_BAD_STATE

Secondary return code; the conversation is not in CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state.

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

The system administrator should examine the error log to determine the reason for the ABEND.

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

When this return code is used with [MC_]ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there isn't a node available that can satisfy the [MC_]ALLOCATE request.

When [MC_]ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:

X'F0000001'

Secondary return code; no nodes have been started.

X'F0000002'

Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:

The node with the local LU is not started.

The local LU is not configured.

AP_CONVERSATION_TYPE_MIXED

Primary return code; the TP has issued both Basic and Mapped conversation verbs. Only one type can be issued in a single conversation.

AP_INVALID_VERB_SEGMENT

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

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

AP_CONV_BUSY

Primary return code; there can only be one outstanding conversation verb at a time on any conversation. This may occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same conv_id.

AP_THREAD_BLOCKING

Primary return code; the calling thread is already in a blocking call.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

Remarks

The conversation must be in one of the following states when the TP issues this verb:

CONFIRM

CONFIRM_SEND

CONFIRM_DEALLOCATE

The new state is determined by the old state—the state of the conversation when the local TP issued [MC_]CONFIRMED. The old state is indicated by the value of the what_rcvd parameter of the preceding receive verb. The following state changes are possible:

Old state		New state
CONFIRM		RECEIVE
CONFIRM_SEND		SEND
CONFIRM_DEALLLOCATE		RESET
Confirmation Requests

A confirmation request is issued by one of the following verbs in the partner TP:

[MC_]CONFIRM

[MC_]PREPARE_TO_RECEIVE if ptr_type is set to AP_SYNC_LEVEL and the conversation's synchronization level (established by [MC_]ALLOCATE) is AP_CONFIRM_SYNC_LEVEL

[MC_]DEALLOCATE if dealloc_type is set to AP_SYNC_LEVEL and the conversation's synchronization level (established by [MC_]ALLOCATE) is AP_CONFIRM_SYNC_LEVEL

[MC_]SEND_DATA if type is set to AP_SEND_DATA_CONFIRM and the conversation's synchronization level (established by [MC_]ALLOCATE) is AP_CONFIRM_SYNC_LEVEL

A confirmation request is received by the local TP through the what_rcvd parameter of one of the following verbs:

[MC_]RECEIVE_IMMEDIATE

[MC_]RECEIVE_AND_WAIT

[MC_]RECEIVE_AND_POST for Windows NT and OS/2

[MC_]CONFIRMED is issued by the local TP only if what_rcvd contains one of the following values:

AP_CONFIRM_WHAT_RECEIVED

AP_CONFIRM_SEND

AP_CONFIRM_DEALLOCATE

If the rtn_status parameter is set to AP_YES, what_rcvd can also contain the following values:

AP_DATA_COMPLETE_CONFIRM

AP_DATA_COMPLETE_CONFIRM_SEND

AP_DATA_COMPLETE_CONFIRM_DEALL

For Basic conversations, what_rcvd can also contain the following values:

AP_DATA_CONFIRM

AP_DATA_CONFIRM_SEND

AP_DATA_CONFIRM_DEALLOCATE


[MC_]DEALLOCATE
APPC Conversation Verbs	5 of 18

[MC_]DEALLOCATE

Deallocates a conversation between two TPs.

For the Windows version 3.x system, Microsoft recommends that you use WinAsyncAPPC rather than the blocking version of these calls. For more information on using the Windows extension, see Chapter 6, "APPC Extensions for the Windows Environment."

Syntax

For a Mapped conversation:

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
reserv3	unsigned char
dealloc_type	unsigned char
reserv4	unsigned char [2]
reserv5	unsigned char [4]
For a Basic conversation:

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
reserv3	unsigned char
dealloc_type	unsigned char
log_dlen	unsigned short int
log_dptr	unsigned char far
Parameter		Description
opcode		Supplied parameter; allowed values include AP_M_DEALLOCATE for MC_DEALLOCATE and AP_B_DEALLOCATE for DEALLOCATE.
opext		Supplied parameter; allowed values include AP_MAPPED _CONVERSATION for MC_DEALLOCATE and AP_BASIC _CONVERSATION for DEALLOCATE.
tp_id		Supplied parameter; identifies the local TP. The value of this parameter is returned by TP_STARTED in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
conv_id		Supplied parameter; provides the conversation identifier. The value of this parameter is returned by [MC_]ALLOCATE in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
dealloc_type		Supplied parameter; specifies how to perform the deallocation. For MC_DEALLOCATE, use AP_ABEND to deallocate the conversation abnormally. If the conversation is in SEND state when the local TP issues MC_DEALLOCATE, APPC sends the contents of the local LU's send buffer to the partner TP before deallocating the conversation. If the conversation is in RECEIVE or PENDING_POST state, APPC purges any incoming data before deallocating the conversation. A TP should specify AP_ABEND when it encounters an error preventing the successful completion of a transaction. The following values are valid only for DEALLOCATE: AP_ABEND_PROG AP_ABEND_SVC AP_ABEND_TIMER Using one of these values deallocates the conversation abnormally. If the conversation is in SEND state when the local TP issues DEALLOCATE, APPC sends the contents of the local LU's send buffer to the partner TP before deallocating the conversation. If the conversation is in RECEIVE or PENDING_POST state, APPC purges any incoming data before deallocating the conversation. An application or service TP should specify AP_ABEND_PROG when it encounters an error preventing the successful completion of a transaction. A service TP should specify AP_ABEND_SVC when it encounters an error caused by its partner service TP (for example, a format error in control information sent by the partner service TP). A service TP should specify AP_ABEND_TIMER when it encounters an error requiring immediate deallocation (for example, an operator ending the program prematurely). AP_FLUSH sends the contents of the local LU's send buffer to the partner TP before deallocating the conversation. This value is allowed only if the conversation is in SEND state.
		AP_SYNC_LEVEL uses the conversation's synchronization level (established by [MC_]ALLOCATE) to determine how to deallocate the conversation. This value is allowed only if the conversation is in SEND state. If the synchronization level of the conversation is AP_NONE, APPC sends the contents of the local LU's send buffer to the partner TP before deallocating the conversation.
		If the synchronization level is AP_CONFIRM_SYNC_LEVEL, APPC sends the contents of the local LU's send buffer and a confirmation request to the partner TP. Upon receiving confirmation from the partner TP, APPC deallocates the conversation. If, however, the partner TP reports an error, the conversation remains allocated.
log_dlen		Supplied parameter; specifies the number of bytes of data to be sent to the error log file. It is used only by DEALLOCATE. The range is from 0 through 32,767. You can set this parameter to a number greater than 0 if dealloc_type is set to AP_ABEND_PGM, AP_ABEND_SVC, or AP_ABEND_TIMER. Otherwise, this parameter must be 0.
log_dptr		Supplied parameter; provides the address of the data buffer containing error information. The data is sent to the local error log and to the partner LU. This parameter is used by DEALLOCATE if log_dlen is greater than 0. For Windows NT and Windows, the data buffer can reside in a static data area or in a globally allocated area. The data buffer must fit entirely within this area. For OS/2, the log data buffer must reside on an unnamed, shared segment, which is allocated by the function DosAllocSeg with Flags equal to 1. The log data buffer must fit entirely on the segment. The TP must format the error data as a GDS error log variable. For more information, see your IBM SNA manual(s).
Return Codes

AP_OK

Primary return code; the verb executed successfully.

AP_PARAMETER_CHECK

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

AP_BAD_CONV_ID

Secondary return code; the value of conv_id did not match a conversation identifier assigned by APPC.

AP_BAD_TP_ID

Secondary return code; the value of tp_id did not match a TP identifier assigned by APPC.

AP_DEALLOC_BAD_TYPE

Secondary return code; the dealloc_type parameter was not set to a valid value.

AP_DEALLOC_LOG_LL_WRONG (for a Basic conversation)

Secondary return code; the LL field of the GDS error log variable did not match the actual length of the log data.

AP_INVALID_DATA_SEGMENT (for a Basic conversation)

Secondary return code; the error data for the log file was longer than the segment allocated to contain the error data, or the address of the error data buffer was wrong.

AP_STATE_CHECK

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

AP_DEALLOC_CONFIRM_BAD_STATE

Secondary return code; the conversation was not in SEND state, and the TP attempted to flush the send buffer and send a confirmation request. This attempt occurred because the value of dealloc_type was AP_SYNC _LEVEL and the synchronization level of the conversation was AP_CONFIRM_SYNC_LEVEL.

AP_DEALLOC_FLUSH_BAD_STATE

Secondary return code; the conversation was not in SEND state and the TP attempted to flush the send buffer. This attempt occurred because the value of dealloc_type was AP_FLUSH or because the value of dealloc_type was AP_SYNC_LEVEL and the synchronization level of the conversation was AP_NONE. In either case, the conversation must be in SEND state.

AP_DEALLOC_NOT_LL_BDY (for a Basic conversation)

Secondary return code; the conversation was in SEND state, and the TP did not finish sending a logical record. The dealloc_type parameter was set to AP_SYNC_LEVEL or AP_FLUSH.

AP_ALLOCATION_ERROR

Primary return code; APPC has failed to allocate a conversation. The conversation state is set to RESET.

This code may be returned through a verb issued after [MC_]ALLOCATE.

AP_ALLOCATION_FAILURE_NO_RETRY

Secondary return code; the conversation cannot be allocated because of a permanent condition, such as a configuration error or session protocol error. To determine the error, the system administrator should examine the error log file. Do not retry the allocation until the error has been corrected.

AP_ALLOCATION_FAILURE_RETRY

Secondary return code; the conversation could not be allocated because of a temporary condition, such as a link failure. The reason for the failure is logged in the system error log. Retry the allocation.

AP_CONVERSATION_TYPE_MISMATCH

Secondary return code; the partner LU or TP does not support the conversation type (Basic or Mapped) specified in the allocation request.

AP_PIP_NOT_ALLOWED

Secondary return code; the allocation request specified PIP data, but either the partner TP does not require this data, or the partner LU does not support it.

AP_PIP_NOT_SPECIFIED_CORRECTLY

Secondary return code; the partner TP requires PIP data, but the allocation request specified either no PIP data or an incorrect number of parameters.

AP_SECURITY_NOT_VALID

Secondary return code; the user ID or password specified in the allocation request was not accepted by the partner LU.

AP_SYNC_LEVEL_NOT_SUPPORTED

Secondary return code; the partner TP does not support the sync_level (AP_NONE or AP_CONFIRM_SYNC_LEVEL) specified in the allocation request, or the sync_level was not recognized.

AP_TP_NAME_NOT_RECOGNIZED

Secondary return code; the partner LU does not recognize the TP name specified in the allocation request.

AP_TRANS_PGM_NOT_AVAIL_NO_RETRY

Secondary return code; the remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition is permanent. The reason for the error may be logged on the remote node. Do not retry the allocation until the error has been corrected.

AP_TRANS_PGM_NOT_AVAIL_RETRY

Secondary return code; the remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition may be temporary, such as a time-out. The reason for the error may be logged on the remote node. Retry the allocation.

AP_COMM_SUBSYSTEM_ABENDED

Primary return code; this 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.

The system administrator should examine the error log to determine the reason for the ABEND.

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

When this return code is used with [MC_]ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there isn't a node available that can satisfy the [MC_]ALLOCATE request.

When [MC_]ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:

X'F0000001'

Secondary return code; no nodes have been started.

X'F0000002'

Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:

The node with the local LU is not started.

The local LU is not configured.

AP_CONV_FAILURE_NO_RETRY

Primary return code; the conversation was terminated because of a permanent condition, such as a session protocol error. The system administrator should examine the system error log to determine the cause of the error. Do not retry the conversation until the error has been corrected.

AP_CONV_FAILURE_RETRY

Primary return code; the conversation was terminated because of a temporary error. Restart the TP to see if the problem occurs again. If it does, the system administrator should examine the error log to determine the cause of the error.

AP_CONVERSATION_TYPE_MIXED

Primary return code; the TP has issued both Basic and Mapped conversation verbs. Only one type can be issued in a single conversation.

AP_INVALID_VERB_SEGMENT

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

AP_PROG_ERROR_PURGING

Primary return code; while in RECEIVE, PENDING, PENDING_POST (Windows NT and OS/2 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state, the partner TP issued one of the following verbs:

SEND_ERROR with err_type set to AP_PROG

MC_SEND_ERROR

Data sent but not yet received is purged.

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

AP_CONV_BUSY

Primary return code; there can only be one outstanding conversation verb at a time on any conversation. This may occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same conv_id.

AP_THREAD_BLOCKING

Primary return code; the calling thread is already in a blocking call.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

AP_DEALLOC_ABEND (for a Mapped conversation)

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner TP issued MC_DEALLOCATE with dealloc_type set to AP_ABEND.

The partner TP encountered an ABEND, causing the partner LU to send an MC_DEALLOCATE request.

AP_DEALLOC_ABEND_PROG

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_PROG.

The partner TP has encountered an ABEND, causing the partner LU to send a DEALLOCATE request.

AP_DEALLOC_ABEND_SVC

Primary return code; the conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_SVC.

AP_DEALLOC_ABEND_TIMER

Primary return code; the conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_TIMER.

AP_SVC_ERROR_PURGING

Primary return code; the partner TP (or partner LU) issued SEND_ERROR with err_type set to AP_SVC while in RECEIVE, PENDING_POST (Windows NT and OS/2 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state. Data sent to the partner TP may have been purged.

Remarks

Depending on the value of the dealloc_type parameter, the conversation can be in one of the states indicated in the following table when the TP issues [MC_]DEALLOCATE.

dealloc_type		Allowed state
AP_FLUSH		SEND
AP_SYNC_LEVEL		SEND
AP_ABEND		Any except RESET
AP_ABEND_PROG		Any except RESET
AP_ABEND_SVC		Any except RESET
AP_ABEND_TIMER		Any except RESET
State changes, summarized in the following table, are based on the value of the primary_rc.

primary_rc		New state
AP_OK		RESET
AP_ALLOCATION_ERROR		RESET
AP_CONV_FAILURE_RETRY		RESET
AP_CONV_FAILURE_NO_RETRY		RESET
AP_DEALLOC_ABEND		RESET
AP_DEALLOC_ABEND_PROG		RESET
AP_DEALLOC_ABEND_SVC		RESET
AP_DEALLOC_ABEND_TIMER		RESET
AP_PROG_ERROR_PURGING		RECEIVE
AP_SVC_ERROR_PURGING		RECEIVE
Before deallocating the conversation, this verb performs the equivalent of one of the following:

[MC_]FLUSH, by sending the contents of the local LU's send buffer to the partner LU (and TP)

[MC_]CONFIRM, by sending the contents of the local LU's send buffer and a confirmation request to the partner TP

After this verb has successfully executed, the conversation ID is no longer valid.


[MC_]FLUSH
APPC Conversation Verbs	6 of 18

[MC_]FLUSH

Sends the contents of the local LU's send buffer to the partner LU (and TP). If the send buffer is empty, no action takes place.

For the Windows version 3.x system, Microsoft recommends that you use WinAsyncAPPC rather than the blocking version of these calls. For more information on using the Windows extension, see Chapter 6, "APPC Extensions for the Windows Environment."

Syntax

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
Parameter		Description
opcode		Supplied parameter; allowed values include AP_M_FLUSH for MC_FLUSH and AP_B_FLUSH for FLUSH.
opext		Supplied parameter; allowed values include AP_MAPPED_CONVERSATION for MC_FLUSH and AP_BASIC_CONVERSATION for FLUSH.
tp_id		Supplied parameter; identifies the local TP. The value of this parameter is returned by TP_STARTED in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
conv_id		Supplied parameter; provides the conversation identifier. The value of this parameter is returned by [MC_]ALLOCATE in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
Return Codes

AP_OK

Primary return code; the verb executed successfully.

AP_PARAMETER_CHECK

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

AP_BAD_CONV_ID

Secondary return code; the value of conv_id did not match a conversation identifier assigned by APPC.

AP_BAD_TP_ID

Secondary return code; the value of tp_id did not match a TP identifier assigned by APPC.

AP_STATE_CHECK

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

AP_FLUSH_NOT_SEND_STATE

Secondary return code; the conversation was not in SEND state.

AP_COMM_SUBSYSTEM_ABENDED

Primary return code; this 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.

The system administrator should examine the error log to determine the reason for the ABEND.

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

When this return code is used with [MC_]ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there isn't a node available that can satisfy the [MC_]ALLOCATE request.

When [MC_]ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:

X'F0000001'

Secondary return code; no nodes have been started.

X'F0000002'

Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:

The node with the local LU is not started.

The local LU is not configured.

AP_CONVERSATION_TYPE_MIXED

Primary return code; the TP has issued both Basic and Mapped conversation verbs. Only one type can be issued in a single conversation.

AP_INVALID_VERB_SEGMENT

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

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

AP_conv_BUSY

Primary return code; there can only be one outstanding conversation verb at a time on any conversation. This may occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same conv_id.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

Remarks

Data processed by [MC_]SEND_DATA accumulates in the local LU's send buffer until one of the following happens:

The local TP issues [MC_]FLUSH (or other verb that flushes the LU's send buffer).

The buffer is full.

The request generated by [MC_]ALLOCATE is also buffered.

The conversation must be in SEND state when the TP issues this verb.

There is no state change.


[MC_]GET_ATTRIBUTES
APPC Conversation Verbs	7 of 18

[MC_]GET_ATTRIBUTES

Returns the attributes of the conversation.

Syntax

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
reserv3	unsigned char
sync_level	unsigned char
mode_name	unsigned char [8]
net_name	unsigned char [8]
lu_name	unsigned char [8]
lu_alias	unsigned char [8]
plu_alias	unsigned char [8]
plu_un_name	unsigned char [8]
reserv4	unsigned char [2]
fqplu_name	unsigned char [17]
reserv5	unsigned char
user_id	unsigned char [10]
conv_group_id	unsigned long int
conv_corr_len	unsigned char
conv_corr_id	unsigned char [8]
reserv6	unsigned char [13]
Parameter		Description
opcode		Supplied parameter; allowed values include AP_M_GET _ATTRIBUTES for MC_GET_ATTRIBUTES and AP_B_GET _ATTRIBUTES for GET_ATTRIBUTES.
opext		Supplied parameter; allowed values include AP_MAPPED _CONVERSATION for MC_GET_ATTRIBUTES and AP_BASIC _CONVERSATION for GET_ATTRIBUTES.
tp_id		Supplied parameter; identifies the local TP. The value of this parameter is returned by TP_STARTED in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
conv_id		Supplied parameter; provides the conversation identifier. The value of this parameter is returned by [MC_]ALLOCATE in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
sync_level		Returned parameter; specifies the level of synchronization processing for the conversation. This parameter determines whether the TPs can request confirmation of receipt of data and confirm receipt of data. AP_CONFIRM_SYNC_LEVEL indicates that TPs can use confirmation processing in this conversation. AP_NONE indicates that confirmation processing will not be used in this conversation.
mode_name		Returned parameter; specifies the name of a set of networking characteristics. It is a type A EBCDIC character string.
net_name		Returned parameter; specifies the name of the SNA network containing the local LU used by this TP. It is a type A EBCDIC character string.
lu_name		Returned parameter; provides the name of the local LU.
lu_alias		Returned parameter; provides the alias by which the local LU is known to the local TP. It is an ASCII character string.
plu_alias		Returned parameter; this is the alias by which the partner LU is known to the local TP. It is an ASCII character string.
plu_un_name		Returned parameter, specifies the uninterpreted name of the partner LU — the name of the partner LU as defined to the system services control point (SSCP). It is a type AE EBCDIC character string. This parameter is returned only if the local LU is dependent.
fqplu_name		Returned parameter; provides the fully qualified name of the partner LU. It is a type A EBCDIC character string. The field contains the network name, an EBCDIC period, and the partner-LU name.
user_id		Returned parameter; specifies the user ID sent by the invoking TP through [MC_]ALLOCATE to access the invoked TP (if applicable). It is a type AE EBCDIC character string. The field contains the user ID if the following conditions are true: The invoked TP requires conversation security. [MC_]GET_ATTRIBUTES was issued by the invoked TP. Otherwise, the field contains spaces.
conv_group_id		Returned parameter; specifies the conversation group identifier for the session to which the conversation has been allocated. This is also returned on [MC_]ALLOCATE and RECEIVE_ALLOCATE.
conv_corr_len		Returned parameter; specifies the length of the conversation correlator ID that is returned.
conv_corr_id		Returned parameter; specifies the conversation correlator ID (if any) that the source LU assigns to identify the conversation, which is unique for the source/partner LU pair. It is sent by the source LU on the allocation request.
Return Codes

AP_OK

Primary return code; the verb executed successfully.

AP_PARAMETER_CHECK

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

AP_BAD_CONV_ID

Secondary return code; the value of conv_id did not match a conversation identifier assigned by APPC.

AP_BAD_TP_ID

Secondary return code; the value of tp_id did not match a TP identifier assigned by APPC.

AP_COMM_SUBSYSTEM_ABENDED

Primary return code; this 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.

The system administrator should examine the error log to determine the reason for the ABEND.

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

When this return code is used with [MC_]ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there isn't a node available that can satisfy the [MC_]ALLOCATE request.

When [MC_]ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:

X'F0000001'

Secondary return code; no nodes have been started.

X'F0000002'

Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:

The node with the local LU is not started.

The local LU is not configured.

AP_CONVERSATION_TYPE_MIXED

Primary return code; the TP has issued both Basic and Mapped conversation verbs. Only one type can be issued in a single conversation.

AP_INVALID_VERB_SEGMENT

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

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

AP_CONV_BUSY

Primary return code; there can only be one outstanding conversation verb at a time on any conversation. This may occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same conv_id.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

Remarks

Conversation can be in any state except RESET when the TP issues this verb.

There is no state change.


GET_TYPE
APPC Conversation Verbs	8 of 18

GET_TYPE

Returns the conversation type (Basic or Mapped) of a particular conversation so the TP can decide whether to use Basic or Mapped conversation verbs.

Syntax

opcode	unsigned short int
opext (reserved)	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
conv_type	unsigned char
Parameter		Description
opcode		Supplied parameter; ap_get_type.
tp_id		Supplied parameter; identifies the local TP. The value of this parameter was returned by TP_STARTED in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
conv_id		Supplied parameter; provides the identifier for the conversation about which this TP is inquiring. The value of this parameter was returned by [MC_]ALLOCATE in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
conv_type		Returned parameter, supplies the type of conversation, either AP_BASIC_CONVERSATION or AP_MAPPED_CONVERSATION.
Return Codes

AP_OK

Primary return code; the verb executed successfully.

AP_PARAMETER_CHECK

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

AP_BAD_CONV_ID

Secondary return code; the value of conv_id did not match a conversation identifier assigned by APPC.

AP_BAD_TP_ID

Secondary return code; the value of tp_id did not match a TP identifier assigned by APPC.

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

The system administrator should examine the error log to determine the reason for the ABEND.

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

When this return code is used with [MC_]ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there isn't a node available that can satisfy the [MC_]ALLOCATE request.

When [MC_]ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:

X'F0000001'

Secondary return code; no nodes have been started.

X'F0000002'

Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:

The node with the local LU is not started.

The local LU is not configured.

AP_INVALID_VERB_SEGMENT

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

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

AP_CONV_BUSY

Primary return code; there can only be one outstanding conversation verb at a time on any conversation. This may occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same conv_id.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

Remarks

The conversation can be in any state except RESET when the TP issues this verb.

There is no state change.


[MC_]PREPARE_TO_RECEIVE
APPC Conversation Verbs	9 of 18

[MC_]PREPARE_TO_RECEIVE

Changes the state of the conversation for the local TP from SEND to RECEIVE.

For the Windows version 3.x system, Microsoft recommends that you use WinAsyncAPPC rather than the blocking version of these calls. For more information on using the Windows extension, see Chapter 6, "APPC Extensions for the Windows Environment."

Syntax

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
ptr_type	unsigned char
locks	unsigned char
Parameter		Description
opcode		Supplied parameter; allowed values include AP_M_PREPARE_TO _RECEIVE for MC_PREPARE_TO_RECEIVE and AP_B _PREPARE_TO_RECEIVE for PREPARE_TO_RECEIVE.
opext		Supplied parameter; allowed values include AP_MAPPED _CONVERSATION for MC_PREPARE_TO_RECEIVE and AP_BASIC_CONVERSATION for PREPARE_TO_RECEIVE.
tp_id		Supplied parameter; identifies the local TP. The value of this parameter is returned by TP_STARTED in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
conv_id		Supplied parameter; provides the conversation identifier. The value of this parameter is returned by [MC_]ALLOCATE in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
ptr_type		Supplied parameter; specifies how to perform the state change. Use AP_FLUSH to send the contents of the local LU's send buffer to the partner LU (and TP) before changing the conversation's state to RECEIVE. The AP_SYNC_LEVEL value uses the conversation's synchronization level (established by [MC_]ALLOCATE) to determine how to perform the state change.
ptr_type		If the synchronization level of the conversation is AP_NONE, APPC sends the contents of the local LU's send buffer to the partner TP before changing the conversation's state to RECEIVE. If the synchronization level is AP_CONFIRM_SYNC_LEVEL, APPC sends the contents of the local LU's send buffer and a confirmation request to the partner TP. Upon receiving confirmation from the partner TP, APPC changes the conversation's state to RECEIVE. If, however, the partner TP reports an error, the state changes to RECEIVE or RESET. See "Remarks" later in this section.
locks		Supplied parameter; specifies when APPC should return control to the local TP. Use this parameter only if ptr_type is set to AP_SYNC_LEVEL and the synchronization level of the conversation, established by [MC_]ALLOCATE, is AP_CONFIRM_SYNC_LEVEL. (Otherwise, the parameter is ignored.) Use AP_LONG to indicate that APPC returns control to the local TP when the confirmation and subsequent data from the partner TP arrive at the local LU. (This method results in more efficient use of the network but requires longer time to return control to the local TP.) Use AP_SHORT to indicate that APPC returns control to the local TP when the confirmation from the partner TP arrives at the local LU.
Return Codes

AP_OK

Primary return code; the verb executed successfully.

AP_PARAMETER_CHECK

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

AP_BAD_CONV_ID

Secondary return code; the value of conv_id did not match a conversation identifier assigned by APPC.

AP_BAD_TP_ID

Secondary return code; the value of tp_id did not match a TP identifier assigned by APPC.

AP_P_TO_R_INVALID_TYPE

Secondary return code; the ptr_type parameter was not set to a valid value.

AP_STATE_CHECK

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

AP_P_TO_R_NOT_SEND_STATE

Secondary return code; the conversation was not in SEND state.

AP_P_TO_R_NOT_LL_BDY

Secondary return code; the local TP did not finish sending a logical record.

AP_ALLOCATION_ERROR

Primary return code; APPC has failed to allocate a conversation. The conversation state is set to RESET.

This code may be returned through a verb issued after [MC_]ALLOCATE.

AP_ALLOCATION_FAILURE_NO_RETRY

Secondary return code; the conversation cannot be allocated because of a permanent condition, such as a configuration error or session protocol error. To determine the error, the system administrator should examine the error log file. Do not retry the allocation until the error has been corrected.

AP_ALLOCATION_FAILURE_RETRY

Secondary return code; the conversation could not be allocated because of a temporary condition, such as a link failure. The reason for the failure is logged in the system error log. Retry the allocation.

AP_CONVERSATION_TYPE_MISMATCH

Secondary return code; the partner LU or TP does not support the conversation type (Basic or Mapped) specified in the allocation request.

AP_PIP_NOT_ALLOWED

Secondary return code; the allocation request specified PIP data, but either the partner TP does not require this data, or the partner LU does not support it.

AP_PIP_NOT_SPECIFIED_CORRECTLY

Secondary return code; the partner TP requires PIP data, but the allocation request specified either no PIP data or an incorrect number of parameters.

AP_SECURITY_NOT_VALID

Secondary return code; the user ID or password specified in the allocation request was not accepted by the partner LU.

AP_SYNC_LEVEL_NOT_SUPPORTED

Secondary return code; the partner TP does not support the sync_level (AP_NONE or AP_CONFIRM_SYNC_LEVEL) specified in the allocation request, or the sync_level was not recognized.

AP_TP_NAME_NOT_RECOGNIZED

Secondary return code; the partner LU does not recognize the TP name specified in the allocation request.

AP_TRANS_PGM_NOT_AVAIL_NO_RETRY

Secondary return code; the remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition is permanent. The reason for the error may be logged on the remote node. Do not retry the allocation until the error has been corrected.

AP_TRANS_PGM_NOT_AVAIL_RETRY

Secondary return code; the remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition may be temporary, such as a time-out. The reason for the error may be logged on the remote node. Retry the allocation.

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

The system administrator should examine the error log to determine the reason for the ABEND.

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

When this return code is used with [MC_]ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there isn't a node available that can satisfy the [MC_]ALLOCATE request.

When [MC_]ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:

X'F0000001'

Secondary return code; no nodes have been started.

X'F0000002'

Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:

The node with the local LU is not started.

The local LU is not configured.

AP_CONV_FAILURE_NO_RETRY

Primary return code; the conversation was terminated because of a permanent condition, such as a session protocol error. The system administrator should examine the system error log to determine the cause of the error. Do not retry the conversation until the error has been corrected.

AP_CONV_FAILURE_RETRY

Primary return code; the conversation was terminated because of a temporary error. Restart the TP to see if the problem occurs again. If it does, the system administrator should examine the error log to determine the cause of the error.

AP_CONVERSATION_TYPE_MIXED

Primary return code; the TP has issued both Basic and Mapped conversation verbs. Only one type can be issued in a single conversation.

AP_INVALID_VERB_SEGMENT

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

AP_PROG_ERROR_PURGING

Primary return code; while in RECEIVE, PENDING, PENDING_POST (Windows NT and OS/2 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state, the partner TP issued one of the following verbs:

SEND_ERROR with err_type set to AP_PROG

MC_SEND_ERROR

Data sent but not yet received is purged.

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

AP_CONV_BUSY

Primary return code; there can only be one outstanding conversation verb at a time on any conversation. This may occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same conv_id.

AP_THREAD_BLOCKING

Primary return code; the calling thread is already in a blocking call.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

The following primary return code is returned only by MC_PREPARE _TO_RECEIVE:

AP_DEALLOC_ABEND

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner TP issued MC_DEALLOCATE with dealloc_type set to AP_ABEND.

The partner TP encountered an ABEND, causing the partner LU to send an MC_DEALLOCATE request.

The following primary return codes are returned only by PREPARE_TO_RECEIVE:

AP_DEALLOC_ABEND_PROG

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner TP issued the DEALLOCATE verb with dealloc_type set to AP_ABEND_PROG.

The partner TP has encountered an ABEND, causing the partner LU to send a DEALLOCATE request.

AP_DEALLOC_ABEND_SVC

Primary return code; the conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_SVC.

AP_DEALLOC_ABEND_TIMER

Primary return code; the conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_TIMER.

AP_SVC_ERROR_PURGING

Primary return code; the partner TP (or partner LU) issued a SEND_ERROR verb with err_type set to AP_SVC while in RECEIVE, PENDING_POST (Windows NT and OS/2 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state. Data sent to the partner TP may have been purged.

Remarks

Before changing the conversation state, this verb performs the equivalent of one of the following:

[MC_]FLUSH, by sending the contents of the local LU's send buffer to the partner LU (and TP)

[MC_]CONFIRM, by sending the contents of the local LU's send buffer and a confirmation request to the partner TP

After this verb has successfully executed, the local TP can receive data.

The conversation must be in SEND state when the TP issues this verb.

State changes, summarized in the following table, are based on the value of primary_rc.

primary_rc		New state
AP_OK		RECEIVE
AP_ALLOCATION_ERROR		RESET
AP_CONV_FAILURE_RETRY		RESET
AP_CONV_FAILURE_NO_RETRY		RESET
AP_DEALLOC_ABEND		RESET
AP_DEALLOC_ABEND_PROG		RESET
AP_DEALLOC_ABEND_SVC		RESET
AP_DEALLOC_ABEND_TIMER		RESET
AP_PROG_ERROR_PURGING		RECEIVE
AP_SVC_ERROR_PURGING		RECEIVE
The conversation does not change to SEND state for the partner TP until the partner TP receives one of the following values through the what_rcvd parameter of a subsequent receive verb:

AP_SEND

AP_CONFIRM_SEND and replies with [MC_]CONFIRMED

AP_DATA_COMPLETE_CONFIRM_SEND and replies with [MC_]CONFIRMED

AP_DATA_CONFIRM_SEND and replies with [MC_]CONFIRMED

The receive verbs are [MC_]RECEIVE_AND_POST (Windows NT and the OS/2 operating systems), [MC_]RECEIVE_IMMEDIATE, and [MC_]RECEIVE_AND_WAIT.


RECEIVE_ALLOCATE
APPC Conversation Verbs	10 of 18

RECEIVE_ALLOCATE

Issued by the invoked TP to confirm that the invoked TP is ready to begin a conversation with the invoking TP, which issued [MC_]ALLOCATE.

For the Windows version 3.x system, Microsoft recommends that you use WinAsyncAPPC rather than the blocking version of these calls. For more information on using the Windows extension, see Chapter 6, "APPC Extensions for the Windows Environment."

Syntax

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_name	unsigned char [64]
tp_id	unsigned char [8]
conv_id	unsigned long int
sync_level	unsigned char
conv_type	unsigned char
user_id	unsigned char [10]
lu_alias	unsigned char [8]
plu_alias	unsigned char [8]
mode_name	unsigned char [8]
reserv3	unsigned char [28]
Parameter		Description
opcode		Supplied parameter; AP_RECEIVE_ALLOCATE.
tp_name		Supplied parameter; provides the name of the local TP. The value of tp_name must match the TP name configured through Registry or environment variables. APPC matches the RECEIVE_ALLOCATE verb's tp_name parameter with the TP name specified by the incoming allocate, which is generated by [MC_]ALLOCATE in the invoking TP. This parameter is a 64-byte EBCDIC character string and is case sensitive. The tp_name parameter can consist of characters from the type AE EBCDIC character set: Uppercase and lowercase letters Numerals 0 through 9 Special characters $, #, and period (.) If tp_name is fewer than 64 bytes, use EBCDIC spaces (X'40') to pad it on the right.
tp_name		The SNA convention for naming a service TP is up to four characters. The first character is a hexadecimal byte between X'00' and X'3F'. The other characters are from the type AE EBCDIC character set.
tp_id		Returned parameter; identifies the local TP.
conv_id		Returned parameter; provides the conversation identifier. It identifies the conversation APPC has established between the two partner TPs.
sync_level		Returned parameter; provides the synchronization level of the conversation. The parameter determines whether the TPs can request confirmation of receipt of data and confirm receipt of data. The following are possible values: AP_CONFIRM_SYNC_LEVEL indicates that the partner TPs can use confirmation processing in this conversation. AP_NONE indicates that confirmation processing will not be used in this conversation.
conv_type		Returned parameter; specifies the type of conversation chosen by the partner TP, using [MC_]ALLOCATE. The following are possible values: AP_BASIC_CONVERSATION AP_MAPPED_CONVERSATION
user_id		Returned parameter; provides the user ID specified by the partner TP, using [MC_]ALLOCATE (if the partner TP set the [MC_]ALLOCATE verb's security parameter to AP_PGM or AP_SAME). It is a type AE EBCDIC character string.
lu_alias		Returned parameter; provides the alias by which the local LU is known to the local TP. It is an ASCII character string.
plu_alias		Returned parameter; provides the alias by which the partner LU (which initiated the incoming allocate) is known to the local TP. It is an ASCII character string.
mode_name		Returned parameter; provides the mode name specified by [MC_]ALLOCATE in the partner TP. It is the name of a set of networking characteristics defined during configuration. The mode_name is a type A EBCDIC character string.
Return Codes

AP_OK

Primary return code; the verb executed successfully.

AP_PARAMETER_CHECK

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

AP_UNDEFINED_TP_NAME

Secondary return code; the TP name was not configured correctly.

AP_STATE_CHECK

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

AP_ALLOCATE_NOT_PENDING

Secondary return code; APPC did not find an incoming allocate (from the invoking TP) to match the value of tp_name, supplied by RECEIVE_ALLOCATE. RECEIVE_ALLOCATE waited for the incoming allocate and eventually timed out.

AP_INVALID_PROCESS

Secondary return code; the process issuing RECEIVE_ALLOCATE was different from the one started by APPC.

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

The system administrator should examine the error log to determine the reason for the ABEND.

AP_CONV_BUSY

Primary return code; there can only be one outstanding conversation verb at a time on any conversation.

AP_THREAD_BLOCKING

Primary return code; the calling thread is already in a blocking call.

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

AP_INVALID_VERB_SEGMENT

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

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

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

Remarks

This must be the first APPC verb issued by the invoked TP. The initial state is RESET. If the verb executes successfully (primary_rc is AP_OK), the state changes to RECEIVE.

In response to this verb, APPC establishes a conversation between the two TPs and generates a TP identifier for the invoked TP and a conversation identifier. These identifiers are required parameters for subsequent APPC verbs.

If the invoked TP issues RECEIVE_ALLOCATE and a corresponding incoming allocate (resulting from [MC_]ALLOCATE issued by the invoking TP) is not present, the invoked TP waits until the incoming allocate arrives or the verb times out. The time-out value is set by the system administrator.


[MC_]RECEIVE_AND_POST
APPC Conversation Verbs	11 of 18

[MC_]RECEIVE_AND_POST

Receives application data and status information asynchronously. This allows the local TP to proceed with processing while data is still arriving at the local LU.

[MC_]RECEIVE_AND_POST is only supported under the Windows NT and OS/2 operating systems. For similar functionality under the Windows version 3.x graphical environment, use RECEIVE_AND_WAIT in conjunction with WinAsyncAPPC. Specifically, while an asynchronous RECEIVE_AND_POST is outstanding, the following verbs can be issued on the same conversation:

REQUEST_TO_SEND

GET_TYPE

GET_ATTRIBUTES

TEST_RTS

DEALLOCATE (AP_ABEND_PROG, AP_ABEND_SVC, or AP_ABEND_TIMER)

SEND_ERROR

TP_ENDED

This allows an application to use an asynchronous RECEIVE_AND_POST to receive data. While the RECEIVE_AND_POST is outstanding, it can still use SEND_ERROR and REQUEST_TO_SEND. Microsoft recommends you use this feature for full asynchronous support. For information on using Windows extensions, see Chapter 6, "APPC Extensions for the Windows Environment." For information on how a TP receives data and how to use this verb, see "Remarks" later in this section.

Syntax

For a Mapped conversation:

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
what_rcvd	unsigned short int
rtn_status	unsigned char
reserv4	unsigned char
rts_rcvd	unsigned char
reserv5	unsigned char
max_len	unsigned short int
dlen	unsigned short int
dptr	unsigned char far *
sema	unsigned char far *
reserv6	unsigned char
For a Basic conversation:

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
what_rcvd	unsigned short int
rtn_status	unsigned char
fill	unsigned char
rts_rcvd	unsigned char
reserv4	unsigned char
max_len	unsigned short int
dlen	unsigned short int
dptr	unsigned char far *
sema	unsigned char far *
reserv5	unsigned char
Parameter		Description
opcode		Supplied parameter; allowed values include AP_M_RECEIVE_AND _POST for MC_RECEIVE_AND_POST and AP_B_RECEIVE _AND_POST for RECEIVE_AND_POST.
opext		Supplied parameter; allowed values include AP_MAPPED _CONVERSATION for MC_RECEIVE_AND_POST and AP_BASIC_CONVERSATION for RECEIVE_AND_POST.
tp_id		Supplied parameter; identifies the local TP. The value of this parameter is returned by TP_STARTED in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
conv_id		Supplied parameter; provides the conversation identifier. The value of this parameter is returned by [MC_]ALLOCATE in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
what_rcvd		Returned parameter; indicates whether data or conversation status was received. AP_CONFIRM_DEALLOCATE indicates that the partner TP issued [MC_]DEALLOCATE with dealloc_type set to AP_SYNC _LEVEL. The conversation's synchronization level, established by [MC_]ALLOCATE, is AP_CONFIRM_SYNC_LEVEL. Upon receiving this value, the local TP normally issues [MC_]CONFIRMED.
what_rcvd		AP_CONFIRM_SEND indicates that the partner TP issued [MC_]PREPARE_TO_RECEIVE with ptr_type set to AP_SYNC_LEVEL. The conversation's synchronization level, established by [MC_]ALLOCATE, is AP_CONFIRM_SYNC _LEVEL. Upon receiving this value, the local TP normally issues [MC_]CONFIRMED, and begins to send data.
		AP_CONFIRM_WHAT_RECEIVED indicates that the partner TP issued [MC_]CONFIRM. Upon receiving this value, the local TP normally issues [MC_]CONFIRMED.
		AP_DATA indicates that this value can be returned by RECEIVE_AND_POST if fill is set to AP_BUFFER. The local TP received data until max_len or the end of the data was reached. For more information, see "Remarks" later in this section.
		AP_DATA_COMPLETE indicates, for MC_RECEIVE_AND_POST, that the local TP has received a complete data record or the last part of a data record. For RECEIVE_AND_POST with fill set to AP_LL, this value indicates that the local TP has received a complete logical record or the end of a logical record. Upon receiving this value, the local TP normally reissues [MC_]RECEIVE_AND_POST or issues another receive verb.If the partner TP has sent more data, the local TP begins to receive a new unit of data.
		Otherwise, the local TP examines status information. If primary_rc contains AP_OK and what_rcvd contains AP_SEND, AP_CONFIRM_SEND, AP_CONFIRM _DEALLOCATE, or AP_CONFIRM_WHAT_RECEIVED, see the description of the value (in this section) for the next action the local TP normally takes. If primary_rc contains AP_DEALLOC_NORMAL, the conversation has been deallocated in response to the [MC_]DEALLOCATE issued by the partner TP.
what_rcvd		AP_DATA_INCOMPLETE indicates, for MC_RECEIVE_AND_POST, that the local TP has received an incomplete data record. The max_len parameter specified a value less than the length of the data record (or less than the remainder of the data record if this is not the first receive verb to read the record). For RECEIVE_AND_POST with fill set to AP_LL, this value indicates that the local TP has received an incomplete logical record. Upon receiving this value, the local TP normally reissues [MC_]RECEIVE_AND_POST (or issues another receive verb) to receive the next part of the record.
		AP_NONE indicates that the TP did not receive data or conversation status indicators.
		AP_SEND indicates, for the partner TP, that the conversation has entered RECEIVE state. For the local TP, the conversation is now in SEND state. Upon receiving this value, the local TP normally uses [MC_]SEND_DATA to begin sending data.
rtn_status		Supplied parameter; indicates whether both data and conversation status indicators should be returned within one API call. Use AP_NO to specify that indicators should be returned individually on separate invocations of the verb.
		Use AP_YES to specify that indicators should be returned together, provided both are available. Both can be returned when the receive buffer is large enough to hold all of the data that precedes the status indicator and when the following is true: For a Mapped conversation, the data is the last data record before the status indicator. For a Basic conversation, fill specifies BUFFER or LL, and the data is the last logical record before the status indicator.
fill		Supplied parameter; specifies how the local TP receives data. It is used only by RECEIVE_AND_POST. Use AP_BUFFER to indicate that the local TP receives data until the number of bytes specified by max_len is reached or until end of data. Data is received without regard for the logical-record format. Use AP_LL to indicate that data is received in logical-record format. The data received can be: A complete logical record. A max_len byte portion of a logical record. The end of a logical record.
rts_rcvd		Returned parameter; indicates whether the partner TP issued MC_REQUEST_TO_SEND. Possible values are: AP_YES indicates that the partner TP issued [MC_]REQUEST_TO_SEND, which requests that the local TP change the conversation to RECEIVE state. AP_NO indicates that the partner TP has not issued [MC_]REQUEST_TO_SEND. For an explanation of why this indicator can be received by receive verbs, see "[MC_]REQUEST_TO_SEND" later in this chapter.
max_len		Supplied parameter; specifies the maximum number of bytes of data the local TP can receive. The range is from 0 through 65,535. The value must not exceed the length of the buffer to contain the received data. The offset of dptr plus the value of max_len must not exceed the size of the data segment.
dlen		Returned parameter; specifies the number of bytes of data received. Data is stored in the buffer specified by dptr. A length of 0 indicates that no data was received.
dptr		Supplied parameter; provides the address of the buffer to contain the data received by the local LU. For the Windows NT operating system, the data buffer can reside in a static data area or in a globally allocated area. The data buffer must fit entirely within this area. For the OS/2 operating system, the data buffer must reside on an unnamed, shared segment, which is allocated by the DosAllocSeg function with Flags equal to 1. The data buffer must fit entirely on the data segment.
sema		Supplied parameter; provides the address of the semaphore APPC is to clear when the asynchronous receiving operation is finished. It can be a RAM or system semaphore.
Return Codes

AP_OK

Primary return code; the verb executed successfully.

When rtn_status is AP_YES, the preceding return code or one of the following return codes may be returned.

AP_DATA_COMPLETE_SEND

Primary return code; this is a combination of AP_DATA_COMPLETE and AP_SEND.

AP_DATA_COMPLETE_CONFIRM_SEND

Primary return code; this is a combination of AP_DATA_COMPLETE and AP_CONFIRM_SEND.

AP_DATA_COMPLETE_CONFIRM

Primary return code; this is a combination of AP_DATA_COMPLETE and AP_CONFIRM_WHAT_RECEIVED.

AP_DATA_COMPLETE_CONFIRM_DEALL

Primary return code; this is a combination of AP_DATA_COMPLETE and AP_CONFIRM_DEALLOCATE.

The following combined values are for Basic conversations only:

AP_DATA_SEND

Primary return code; this is a combination of AP_DATA and AP_SEND.

AP_DATA_CONFIRM_SEND

Primary return code; this is a combination of AP_DATA and AP_CONFIRM_SEND.

AP_DATA_CONFIRM

Primary return code; this is a combination of AP_DATA and AP_CONFIRM.

AP_DATA_CONFIRM_DEALLOCATE

Primary return code; this is a combination of AP_DATA and AP_CONFIRM_DEALLOCATE.

AP_DEALLOC_NORMAL

Primary return code; the partner TP issued [MC_]DEALLOCATE with dealloc_type set to AP_FLUSH or AP_SYNC_LEVEL with the synchronization level of the conversation specified as AP_NONE.

If rtn_status is AP_YES, examine what_rcvd also.

AP_PARAMETER_CHECK

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

AP_BAD_CONV_ID

Secondary return code; the value of conv_id did not match a conversation identifier assigned by APPC.

AP_BAD_TP_ID

Secondary return code; the value of tp_id did not match a TP identifier assigned by APPC.

AP_BAD_RETURN_STATUS_WITH_DATA

Secondary return code; the specified rtn_status value was not recognized by APPC.

AP_INVALID_DATA_SEGMENT

Secondary return code; the length specified for the data buffer was longer than the segment allocated to contain the buffer.

AP_INVALID_SEMAPHORE_HANDLE

Secondary return code; the address of the RAM semaphore or system semaphore handle was invalid.

Note

APPC cannot trap all invalid semaphore handles. If the TP passes a bad RAM semaphore handle, a protection violation results.

AP_RCV_AND_POST_BAD_FILL

Secondary return code; the fill parameter was set to an invalid value.

AP_STATE_CHECK

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

AP_RCV_AND_POST_BAD_STATE

Secondary return code; the conversation was not in RECEIVE or SEND state when the TP issued this verb.

AP_RCV_AND_POST_NOT_LL_BDY

Secondary return code; the conversation was in SEND state; the TP began but did not finish sending a logical record.

AP_CANCELED

Primary return code; the local TP issued one of the following verbs, which canceled [MC_]RECEIVE_AND_POST:

DEALLOCATE with dealloc_type set to AP_ABEND_PROG, AP_ABEND_SVC, or AP_ABEND_TIMER

MC_DEALLOCATE with dealloc_type set to AP_ABEND

[MC_]SEND_ERROR

TP_ENDED

Issuing one of these verbs causes the semaphore to be cleared.

AP_ALLOCATION_ERROR

Primary return code; APPC has failed to allocate a conversation. The conversation state is set to RESET.

This code may be returned through a verb issued after [MC_]ALLOCATE.

AP_ALLOCATION_FAILURE_NO_RETRY

Secondary return code; the conversation cannot be allocated because of a permanent condition, such as a configuration error or session protocol error. To determine the error, the system administrator should examine the error log file. Do not retry the allocation until the error has been corrected.

AP_ALLOCATION_FAILURE_RETRY

Secondary return code; the conversation could not be allocated because of a temporary condition, such as a link failure. The reason for the failure is logged in the system error log. Retry the allocation.

AP_CONVERSATION_TYPE_MISMATCH

Secondary return code; the partner LU or TP does not support the conversation type (Basic or Mapped) specified in the allocation request.

AP_PIP_NOT_ALLOWED

Secondary return code; the allocation request specified PIP data, but either the partner TP does not require this data, or the partner LU does not support it.

AP_PIP_NOT_SPECIFIED_CORRECTLY

Secondary return code; the partner TP requires PIP data, but the allocation request specified either no PIP data or an incorrect number of parameters.

AP_SECURITY_NOT_VALID

Secondary return code; the user ID or password specified in the allocation request was not accepted by the partner LU.

AP_SYNC_LEVEL_NOT_SUPPORTED

Secondary return code; the partner TP does not support the sync_level (AP_NONE or AP_CONFIRM_SYNC_LEVEL) specified in the allocation request, or the sync_level was not recognized.

AP_TP_NAME_NOT_RECOGNIZED

Secondary return code; the partner LU does not recognize the TP name specified in the allocation request.

AP_TRANS_PGM_NOT_AVAIL_NO_RETRY

Secondary return code; the remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition is permanent. The reason for the error may be logged on the remote node. Do not retry the allocation until the error has been corrected.

AP_TRANS_PGM_NOT_AVAIL_RETRY

Secondary return code; the remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition may be temporary, such as a time-out. The reason for the error may be logged on the remote node. Retry the allocation.

AP_COMM_SUBSYSTEM_ABENDED

Primary return code; this 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.

The system administrator should examine the error log to determine the reason for the ABEND.

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

When this return code is used with [MC_]ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there isn't a node available that can satisfy the [MC_]ALLOCATE request.

When [MC_]ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:

X'F0000001'

Secondary return code; no nodes have been started.

X'F0000002'

Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:

The node with the local LU is not started.

The local LU is not configured.

AP_CONV_FAILURE_NO_RETRY

Primary return code; the conversation was terminated because of a permanent condition, such as a session protocol error. The system administrator should examine the system error log to determine the cause of the error. Do not retry the conversation until the error has been corrected.

AP_CONV_FAILURE_RETRY

Primary return code; the conversation was terminated because of a temporary error. Restart the TP to see if the problem occurs again. If it does, the system administrator should examine the error log to determine the cause of the error.

AP_CONVERSATION_TYPE_MIXED

Primary return code; the TP has issued both Basic and Mapped conversation verbs. Only one type can be issued in a single conversation.

AP_INVALID_VERB_SEGMENT

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

AP_PROG_ERROR_NO_TRUNC

Primary return code; the partner TP issued one of the following verbs while the conversation was in SEND state:

SEND_ERROR with err_type set to AP_PROG

MC_SEND_ERROR

Data was not truncated.

AP_PROG_ERROR_PURGING

Primary return code; while in RECEIVE, PENDING, PENDING_POST (Windows NT and OS/2 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state, the partner TP issued one of the following verbs:

SEND_ERROR with err_type set to AP_PROG

MC_SEND_ERROR

Data sent but not yet received is purged.

AP_PROG_ERROR_TRUNC

Primary return code; in SEND state, after sending an incomplete logical record, the partner TP issued SEND_ERROR with err_type set to AP_PROG. The local TP may have received the first part of the logical record through a receive verb.

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

AP_CONV_BUSY

Primary return code; there can only be one outstanding conversation verb at a time on any conversation. This may occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same conv_id.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

The following primary return code is returned only by MC_RECEIVE _AND_POST:

AP_DEALLOC_ABEND

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner TP issued MC_DEALLOCATE with dealloc_type set to AP_ABEND.

The partner TP encountered an ABEND, causing the partner LU to send an MC_DEALLOCATE request.

The following primary return codes are returned only by RECEIVE_AND _POST:

AP_DEALLOC_ABEND_PROG

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_PROG.

The partner TP has encountered an ABEND, causing the partner LU to send a DEALLOCATE request.

AP_DEALLOC_ABEND_SVC

Primary return code; the conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_SVC.

AP_DEALLOC_ABEND_TIMER

Primary return code; the conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_TIMER.

AP_SVC_ERROR_NO_TRUNC

Primary return code; while in SEND state, the partner TP (or partner LU) issued SEND_ERROR with err_type set to AP_SVC. Data was not truncated.

AP_SVC_ERROR_PURGING

Primary return code; the partner TP (or partner LU) issued SEND_ERROR with err_type set to AP_SVC while in RECEIVE, PENDING_POST (Windows NT and OS/2 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state. Data sent to the partner TP may have been purged.

AP_SVC_ERROR_TRUNC

Primary return code; in SEND state, after sending an incomplete logical record, the partner TP (or partner LU) issued SEND_ERROR. The local TP may have received the first part of the logical record.

Remarks

The local TP receives data through this process:

The local TP issues a receive verb until it finishes receiving a complete unit of data. The data received may be:

One data record transmitted in a Mapped conversation.

One logical record transmitted in a Basic conversation.

A buffer of data received independent of its logical-record format in a Basic conversation.

The local TP may need to issue the receive verb several times in order to receive a complete unit of data. Once a complete unit of data has been received, the local TP can manipulate it. The receive verbs are [MC_]RECEIVE_AND_POST (Windows NT and OS/2 operating systems), [MC_]RECEIVE_AND_WAIT, and [MC_]RECEIVE_IMMEDIATE.

The local TP issues the receive verb again. This has one of the following effects:

If the partner TP has sent more data, the local TP begins to receive a new unit of data.

If the partner TP has finished sending data or is waiting for confirmation, status information (available through what_rcvd) indicates the next action the local TP normally takes.

To use [MC_]RECEIVE_AND_POST, the local TP performs the following tasks:

Sequence	Task

1	For the Windows NT operating system, the TP retrieves the WinAsyncAPPC message number by calling the RegisterWindowMessage API or allocating a semaphore. The sema field should be set to NULL if the application expects to be notified through the Windows message mechanism.

APPC sends the Windows message or clears the semaphore when the local TP finishes receiving data.

For the OS/2 operating system, the TP uses the DosSemSet function to set the semaphore pointed to by sema.

The semaphore will remain set while the local TP receives data asynchronously. APPC will clear the semaphore when the local TP finishes receiving data.

2	The TP issues [MC_]RECEIVE_AND_POST.

3	The TP checks the value of primary_rc.

If primary_rc is AP_OK, the receive buffer (pointed to by dptr) is asynchronously receiving data from the partner TP. While receiving data asynchronously, the local TP can:

   Perform tasks not related to this conversation.

   Issue [MC_]REQUEST_TO_SEND.

   Gather information about this conversation by issuing GET_TYPE, [MC_]GET_ATTRIBUTES, or [MC_]TEST_RTS.

   Prematurely cancel [MC_]RECEIVE_AND_POST by issuing DEALLOCATE with dealloc_type set to AP_ABEND_PROG, AP_ABEND_SVC, or AP_ABEND_TIMER; MC_DEALLOCATE with dealloc_type set to AP_ABEND; [MC_]SEND_ERROR; or TP_ENDED.

If, however, primary_rc is not AP_OK, [MC_]RECEIVE_AND_POST has failed. In this case, the local TP does not perform the next two tasks.

4	For the Windows NT operating system, when the TP finishes receiving data asynchronously, APPC issues the WinAsyncAPPC Windows message or clears the semaphore.

For the OS/2 operating system, the TP uses the DosSemWait function to wait for APPC to clear the semaphore pointed to by sema. When the TP finishes receiving data asynchronously, APPC clears the semaphore. To prevent the local TP from waiting, have it test the semaphore (invoking DosSemWait with Timeout set to 0) until APPC clears the semaphore.

5	The TP checks the new value of primary_rc.

If primary_rc is AP_OK, the local TP can examine the other returned parameters and manipulate the asynchronously received data.

If primary_rc is not AP_OK, only secondary_rc and rts_rcvd (request-to-send received) are meaningful.

Conversation States

The conversation must be in RECEIVE or SEND state when the TP issues this verb.

Issuing [MC_]RECEIVE_AND_POST while the conversation is in SEND state has the following effects:

The local LU sends the information in its send buffer and a SEND indicator to the partner TP.

The conversation changes to PENDING_POST state; the local TP is ready to receive information from the partner TP asynchronously.

The conversation changes states twice:

Upon initial return of the verb, if primary_rc contains AP_OK, the conversation changes to PENDING_POST state.

After completion of the verb, the state changes depending on the value of the following:

The primary_rc parameter

The what_rcvd parameter if primary_rc is AP_OK

what_rcvd		New state
AP_CONFIRM_DEALLOCATE		CONFIRM_DEALLOCATE
AP_DATA_COMPLETE_CONFIRM_DEALL		CONFIRM_DEALLOCATE
AP_DATA_CONFIRM_DEALLOCATE		CONFIRM_DEALLOCATE
AP_CONFIRM_SEND		CONFIRM_SEND
what_rcvd		New state
AP_DATA_COMPLETE_CONFIRM_SEND		CONFIRM_SEND
AP_DATA_CONFIRM_SEND		CONFIRM_SEND
AP_CONFIRM_WHAT_RECEIVED		CONFIRM
AP_DATA_COMPLETE_CONFIRM		CONFIRM
AP_DATA_CONFIRM		CONFIRM
AP_DATA		RECEIVE
AP_DATA_COMPLETE		RECEIVE
AP_DATA_INCOMPLETE		RECEIVE
AP_SEND		SEND
AP_DATA_COMPLETE_SEND		SEND_PENDING
primary_rc		New state
AP_CANCELED		NO CHANGE
AP_CONV_FAILURE_RETRY		RESET
AP_CONV_FAILURE_NO_RETRY		RESET
AP_DEALLOC_ABEND		RESET
AP_DEALLOC_ABEND_PROG		RESET
AP_DEALLOC_ABEND_SVC		RESET
AP_DEALLOC_ABEND_TIMER		RESET
AP_DEALLOC_NORMAL		RESET
AP_PROG_ERROR_PURGING		RECEIVE
AP_PROG_ERROR_NO_TRUNC		RECEIVE
AP_SVC_ERROR_PURGING		RECEIVE
AP_SVC_ERROR_NO_TRUNC		RECEIVE
AP_PROG_ERROR_TRUNC		RECEIVE
AP_SVC_ERROR_TRUNC		RECEIVE
End of Data for a Basic Conversation

If the local TP issues RECEIVE_AND_POST and sets fill to AP_BUFFER, the receipt of data ends when max_len or the end of the data is reached. The end of the data is indicated by either primary_rc with a value other than AP_OK (for example, AP_DEALLOC_NORMAL), or by what_rcvd with one of the following values:

AP_SEND

AP_CONFIRM_SEND

AP_CONFIRM_DEALLOCATE

AP_CONFIRM_WHAT_RECEIVED

AP_DATA_CONFIRM_SEND

AP_DATA_CONFIRM_DEALLOCATE

AP_DATA_CONFIRM

To determine if the end of the data has been reached, the local TP reissues RECEIVE_AND_POST. If the new primary_rc contains AP_OK and what_rcvd contains AP_DATA, the end of the data has not been reached. If, however, the end of the data has been reached, primary_rc or what_rcvd will indicate the cause of the end of the data.

Troubleshooting

The local TP may wait indefinitely if one of the following situations occurs:

For the Windows NT operating system, the local TP issues a RECEIVE_AND_POST request, but either the partner TP has not sent data or the initial primary_rc is not AP_OK.

For the OS/2 operating system, the local TP issues a DosSemWait function call, but either the partner TP has not sent data or the initial primary_rc is not AP_OK.

This is because APPC will not issue the Windows message or clear the semaphore.

When a condition resulting in one of the following primary_rc parameters occurs, APPC does not clear the semaphore:

AP_INVALID_SEMAPHORE_HANDLE

AP_INVALID_VERB_SEGMENT

AP_STACK_TOO_SMALL

To test what_rcvd, issue [MC_]RECEIVE_AND_POST with max_len set to 0, so that the local TP can determine whether the partner TP has data to send, seeks confirmation, or has changed the conversation state.


[MC_]RECEIVE_AND_WAIT
APPC Conversation Verbs	12 of 18

[MC_]RECEIVE_AND_WAIT

Receives any data that is currently available from the partner TP. If no data is currently available, the local TP waits for data to arrive.

For the Windows version 3.x system, Microsoft recommends that you use WinAsyncAPPC rather than the blocking version of these calls. To allow full use to be made of the asynchronous support, asynchronously issued RECEIVE_AND_WAIT verbs have been altered to act like RECEIVE_AND_POST verbs. Specifically, while an asynchronous RECEIVE_AND_WAIT is outstanding, the following verbs can be issued on the same conversation:

REQUEST_TO_SEND

GET_TYPE

GET_ATTRIBUTES

TEST_RTS

DEALLOCATE (AP_ABEND_PROG, AP_ABEND_SVC, or AP_ABEND_TIMER)

SEND_ERROR

TP_ENDED

This allows an application, and in particular, a 5250 emulator, to use an asynchronous RECEIVE_AND_WAIT to receive data. While the RECEIVE_AND_WAIT is outstanding, it can still use SEND_ERROR and REQUEST_TO_SEND. Microsoft recommends that you use this feature for full asynchronous support. For information on using the Windows extension, see Chapter 6, "APPC Extensions for the Windows Environment."

Syntax

For a Mapped conversation:

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
what_rcvd	unsigned short int
rtn_status	unsigned char
reserv4	unsigned char
rts_rcvd	unsigned char
reserv5	unsigned char
max_len	unsigned short int
dlen	unsigned short int
dptr	unsigned char far *
reserv6	unsigned char [5]
For a Basic conversation:

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
what_rcvd	unsigned short int
rtn_status	unsigned char
fill	unsigned char
rts_rcvd	unsigned char
reserv4	unsigned char
max_len	unsigned short int
dlen	unsigned short int
dptr	unsigned char far *
reserv5	unsigned char [5]
Parameter		Description
opcode		Supplied parameter; allowed values include AP_M_RECEIVE_AND _WAIT for MC_RECEIVE_AND_WAIT and AP_B_RECEIVE _AND_WAIT for RECEIVE_AND_WAIT.
opext		Supplied parameter; allowed values include AP_MAPPED _CONVERSATION for MC_RECEIVE_AND_WAIT and AP_BASIC_CONVERSATION for RECEIVE_AND_WAIT.
tp_id		Supplied parameter; identifies the local TP. The value of this parameter is returned by TP_STARTED in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
conv_id		Supplied parameter; specifies the conversation identifier. The value of this parameter is returned by [MC_]ALLOCATE in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
what_rcvd		Returned parameter; indicates whether data or conversation status was received. AP_CONFIRM_DEALLOCATE indicates that the partner TP has issued [MC_]DEALLOCATE with dealloc_type set to AP_SYNC_LEVEL, and the conversation's synchronization level, established by [MC_]ALLOCATE, is AP_CONFIRM_SYNC_LEVEL. Upon receiving this value, the local TP normally issues [MC_]CONFIRMED.
		AP_CONFIRM_SEND indicates that the partner TP has issued [MC_]PREPARE_TO_RECEIVE with ptr_type set to AP_SYNC_LEVEL, and the conversation's synchronization level, established by [MC_]ALLOCATE, is AP_CONFIRM_SYNC_LEVEL. Upon receiving this value, the local TP normally issues [MC_]CONFIRMED and begins to send data.
		AP_CONFIRM_WHAT_RECEIVED indicates that the partner TP has issued [MC_]CONFIRM. Upon receiving this value, the local TP normally issues [MC_]CONFIRMED.
		AP_DATA can be returned in a Basic conversation by RECEIVE_AND_WAIT if fill is set to AP_BUFFER. The local TP received data until max_len or end of data was reached. For more information, see "RECEIVE_AND_WAIT End of Data" later in this section.
		AP_DATA_COMPLETE indicates, in a Mapped conversation for MC_RECEIVE_AND_WAIT, that the local TP has received a complete data record or the last part of a data record. In a Basic conversation, for RECEIVE_AND_WAIT with the fill parameter set to AP_LL, this value indicates that the local TP has received a complete logical record or the end of a logical record. Upon receiving this value, the local TP normally reissues [MC_]RECEIVE_AND_WAIT or issues another receive verb. If the partner TP has sent more data, the local TP begins to receive a new unit of data. Otherwise, the local TP examines status information, if primary_rc contains AP_OK and what_rcvd contains AP_SEND, AP_CONFIRM_SEND, AP_CONFIRM_DEALLOCATE, or AP_CONFIRM_WHAT_RECEIVED. See "Return codes" later in this section for the next action the local TP normally takes. If primary_rc contains AP_DEALLOC_NORMAL, the conversation has been deallocated in response to [MC_]DEALLOCATE issued by the partner TP.
		AP_DATA_INCOMPLETE indicates, for MC_RECEIVE_AND_WAIT, in a Mapped conversation, that the local TP has received an incomplete data record. The max_len parameter specified a value less than the length of the data record (or less than the remainder of the data record if this is not the first receive verb to read the record). In a Basic conversation, for RECEIVE_AND_WAIT with fill set to AP_LL, this value indicates that the local TP has received an incomplete logical record. Upon receiving this value, the local TP normally reissues [MC_]RECEIVE_AND_WAIT (or issues another receive verb) to receive the next part of the record.
		AP_NONE indicates that the TP did not receive data or conversation status indicators.
		AP_SEND indicates, for the partner TP, that the conversation has entered RECEIVE state. For the local TP, the conversation is now in SEND state. Upon receiving this value, the local TP normally uses [MC_]SEND_DATA to begin sending data.
rtn_status		Supplied parameter; indicates whether both data and conversation status indicators should be returned within one API call. Use AP_NO to specify that indicators should be returned individually on separate invocations of the verb.
		Use AP_YES to specify that indicators should be returned together, provided both are available. Both can be returned when the receive buffer is large enough to hold all of the data that precedes the status indicator and when the following is true: For a Mapped conversation, the data is the last data record before the status indicator. For a Basic conversation, the fill parameter specifies BUFFER or LL, and the data is the last logical record before the status indicator.
fill		Supplied parameter; used in a Basic conversation to specify how the local TP receives data. It is used only by RECEIVE_AND_WAIT. The following are allowed values: Use AP_BUFFER to specify that the local TP receives data until the number of bytes specified by max_len is reached or until the end of the data. Data is received without regard for the logical-record format. Use AP_LL to specify that data is received in logical-record format. The data received can be a complete logical record, a max_len byte portion of a logical record, or the end of a logical record.
rts_rcvd		Returned parameter; contains the request-to-send indicator. Possible values are: AP_YES indicates that the partner TP has issued [MC_]REQUEST_TO_SEND, which requests that the local TP change the conversation to RECEIVE state. AP_NO indicates that the partner TP has not issued [MC_]REQUEST_TO_SEND. For an explanation of why this indicator can be received by receive verbs, see "[MC_]REQUEST_TO_SEND" later in this chapter.
max_len		Supplied parameter; indicates the maximum number of bytes of data the local TP can receive. The range is from 0 through 65,535. For the Windows NT operating system and the Windows graphical environment, this value must not exceed the length of the buffer to contain the received data. For the OS/2 operating system, the offset of dptr plus the value of max_len must not exceed the size of the data segment.
dlen		Returned parameter; indicates the number of bytes of data received. Data is stored in the buffer specified by dptr. A length of 0 indicates that no data was received.
dptr		Supplied parameter; provides the address of the buffer to contain the data received by the local TP. For the Windows NT operating system and the Windows graphical environment, the data buffer can reside in a static data area or in a globally allocated area. The data buffer must fit entirely within this area. For the OS/2 operating system, the data buffer must reside on an unnamed, shared segment, which is allocated by the DosAllocSeg function with Flags equal to 1. The data buffer must fit entirely on the data segment. For the Windows environment, the data buffer can reside in a static data area or in a globally allocated area. The data buffer must fit entirely within this area.
Return Codes

AP_OK

Primary return code; the verb executed successfully.

When rtn_status is AP_YES, the preceding return code or one of the following return codes may be returned.

AP_DATA_COMPLETE_SEND

Primary return code; this is a combination of AP_DATA_COMPLETE and AP_SEND.

AP_DATA_COMPLETE_CONFIRM_SEND

Primary return code; this is a combination of AP_DATA_COMPLETE and AP_CONFIRM_SEND.

AP_DATA_COMPLETE_CONFIRM

Primary return code; this is a combination of AP_DATA_COMPLETE and AP_CONFIRM_WHAT_RECEIVED.

AP_DATA_COMPLETE_CONFIRM_DEALL

Primary return code; this is a combination of AP_DATA_COMPLETE and AP_CONFIRM_DEALLOCATE.

The following combined values are for Basic conversations only:

AP_DATA_SEND

Primary return code; this is a combination of AP_DATA and AP_SEND.

AP_DATA_CONFIRM_SEND

Primary return code; this is a combination of AP_DATA and AP_CONFIRM_SEND.

AP_DATA_CONFIRM

Primary return code; this is a combination of AP_DATA and AP_CONFIRM_WHAT_RECEIVED.

AP_DATA_CONFIRM_DEALLOCATE

Primary return code; this is a combination of AP_DATA and AP_CONFIRM_DEALLOCATE.

AP_DEALLOC_NORMAL

Primary return code; the partner TP has deallocated the conversation without requesting confirmation and issued [MC_]DEALLOCATE with dealloc_type set to one of the following:

AP_CONFIRM_SYNC_LEVEL.

AP_FLUSH.

AP_SYNC_LEVEL with the synchronization level of the conversation specified as AP_NONE.

If rtn_status is AP_YES, examine what_rcvd also.

AP_PARAMETER_CHECK

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

AP_BAD_CONV_ID

Secondary return code; the value of conv_id did not match a conversation identifier assigned by APPC.

AP_BAD_TP_ID

Secondary return code; the value of tp_id did not match a TP identifier assigned by APPC.

AP_BAD_RETURN_STATUS_WITH_DATA

Secondary return code; the specified rtn_status value was not recognized by APPC.

AP_INVALID_DATA_SEGMENT

Secondary return code; the length specified for the data buffer was longer than the segment allocated to contain the buffer.

AP_RCV_AND_WAIT_BAD_FILL

Secondary return code; for Basic conversations, fill was set to an invalid value.

AP_STATE_CHECK

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

AP_RCV_AND_WAIT_BAD_STATE

Secondary return code; the conversation was not in RECEIVE or SEND state when the TP issued this verb.

AP_RCV_AND_WAIT_NOT_LL_BDY

Secondary return code; for Basic conversations, the conversation was in SEND state; the TP began but did not finish sending a logical record.

AP_ALLOCATION_ERROR

Primary return code; APPC has failed to allocate a conversation. The conversation state is set to RESET.

This code may be returned through a verb issued after [MC_]ALLOCATE.

AP_ALLOCATION_FAILURE_NO_RETRY

Secondary return code; the conversation cannot be allocated because of a permanent condition, such as a configuration error or session protocol error. To determine the error, the system administrator should examine the error log file. Do not retry the allocation until the error has been corrected.

AP_ALLOCATION_FAILURE_RETRY

Secondary return code; the conversation could not be allocated because of a temporary condition, such as a link failure. The reason for the failure is logged in the system error log. Retry the allocation.

AP_CONVERSATION_TYPE_MISMATCH

Secondary return code; the partner LU or TP does not support the conversation type (Basic or Mapped) specified in the allocation request.

AP_PIP_NOT_ALLOWED

Secondary return code; the allocation request specified PIP data, but either the partner TP does not require this data, or the partner LU does not support it.

AP_PIP_NOT_SPECIFIED_CORRECTLY

Secondary return code; the partner TP requires PIP data, but the allocation request specified either no PIP data or an incorrect number of parameters.

AP_SECURITY_NOT_VALID

Secondary return code; the user ID or password specified in the allocation request was not accepted by the partner LU.

AP_SYNC_LEVEL_NOT_SUPPORTED

Secondary return code; the partner TP does not support the sync_level (AP_NONE or AP_CONFIRM_SYNC_LEVEL) specified in the allocation request, or the sync_level was not recognized.

AP_TP_NAME_NOT_RECOGNIZED

Secondary return code; the partner LU does not recognize the TP name specified in the allocation request.

AP_TRANS_PGM_NOT_AVAIL_NO_RETRY

Secondary return code; the remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition is permanent. The reason for the error may be logged on the remote node. Do not retry the allocation until the error has been corrected.

AP_TRANS_PGM_NOT_AVAIL_RETRY

Secondary return code; the remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition may be temporary, such as a time-out. The reason for the error may be logged on the remote node. Retry the allocation.

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

The system administrator should examine the error log to determine the reason for the ABEND.

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

When this return code is used with [MC_]ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there isn't a node available that can satisfy the [MC_]ALLOCATE request.

When [MC_]ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:

X'F0000001'

Secondary return code; no nodes have been started.

X'F0000002'

Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:

The node with the local LU is not started.

The local LU is not configured.

AP_CONV_FAILURE_NO_RETRY

Primary return code; the conversation was terminated because of a permanent condition, such as a session protocol error. The system administrator should examine the system error log to determine the cause of the error. Do not retry the conversation until the error has been corrected.

AP_CONV_FAILURE_RETRY

Primary return code; the conversation was terminated because of a temporary error. Restart the TP to see if the problem occurs again. If it does, the system administrator should examine the error log to determine the cause of the error.

AP_CONVERSATION_TYPE_MIXED

Primary return code; the TP has issued both Basic and Mapped conversation verbs. Only one type can be issued in a single conversation.

AP_INVALID_VERB_SEGMENT

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

AP_PROG_ERROR_NO_TRUNC

Primary return code; the partner TP has issued one of the following verbs while the conversation was in SEND state:

SEND_ERROR with err_type set to AP_PROG

MC_SEND_ERROR

Data was not truncated.

AP_PROG_ERROR_PURGING

Primary return code; while in RECEIVE, PENDING, PENDING_POST (Windows NT and OS/2 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state, the partner TP issued one of the following verbs:

SEND_ERROR with err_type set to AP_PROG

MC_SEND_ERROR

Data sent but not yet received is purged.

AP_PROG_ERROR_TRUNC

Primary return code; in SEND state, after sending an incomplete logical record, the partner TP issued SEND_ERROR with err_type set to AP_PROG. The local TP may have received the first part of the logical record through a receive verb.

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

AP_CONV_BUSY

Primary return code; there can only be one outstanding conversation verb at a time on any conversation. This may occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same conv_id.

AP_THREAD_BLOCKING

Primary return code; the calling thread is already in a blocking call.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

The following primary return code is for Mapped conversations and is returned only by MC_RECEIVE_AND_WAIT:

AP_DEALLOC_ABEND

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner TP issued MC_DEALLOCATE with dealloc_type set to AP_ABEND.

The partner TP encountered an ABEND, causing the partner LU to send an MC_DEALLOCATE request.

The following primary return codes are for Basic conversations and are returned only by RECEIVE_AND_WAIT:

AP_DEALLOC_ABEND_PROG

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner TP has issued DEALLOCATE with dealloc_type set to AP_ABEND_PROG.

The partner TP has encountered an ABEND, causing the partner LU to send a DEALLOCATE request.

AP_DEALLOC_ABEND_SVC

Primary return code; the conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_SVC.

AP_DEALLOC_ABEND_TIMER

Primary return code; the conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_TIMER.

AP_SVC_ERROR_NO_TRUNC

Primary return code; while in SEND state, the partner TP (or partner LU) issued SEND_ERROR with err_type set to AP_SVC. Data was not truncated.

AP_SVC_ERROR_PURGING

Primary return code; the partner TP (or partner LU) issued SEND_ERROR with err_type set to AP_SVC while in RECEIVE, PENDING_POST (Windows NT and OS/2 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state. Data sent to the partner TP may have been purged.

AP_SVC_ERROR_NO_TRUNC

Primary return code; while in SEND state, after sending an incomplete logical record, the partner TP (or partner LU) issued SEND_ERROR. The local TP may have received the first part of the logical record.

Remarks

A local TP receives data by issuing a receive verb until it finishes receiving a complete unit of data. The data received may be:

One data record transmitted in a Mapped conversation.

One logical record transmitted in a Basic conversation.

A buffer of data received independent of its logical-record format in a Basic conversation.

The local TP may need to issue the receive verb several times in order to receive a complete unit of data. Once a complete unit of data has been received, the local TP can manipulate it.

The receive verbs are [MC_]RECEIVE_AND_POST (Windows NT and OS/2 operating systems), [MC_]RECEIVE_AND_WAIT, and [MC_]RECEIVE_IMMEDIATE.

The local TP issues the receive verb again. This has one of the following effects:

If the partner TP has sent more data, the local TP begins to receive a new unit of data.

If the partner TP has finished sending data or is waiting for confirmation, status information (available through the what_rcvd parameter) indicates the next action the local TP normally takes.

The conversation must be in RECEIVE or SEND state when the TP issues this verb.

Issuing the Verb in SEND State

Issuing [MC_]RECEIVE_AND_WAIT while the conversation is in SEND state has the following effects:

The local LU sends the information in its send buffer and a SEND indicator to the partner TP.

The conversation changes to RECEIVE state; the local TP waits for the partner TP to send data.

State Change

The new conversation state is determined by the following factors:

The state the conversation is in when the TP issues the verb.

The primary_rc parameter.

The what_rcvd parameter if primary_rc contains AP_OK.

Verb Issued in SEND State

The following table details the state changes when [MC_]RECEIVE_AND_WAIT is issued in SEND state and primary_rc is AP_OK.

what_rcvd		New state
AP_CONFIRM_DEALLOCATE		CONFIRM_DEALLOCATE
AP_DATA_COMPLETE_CONFIRM_DEALL		CONFIRM_DEALLOCATE
AP_DATA_CONFIRM_DEALLOCATE		CONFIRM_DEALLOCATE
AP_CONFIRM_SEND		CONFIRM_SEND
AP_DATA_COMPLETE_CONFIRM_SEND		CONFIRM_SEND
AP_DATA_CONFIRM_SEND		CONFIRM_SEND
AP_CONFIRM_WHAT_RECEIVED		CONFIRM
AP_DATA_COMPLETE_CONFIRM		CONFIRM
AP_DATA_CONFIRM		CONFIRM
AP_DATA		RECEIVE
AP_DATA_COMPLETE		RECEIVE
AP_DATA_INCOMPLETE		RECEIVE
AP_SEND		NO CHANGE
AP_DATA_COMPLETE_SEND		SEND_PENDING
The following table details the state changes when [MC_]RECEIVE_AND_WAIT is issued in RECEIVE state and primary_rc is not AP_OK.

primary_rc		New state
AP_ALLOCATION_ERROR		RESET
AP_CONV_FAILURE_RETRY		RESET
AP_CONV_FAILURE_NO_RETRY		RESET
AP_DEALLOC_ABEND		RESET
AP_DEALLOC_ABEND_PROG		RESET
AP_DEALLOC_ABEND_SVC		RESET
ap_dealloc_abend_timer		RESET
AP_dealloc_normal		RESET
AP_prog_Error_Purging		RECEIVE
AP_prog_error_no_TRUNC		RECEIVE
AP_Svc_error_purging		RECEIVE
ap_svc_error_no_TRUNC		RECEIVE
Verb Issued in RECEIVE State

The following table details the state changes when [MC_]RECEIVE_AND _WAIT is issued in RECEIVE state and primary_rc is AP_OK.

what_rcvd		New state
AP_CONFIRM_DEALLOCATE		CONFIRM_DEALLOCATE
AP_DATA_COMPLETE_CONFIRM_DEALL		CONFIRM_DEALLOCATE
AP_DATA_CONFIRM_DEALLOCATE		CONFIRM_DEALLOCATE
AP_CONFIRM_SEND		CONFIRM_SEND
AP_DATA_COMPLETE_CONFIRM_SEND		CONFIRM_SEND
AP_DATA_CONFIRM_SEND		CONFIRM_SEND
AP_CONFIRM_WHAT_RECEIVED		CONFIRM
AP_DATA_COMPLETE_CONFIRM		CONFIRM
AP_DATA_CONFIRM		CONFIRM
AP_DATA		NO CHANGE
AP_DATA_COMPLETE		NO CHANGE
AP_DATA_INCOMPLETE		NO CHANGE
AP_SEND		SEND
AP_DATA_COMPLETE_SEND		SEND_PENDING
The following table details the state changes when [MC_]RECEIVE_AND_WAIT is issued in RECEIVE state and primary_rc is not AP_OK.

primary_rc		New state
AP_ALLOCATION_ERROR		RESET
AP_CONV_FAILURE_RETRY		RESET
AP_CONV_FAILURE_NO_RETRY		RESET
AP_DEALLOC_ABEND		RESET
AP_DEALLOC_ABEND_PROG		RESET
AP_DEALLOC_ABEND_SVC		RESET
AP_DEALLOC_ABEND_TIMER		RESET
AP_DEALLOC_NORMAL		RESET
AP_PROG_ERROR_PURGING		NO CHANGE
AP_PROG_ERROR_NO_TRUNC		NO CHANGE
AN_SVC_ERROR_PURGING		NO CHANGE
AN_SVC_ERROR_NO_TRUNC		NO CHANGE
AP_PROG_ERROR_TRUNC		NO CHANGE
AP_SVC_ERROR_TRUNC		NO CHANGE
RECEIVE_AND_WAIT End of Data

In Basic conversations, if the local TP issues RECEIVE_AND_WAIT and sets fill to AP_BUFFER, the receipt of the data ends when max_len or the end of the data is reached. The end of the data is indicated by either:

A primary_rc parameter with a value other than AP_OK (for example, AP_DEALLOC_NORMAL).

A what_rcvd parameter with one of the following values:

AP_SEND

AP_CONFIRM_SEND

AP_CONFIRM_DEALLOCATE

AP_CONFIRM_WHAT_RECEIVED

AP_DATA_CONFIRM_SEND

AP_DATA_CONFIRM_DEALLOCATE

AP_DATA_CONFIRM

To determine if the end of the data has been reached, the local TP reissues RECEIVE_AND_WAIT. If the new primary_rc contains AP_OK and what_rcvd contains AP_DATA, the end of the data has not been reached. If, however, the end of the data has been reached, primary_rc or what_rcvd will indicate the cause of the end of the data.

[MC_]RECEIVE_AND_WAIT waits for data or an indicator to be sent by the partner TP. If you need the local TP to operate continuously, use [MC_]RECEIVE_IMMEDIATE instead.

By issuing [MC_]RECEIVE_AND_WAIT with max_len set to 0, the local TP can determine whether the partner TP has data to send, seeks confirmation, or has changed the conversation state.


[MC_]RECEIVE_IMMEDIATE
APPC Conversation Verbs	13 of 18

[MC_]RECEIVE_IMMEDIATE

Receives any data currently available from the partner TP. If no data is available, the local TP does not wait. To avoid blocking the conversation, the Windows NT and Windows version 3.x systems can issue MC_RECEIVE_AND_WAIT in conjunction with WinAsyncAPPC. For OS/2 systems, use MC_RECEIVE_AND_POST.

Syntax

For a Mapped conversation:

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
what_rcvd	unsigned short int
rtn_status	unsigned char
reserv4	unsigned char
rts_rcvd	unsigned char
reserv5	unsigned char
max_len	unsigned short int
dlen	unsigned short int
dptr	unsigned char far *
reserv6	unsigned char [5]
For a Basic conversation:

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
what_rcvd	unsigned short int
rtn_status	unsigned char
fill	unsigned char
rts_rcvd	unsigned char
reserv4	unsigned char
max_len	unsigned short int
dlen	unsigned short int
dptr	unsigned char far *
reserv5	unsigned char [5]
Parameter		Description
opcode		Supplied parameter; allowed values include AP_M_RECEIVE _IMMEDIATE for MC_RECEIVE_IMMEDIATE and AP_B_RECEIVE_IMMEDIATE for RECEIVE_IMMEDIATE.
opext		Supplied parameter; allowed values include AP_MAPPED _CONVERSATION for MC_RECEIVE_IMMEDIATE and AP_BASIC_CONVERSATION for RECEIVE_IMMEDIATE.
tp_id		Supplied parameter; identifies the local TP. The value of this parameter is returned by TP_STARTED in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
conv_id		Supplied parameter; provides the conversation identifier. The value of this parameter is returned by [MC_]ALLOCATE in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
what_rcvd		Returned parameter; contains information received with the incoming data: AP_CONFIRM_DEALLOCATE indicates that the partner TP has issued [MC_]DEALLOCATE with dealloc_type set to AP_SYNC_LEVEL, and the conversation's synchronization level, established by [MC_]ALLOCATE, is AP_CONFIRM_SYNC_LEVEL. Upon receiving this value, the local TP normally issues [MC_]CONFIRMED.
		AP_CONFIRM_SEND indicates that the partner TP has issued [MC_]PREPARE_TO_RECEIVE with ptr_type set to AP_SYNC_LEVEL, and the conversation's synchronization level, established by [MC_]ALLOCATE, is AP_CONFIRM_SYNC_LEVEL. Upon receiving this value, the local TP normally issues [MC_]CONFIRMED, and begins to send data.
		AP_CONFIRM_WHAT_RECEIVED indicates that the partner TP has issued [MC_]CONFIRM. Upon receiving this value, the local TP normally issues [MC_]CONFIRMED.
		AP_DATA is returned for Basic conversations, by RECEIVE_IMMEDIATE if fill is set to AP_BUFFER. The local TP received data until max_len or end of data was reached. For more information, see "RECEIVE_IMMEDIATE End of Data" later in this section.
		AP_DATA_COMPLETE indicates, for MC_RECEIVE_IMMEDIATE in Mapped conversations, that the local TP has received a complete data record or the last part of a data record. For RECEIVE_IMMEDIATE with fill set to AP_LL in Basic conversations, this value indicates that the local TP has received a complete logical record or the end of a logical record. Upon receiving this value, the local TP normally reissues [MC_]RECEIVE_IMMEDIATE or issues another receive verb. If the partner TP has sent more data, the local TP begins to receive a new unit of data. Otherwise, the local TP examines status information if primary_rc contains AP_OK and what_rcvd contains any of these values: AP_SEND AP_CONFIRM_SEND AP_CONFIRM_DEALLOCATE AP_CONFIRM_WHAT_RECEIVED See the description of the value in "Return Codes" later in this section for the next action the local TP normally takes. If primary_rc contains AP_DEALLOC_NORMAL, the conversation has been deallocated in response to [MC_]DEALLOCATE issued by the partner TP.
		AP_DATA_INCOMPLETE indicates for MC_RECEIVE_IMMEDIATE, in Mapped conversations, that the local TP has received an incomplete data record. The max_len parameter specified a value less than the length of the data record (or less than the remainder of the data record if this is not the first receive verb to read the record). For RECEIVE_IMMEDIATE with fill set to AP_LL in Basic conversations, this value indicates that the local TP has received an incomplete logical record. Upon receiving this value, the local TP normally reissues [MC_]RECEIVE_IMMEDIATE (or issues another receive verb) to receive the next part of the record.
		AP_NONE indicates that the TP did not receive data or conversation status indicators.
		AP_SEND indicates, for the partner TP, the conversation has entered RECEIVE state. For the local TP, the conversation is now in SEND state. Upon receiving this value, the local TP normally uses [MC_]SEND_DATA to begin sending data.
rtn_status		Supplied parameter; indicates whether both data and conversation status indicators should be returned within one API call. Use AP_NO to specify that indicators should be returned individually on separate invocations of the verb. Use AP_YES to specify that indicators should be returned together, provided both are available. Both can be returned when the receive buffer is large enough to hold all of the data that precedes the status indicator and when the following is true: For a Mapped conversation, the data is the last data record before the status indicator. For a Basic conversation, fill specifies either BUFFER or LL, and the data is the last logical record before the status indicator.
fill		Supplied parameter; specifies the manner in which the local TP receives data. It is used only for RECEIVE_IMMEDIATE. Use AP_BUFFER to indicate that the local TP receives data until the number of bytes specified by max_len is reached or until end of data. Data is received without regard for the logical-record format. Use AP_LL to indicate that data is received in logical-record format. The data received can be a complete logical record, a max_len byte portion of a logical record, or the end of a logical record.
rts_rcvd		Returned parameter; contains the request-to-send indicator. Possible values are: AP_YES indicates that the partner TP has issued [MC_]REQUEST_TO_SEND, which requests that the local TP change the conversation to RECEIVE state. AP_NO indicates that the partner TP has not issued [MC_]REQUEST_TO_SEND. For an explanation of why this indicator can be received by receive verbs, see "[MC_]REQUEST_TO_SEND" later in this chapter.
max_len		Supplied parameter; indicates the maximum number of bytes of data the local TP can receive. The range is from 0 through 65, 535. For the Windows NT operating system and the Windows graphical environment, this value must not exceed the length of the buffer to contain the received data. For the OS/2 operating system, the offset of dptr plus the value of max_len must not exceed the size of the data segment.
dlen		Returned parameter; provides the number of bytes of data received. Data is stored in a buffer specified by dptr. A length of 0 indicates that no data was received.
dptr		Supplied parameter; this is the address of the buffer to contain the data received by the local TP. For the Windows NT operating system and the Windows graphical environment, the data buffer can reside in a static data area or in a globally allocated area. The data buffer must fit entirely within this area. For the OS/2 operating system, the data buffer must reside on an unnamed, shared segment, which is allocated by the function DosAllocSeg with Flags equal to 1. The data buffer must fit entirely on the data segment.
Return Codes

AP_OK

Primary return code; the verb executed successfully.

When rtn_status is AP_YES, the preceding return code or one of the following return codes may be returned.

AP_DATA_COMPLETE_SEND

Primary return code; this is a combination of AP_DATA_COMPLETE and AP_SEND.

AP_DATA_COMPLETE_CONFIRM_SEND

Primary return code; this is a combination of AP_DATA_COMPLETE and AP_CONFIRM_SEND.

AP_DATA_COMPLETE_CONFIRM

Primary return code; this is a combination of AP_DATA_COMPLETE and AP_CONFIRM_WHAT_RECEIVED.

AP_DATA_COMPLETE_CONFIRM_DEALL

Primary return code; this is a combination of AP_DATA_COMPLETE and AP_CONFIRM_DEALLOCATE.

The following combined values are for Basic conversations only:

AP_DATA_SEND

Primary return code; this is a combination of AP_DATA and AP_SEND.

AP_DATA_CONFIRM_SEND

Primary return code; this is a combination of AP_DATA and AP_CONFIRM_SEND.

AP_DATA_CONFIRM

Primary return code; this is a combination of AP_DATA and AP_CONFIRM_WHAT_RECEIVED.

AP_DATA_CONFIRM_DEALLOCATE

Primary return code; this is a combination of AP_DATA and AP_CONFIRM_DEALLOCATE.

AP_UNSUCCESSFUL

Primary return code; no data is immediately available from the partner TP.

AP_DEALLOC_NORMAL

Primary return code; the partner TP has deallocated the conversation without requesting confirmation. The partner TP issued [MC_]DEALLOCATE with dealloc_type set to one of the following:

AP_FLUSH.

AP_SYNC_LEVEL with the synchronization level of the conversation specified as AP_NONE.

If rtn_status is AP_YES, examine what_rcvd also.

AP_PARAMETER_CHECK

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

AP_BAD_CONV_ID

Secondary return code; the value of conv_id did not match a conversation identifier assigned by APPC.

AP_BAD_TP_ID

Secondary return code; the value of tp_id did not match a TP identifier assigned by APPC.

AP_BAD_RETURN_STATUS_WITH_DATA

Secondary return code; the specified rtn_status value was not recognized by APPC.

AP_INVALID_DATA_SEGMENT

Secondary return code; the length specified for the data buffer was longer than the segment allocated to contain the buffer.

AP_RCV_IMMD_BAD_FILL

Secondary return code for a Basic conversation; the fill parameter was set to an invalid value.

AP_STATE_CHECK

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

AP_RCV_IMMD_BAD_STATE

Secondary return code; the conversation was not in RECEIVE state.

AP_ALLOCATION_ERROR

Secondary return code; APPC has failed to allocate a conversation. The conversation state is set to RESET.

This code may be returned through a verb issued after [MC_]ALLOCATE.

AP_ALLOCATION_FAILURE_NO_RETRY

Secondary return code; the conversation cannot be allocated because of a permanent condition, such as a configuration error or session protocol error. To determine the error, the system administrator should examine the error log file. Do not retry the allocation until the error has been corrected.

AP_ALLOCATION_FAILURE_RETRY

Secondary return code; the conversation could not be allocated because of a temporary condition, such as a link failure. The reason for the failure is logged in the system error log. Retry the allocation.

AP_CONVERSATION_TYPE_MISMATCH

Secondary return code; the partner LU or TP does not support the conversation type (Basic or Mapped) specified in the allocation request.

AP_PIP_NOT_ALLOWED

Secondary return code; the allocation request specified PIP data, but either the partner TP does not require this data, or the partner LU does not support it.

AP_PIP_NOT_SPECIFIED_CORRECTLY

Secondary return code; the partner TP requires PIP data, but the allocation request specified either no PIP data or an incorrect number of parameters.

AP_SECURITY_NOT_VALID

Secondary return code; the user ID or password specified in the allocation request was not accepted by the partner LU.

AP_SYNC_LEVEL_NOT_SUPPORTED

Secondary return code; the partner TP does not support the sync_level (AP_NONE or AP_CONFIRM_SYNC_LEVEL) specified in the allocation request, or the sync_level was not recognized.

AP_TP_NAME_NOT_RECOGNIZED

Secondary return code; the partner LU does not recognize the TP name specified in the allocation request.

AP_TRANS_PGM_NOT_AVAIL_NO_RETRY

Secondary return code; the remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition is permanent. The reason for the error may be logged on the remote node. Do not retry the allocation until the error has been corrected.

AP_TRANS_PGM_NOT_AVAIL_RETRY

Secondary return code; the remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition may be temporary, such as a time-out. The reason for the error may be logged on the remote node. Retry the allocation.

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

The system administrator should examine the error log to determine the reason for the ABEND.

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

When this return code is used with [MC_]ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there isn't a node available that can satisfy the [MC_]ALLOCATE request.

When [MC_]ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:

X'F0000001'

Secondary return code; no nodes have been started.

X'F0000002'

Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:

The node with the local LU is not started.

The local LU is not configured.

AP_CONV_FAILURE_NO_RETRY

Primary return code; the conversation was terminated because of a permanent condition, such as a session protocol error. The system administrator should examine the system error log to determine the cause of the error. Do not retry the conversation until the error has been corrected.

AP_CONV_FAILURE_RETRY

Primary return code; the conversation was terminated because of a temporary error. Restart the TP to see if the problem occurs again. If it does, the system administrator should examine the error log to determine the cause of the error.

AP_CONVERSATION_TYPE_MIXED

Primary return code; the TP has issued both Basic and Mapped conversation verbs. Only one type can be issued in a single conversation.

AP_INVALID_VERB_SEGMENT

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

AP_PROG_ERROR_NO_TRUNC

Primary return code; the partner TP has issued one of the following verbs while the conversation was in SEND state:

SEND_ERROR with err_type set to AP_PROG

MC_SEND_ERROR

Data was not truncated.

AP_PROG_ERROR_PURGING

Primary return code; while in RECEIVE, PENDING, PENDING_POST (Windows NT and OS/2 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state, the partner TP issued one of the following verbs:

SEND_ERROR with err_type set to AP_PROG

MC_SEND_ERROR

Data sent but not yet received is purged.

AP_PROG_ERROR_TRUNC

Primary return code; in SEND state, after sending an incomplete logical record, the partner TP issued SEND_ERROR with err_type set to AP_PROG. The local TP may have received the first part of the logical record through a receive verb.

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

AP_CONV_BUSY

Primary return code; there can only be one outstanding conversation verb at a time on any conversation. This may occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same conv_id.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

AP_DEALLOC_ABEND (for a Mapped conversation)

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner TP issued MC_DEALLOCATE with dealloc_type set to AP_ABEND.

The partner TP encountered an ABEND, causing the partner LU to send an MC_DEALLOCATE request.

AP_DEALLOC_ABEND_PROG (for a Basic conversation)

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner TP has issued DEALLOCATE with dealloc_type set to AP_ABEND_PROG.

The partner TP has encountered an ABEND, causing the partner LU to send a DEALLOCATE request.

AP_DEALLOC_ABEND_SVC (for a Basic conversation)

Primary return code; the conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_SVC.

AP_DEALLOC_ABEND_TIMER (for a Basic conversation)

Primary return code; the conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_TIMER.

AP_SVC_ERROR_NO_TRUNC (for a Basic conversation)

Primary return code; while in SEND state, the partner TP (or partner LU) issued SEND_ERROR with err_type set to AP_SVC. Data was not truncated.

AP_SVC_ERROR_PURGING (for a Basic conversation)

Primary return code; the partner TP (or partner LU) issued SEND_ERROR with err_type set to AP_SVC while in RECEIVE, PENDING_POST (Windows NT and OS/2 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state. Data sent to the partner TP may have been purged.

AP_SVC_ERROR_TRUNC (for a Basic conversation)

Primary return code; in SEND state, after sending an incomplete logical record, the partner TP (or partner LU) issued SEND_ERROR. The local TP may have received the first part of the logical record.

Remarks

The process through which the local TP receives data is as follows:

The local TP issues a receive verb until it finishes receiving a complete unit of data. The data received may be any of the following:

One data record transmitted in a Mapped conversation.

One logical record transmitted in a Basic conversation.

A buffer of data received independent of its logical-record format in a Basic conversation.

The local TP may need to issue the receive verb several times in order to receive a complete unit of data. Once a complete unit of data has been received, the local TP can manipulate it.

The receive verbs are [MC_]RECEIVE_AND_POST (Windows NT and OS/2 operating systems), [MC_]RECEIVE_AND_WAIT, and [MC_]RECEIVE_IMMEDIATE.

The local TP issues the receive verb again. This has one of the following effects:

If the partner TP has sent more data, the local TP begins to receive a new unit of data.

If the partner TP has finished sending data or is waiting for confirmation, status information (available through what_rcvd) indicates the next action the local TP normally takes.

The conversation must be in RECEIVE state when the TP issues this verb.

The new state is determined by primary_rc. If primary_rc is AP_OK, the new state is determined by what_rcvd.

The following table details the state changes when the primary_rc is AP_OK.

what_rcvd		New state
AP_CONFIRM_DEALLOCATE		CONFIRM_DEALLOCATE
AP_DATA_COMPLETE_CONFIRM_DEALL		CONFIRM_DEALLOCATE
AP_DATA_CONFIRM_DEALLOCATE		CONFIRM_DEALLOCATE
AP_CONFIRM_SEND		CONFIRM_SEND
AP_DATA_COMPLETE_CONFIRM_SEND		CONFIRM_SEND
AP_DATA_CONFIRM_SEND		CONFIRM_SEND
AP_CONFIRM_WHAT_RECEIVED		CONFIRM
AP_DATA_COMPLETE_CONFIRM		CONFIRM
AP_DATA_CONFIRM		CONFIRM
AP_DATA		NO CHANGE
AP_DATA_COMPLETE		NO CHANGE
AP_DATA_INCOMPLETE		NO CHANGE
AP_SEND		SEND
AP_DATA_COMPLETE_SEND		SEND_PENDING
The following table details the state changes when the primary_rc is not AP_OK.

primary_rc		New state
AP_ALLOCATION_ERROR		RESET
AP_CONV_FAILURE_RETRY		RESET
AP_CONV_FAILURE_NO_RETRY		RESET
AP_DEALLOC_ABEND		RESET
AP_DEALLOC_ABEND_PROG		RESET
AP_DEALLOC_ABEND_SVC		RESET
AP_DEALLOC_ABEND_TIMER		RESET
AP_DEALLOC_NORMAL		RESET
AP_PROG_ERROR_PURGING		NO CHANGE
AP_PROG_ERROR_NO_TRUNC		NO CHANGE
AN_SVC_ERROR_PURGING		NO CHANGE
AN_SVC_ERROR_NO_TRUNC		NO CHANGE
AP_PROG_ERROR_TRUNC		NO CHANGE
AP_SVC_ERROR_TRUNC		NO CHANGE
AP_UNSUCCESSFUL		NO CHANGE
RECEIVE_IMMEDIATE End of Data

If the local TP issues RECEIVE_IMMEDIATE and sets fill to AP_BUFFER, the receipt of the data ends when max_len or the end of the data is reached. The end of the data is indicated by either:

A primary_rc parameter with a value other than AP_OK (for example, AP_DEALLOC_NORMAL).

A what_rcvd parameter with one of the following values:

AP_SEND

AP_CONFIRM_SEND

AP_CONFIRM_DEALLOCATE

AP_CONFIRM_WHAT_RECEIVED

AP_DATA_CONFIRM_SEND

AP_DATA_CONFIRM_DEALLOCATE

AP_DATA_CONFIRM

To determine if the end of the data has been reached, the local TP reissues RECEIVE_IMMEDIATE. If the new primary_rc parameter contains AP_OK and what_rcvd contains AP_DATA, the end of the data has not been reached. If, however, the end of the data has been reached, primary_rc or what_rcvd will indicate the cause of the end of the data.

Testing the what_rcvd Parameter

By issuing [MC_]RECEIVE_IMMEDIATE with max_len set to 0, the local TP can determine whether the partner TP has data to send, seeks confirmation, or has changed the conversation state.


[MC_]REQUEST_TO_SEND
APPC Conversation Verbs	14 of 18

[MC_]REQUEST_TO_SEND

Notifies the partner TP that the local TP wants to send data.

For the Windows version 3.x system, Microsoft recommends that you use WinAsyncAPPC rather than the blocking version of these calls. For more information on using the Windows extension, see Chapter 6, "APPC Extensions for the Windows Environment."

Syntax

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
Parameter		Description
opcode		Supplied parameter; allowed values include AP_M_REQUEST_TO _SEND for MC_REQUEST_TO_SEND and AP_B_REQUEST _TO_SEND for REQUEST_TO_SEND.
opext		Supplied parameter; allowed values include AP_MAPPED _CONVERSATION for MC_REQUEST_TO_SEND and AP_BASIC_CONVERSATION for REQUEST_TO_SEND.
tp_id		Supplied parameter; identifies the local TP. The value of this parameter is returned by TP_STARTED in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
conv_id		Supplied parameter; provides the conversation identifier. The value of this parameter is returned by [MC_]ALLOCATE in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
Return Codes

AP_OK

Primary return code; the verb executed successfully.

AP_PARAMETER_CHECK

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

AP_BAD_CONV_ID

Secondary return code; the value of conv_id did not match a conversation identifier assigned by APPC.

AP_BAD_TP_ID

Secondary return code; the value of tp_id did not match a TP identifier assigned by APPC.

AP_STATE_CHECK

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

AP_R_T_S_BAD_STATE

Secondary return code; the conversation is not in an allowed state when the TP issued this verb.

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

The system administrator should examine the error log to determine the reason for the ABEND.

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

When this return code is used with [MC_]ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there isn't a node available that can satisfy the [MC_]ALLOCATE request.

When [MC_]ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:

X'F0000001'

Secondary return code; no nodes have been started.

X'F0000002'

Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:

The node with the local LU is not started.

The local LU is not configured.

AP_CONVERSATION_TYPE_MIXED

Primary return code; the TP has issued both Basic and Mapped conversation verbs. Only one type can be issued in a single conversation.

AP_INVALID_VERB_SEGMENT

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

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

AP_CONV_BUSY

Primary return code; there can only be one outstanding conversation verb at a time on any conversation. This may occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same conv_id.

AP_THREAD_BLOCKING

Primary return code; the calling thread is already in a blocking call.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

Remarks

The conversation can be in any of the following states when the TP issues this verb:

CONFIRM

PENDING_POST (OS/2)

RECEIVE

There is no state change.

The request-to-send notification is received by the partner program through the rts_rcvd parameter of the following verbs:

[MC_]CONFIRM

[MC_]RECEIVE_AND_POST (Windows NT and OS/2 operating systems)

[MC_]RECEIVE_AND_WAIT

[MC_]RECEIVE_IMMEDIATE

[MC_]SEND_DATA

[MC_]SEND_ERROR

It is also indicated by a primary_rc of AP_OK on [MC_]TEST_RTS.

Request-to-send notification is sent to the partner TP immediately; APPC does not wait until the send buffer fills up or is flushed. Consequently, the request-to-send notification may arrive out of sequence. For example, if the local TP is in SEND state and issues [MC_]PREPARE_TO_RECEIVE followed by [MC_]REQUEST_TO_SEND, the partner TP, in RECEIVE state, may receive the request-to-send notification before it receives the send notification. For this reason, request-to-send can be reported to a TP through a receive verb.

In response to this request, the partner TP can change the conversation to:

RECEIVE state by issuing [MC_]PREPARE_TO_RECEIVE or [MC_]RECEIVE_AND_WAIT.

PENDING_POST state by issuing [MC_]RECEIVE_AND_POST.

The partner TP can also ignore the request-to-send.

The conversation state changes to SEND for the local TP when the local TP receives one of the following values through the what_rcvd parameter of a subsequent receive verb:

AP_CONFIRM_SEND and replies with [MC_]CONFIRMED

AP_DATA_COMPLETE_CONFIRM_SEND and replies with [MC_]CONFIRMED

For a Basic conversation, AP_DATA_CONFIRM_SEND and replies with [MC_]CONFIRMED

AP_SEND

The receive verbs are [MC_]RECEIVE_AND_POST (Windows NT and OS/2 operating systems), [MC_]RECEIVE_IMMEDIATE, and [MC_]RECEIVE_AND_WAIT.


[MC_]SEND_CONVERSATION
APPC Conversation Verbs	15 of 18

[MC_]SEND_CONVERSATION

Allocates a session between the local LU and partner LU, sends data on the session, and then deallocates the session.

For the Windows version 3.x system, Microsoft recommends that you use WinAsyncAPPC rather than the blocking version of these calls. For more information on using the Windows extension, see Chapter 6, "APPC Extensions for the Windows Environment."

Syntax

For a Mapped conversation:

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
reserv3	unsigned char [8]
rtn_ctl	unsigned char
reserv4	unsigned char
conv_group_id	unsigned long int
sense_data	unsigned long int
plu_alias	unsigned char [8]
mode_name	unsigned char [8]
tp_name	unsigned char [64]
security	unsigned char
reserv6	unsigned char [11]
pwd	unsigned char [10]
user_id	unsigned char [10]
pip_dlen	unsigned short int
pip_dptr	unsigned char far *
reserv6a	unsigned char
fqplu_name	unsigned char [17]
reserv7	unsigned char [8]
dlen	unsigned short int
dptr	unsigned char far *
For a Basic conversation:

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
reserv3	unsigned char [8]
rtn_ctl	unsigned char
reserv4	unsigned char
conv_group_id	unsigned long int
sense_data	unsigned long int
plu_alias	unsigned char [8]
mode_name	unsigned char [8]
tp_name	unsigned char [64]
security	unsigned char
reserv5	unsigned char [11]
pwd	unsigned char [10]
user_id	unsigned char [10]
pip_dlen	unsigned short int
pip_dptr	unsigned char far *
reserv5a	unsigned char
fqplu_name	unsigned char [17]
reserv6	unsigned char [8]
dlen	unsigned short int
dptr	unsigned char far *
Parameter		Description
opcode		Supplied parameter; allowed values include AP_M_SEND _CONVERSATION for MC_SEND_CONVERSATION and AP_B_SEND_CONVERSATION for SEND_CONVERSATION.
opext		Supplied parameter; allowed values include AP_MAPPED _CONVERSATION for MC_SEND_CONVERSATION and AP_BASIC_CONVERSATION for SEND_CONVERSATION.
tp_id		Supplied parameter; identifies the local TP. The value of this parameter was returned by TP_STARTED.
rtn_ctl		Supplied parameter; specifies how APPC should select a session to allocate for the conversation and when the local LU should return control to the local TP. The following paragraphs describe the allowed values:
		Use AP_IMMEDIATE to specify that the LU allocates a contention-winner session, if one is immediately available, and returns control to the TP.
		Use AP_WHEN_SESSION_ALLOCATED to specify that the LU does not return control to the TP until it allocates a session or encounters one of the errors described in "Return Codes" later in this section. If the session limit is 0, the LU returns control immediately. Note that if a session is not available, the TP waits for one.
		Use AP_WHEN_SESSION_FREE to specify that the LU allocates a contention-winner or contention-loser session, if one is available or able to be activated, and returns control to the TP. If an error occurs (as described in "Return Codes" later in this section) the call will return immediately with the error in the primary_rc and secondary_rc fields.
		Use AP_WHEN_CONWINNER_ALLOC to specify that the LU does not return control until it allocates a contention-winner session or encounters one of the errors described in "Return Codes" later in this section. If the session limit is 0, the LU returns control immediately. Note that if a session is not available, the TP waits for one.
		Use AP_WHEN_CONV_GROUP_ALLOC to specify that the LU does not return control to the TP until it allocates the session specified by conv_group_id or encounters one of the errors described in "Return Codes" later in this section. If the session is not available, the TP waits for it to become free.
conv_group_id		Supplied/returned parameter; used as a supplied parameter when rtn_ctl is WHEN_CONV_GROUP_ALLOC to specify the identity of the conversation group from which the session should be allocated. When rtn_ctl specifies a different value, and the primary_rc is AP_OK, this is a returned value. The purpose of this parameter is to provide a TP with the assurance that the same session will be reallocated and therefore the conversations conducted over the session will occur in the same sequence that they were initiated.
sense_data		Returned parameter; if the primary and secondary return codes indicate an allocation error (retry or no-retry), an SNA-defined sense code is returned.
plu_alias		Supplied parameter; specifies the alias by which the partner LU is known to the local TP. This parameter must match the name of a partner LU established during configuration. The parameter is an 8-byte, type G ASCII character set that includes: Uppercase letters Numerals 0 to 9 Spaces Special characters $, #, %, and @ If the value of this parameter is fewer than 8 bytes, pad it on the right with ASCII spaces (X'20').
mode_name		Supplied parameter; specifies the name of a set of networking characteristics defined during configuration. This parameter must match the name of a mode associated with the partner LU during configuration.
		The parameter is an 8-byte EBCDIC character string. It can consist of characters from the type A EBCDIC character set, including all EBCDIC spaces. These characters are: Uppercase letters Numerals 0 to 9 Special characters $, #, and @ The first character in the string must be an uppercase letter or special character. In a Mapped conversation, the name cannot be SNASVCMG (a reserved mode name used internally by APPC). Using this name in a Basic conversation is not recommended.
tp_name		Supplied parameter; specifies the name of the invoked TP. The value of tp_name specified by [MC_]ALLOCATE in the invoking TP must match the value of tp_name specified by RECEIVE_ALLOCATE in the invoked TP. The parameter is a 64-byte, case-sensitive, EBCDIC character string. This parameter can consist of characters from the type AE EBCDIC character set. These characters are: Uppercase and lowercase letters Numerals 0 to 9 Special characters $, #, @, and period (.) If the TP name is fewer than 64 bytes, use EBCDIC spaces (X'40') to pad it on the right. The SNA convention for naming a service TP is up to 4 characters. The first character is a hexadecimal byte between X'00' and X'3F'. The other characters are from the EBCDIC AE character set.
security		Supplied parameter; specifies the information the partner LU requires in order to validate access to the invoked TP.
		Use AP_NONE to specify that the invoked TP uses no conversation security.
		Use AP_PGM to specify that the invoked TP uses conversation security and requires a user ID and password. Use user_id and pwd to supply this information. Use AP_SAME to specify that the invoked TP, invoked with a valid user ID and password, in turn invokes another TP. For example, assume that TP A invokes TP B with a valid user ID and password, and TP B in turn invokes TP C. If TP B specifies the value AP_SAME, APPC will send the LU for TP C the user ID from TP A and an already-verified indicator. This indicator indicates to TP C not to require the password (if TP C is configured to accept an already-verified indicator).
pwd		Supplied parameter; specifies the password associated with user_id. This parameter is required only if the security parameter is set to AP_PGM and must match the password for user_id that was established during configuration. This parameter is a 10-byte, case-sensitive, EBCDIC character string. It can consist of characters from the type AE EBCDIC character set. These characters are: Uppercase and lowercase letters Numerals 0 to 9 Special characters $, #, @, and period (.) If the password is fewer than 10 bytes, use EBCDIC spaces (X'40') to pad it on the right.
user_id		Supplied parameter; specifies the user ID required to access the partner TP. This parameter is required only if the security parameter is set to AP_PGM and must match one of the user IDs configured for the partner TP. The parameter can consist of characters from the type AE EBCDIC character set. These characters are: Uppercase and lowercase letters Numerals 0 to 9 Special characters $, #, @, and period (.) If the user ID is fewer than 10 bytes, use EBCDIC spaces (X'40') to pad it on the right.
pip_dlen		Supplied parameter; specifies the length of the PIP to be passed to the partner TP. The range for this parameter is from 0 through 32,767.
pip_dptr		Supplied parameter; specifies the address of the buffer containing PIP data. Use this parameter only if pip_dlen is greater than 0. PIP data can consist of initialization parameters or environmental setup information required by a partner TP or remote operating system. The PIP data must follow the GDS format. For more information, see your IBM SNA manual(s). For the Windows NT operating system and the Windows graphical environment, the data buffer can reside in a static data area or in a globally allocated area. For the OS/2 operating system, use a shared, unnamed segment for the data buffer. To allocate the segment, issue the function call DosAllocSeg with the shared indicator equal to 1. The data buffer must be entirely within the data segment.
fqlu_name		Supplied parameter; specifies the fully qualified name of the local LU. This parameter must match the fully qualified name of the local LU defined in the remote node. The parameter is made up of two type A EBCDIC character strings (each of up to 8 characters), which are the network name (NETID) and the LU name of the partner LU. The names are separated by an EBCDIC period ('.'). The NETID may be omitted, and if this is the case, the period should also be omitted. This name must be provided if no plu_alias is provided.
		Type A EBCDIC characters contain: Uppercase letters Numerals 0 to 9 Special characters $, #, and @ If the value of this parameter is fewer than 17 bytes, pad it on the right with EBCDIC spaces (X'40').
dlen		Supplied parameter; specifies the number of bytes of data to be put in the local LU's send buffer. The range for this parameter is from 0 through 65,535.
dptr		Supplied parameter; specifies the address of the buffer containing the data to be put in the local LU's send buffer. For the Windows NT operating system and the Windows graphical environment, the data buffer can reside in a static data area or in a globally allocated area. The data buffer must fit entirely within this area. For the OS/2 operating system, use a shared, unnamed segment for the data buffer. To allocate the segment, issue the function call DosAllocSeg with the shared indicator equal to 1. The data buffer must be entirely within the data segment.
Return Codes

AP_OK

Primary return code; the verb executed successfully.

AP_UNSUCCESSFUL

Primary return code; the supplied parameter rtn_ctl specified immediate return of the control to the TP (AP_IMMEDIATE), and the local LU did not have an available contention-winner session.

AP_PARAMETER_CHECK

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

AP_BAD_RETURN_CONTROL

Secondary return code; the value specified for rtn_ctl was invalid.

AP_BAD_SECURITY

Secondary return code; the value specified for security was invalid.

AP_BAD_TP_ID

Secondary return code; the value of tp_id did not match a TP identifier assigned by APPC.

AP_PIP_LEN_INCORRECT

Secondary return code; the value of pip_dlen was greater than 32,767.

AP_UNKNOWN_PARTNER_MODE

The value specified for mode_name was invalid.

AP_BAD_PARTNER_LU_ALIAS

APPC did not recognize the supplied partner_lu_alias.

AP_NO_USE_OF_SNASVCMG (for a Mapped conversation)

Secondary return code; SNASVCMG is not a valid value for mode_name.

AP_INVALID_DATA_SEGMENT (for a Mapped conversation)

Secondary return code; the PIP data or application data was longer than the allocated data segment, or the address of a data buffer was wrong.

AP_ALLOCATION_ERROR

Primary return code; APPC has failed to allocate a conversation. The conversation state is set to RESET.

This code may be returned through a verb issued after [MC_]ALLOCATE.

AP_ALLOCATION_FAILURE_NO_RETRY

Secondary return code; the conversation cannot be allocated because of a permanent condition, such as a configuration error or session protocol error. To determine the error, the system administrator should examine the error log file. Do not retry the allocation until the error has been corrected.

AP_ALLOCATION_FAILURE_RETRY

Secondary return code; the conversation could not be allocated because of a temporary condition, such as a link failure. The reason for the failure is logged in the system error log. Retry the allocation.

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

The system administrator should examine the error log to determine the reason for the ABEND.

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

When this return code is used with [MC_]ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there isn't a node available that can satisfy the [MC_]ALLOCATE request.

When [MC_]ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:

X'F0000001'

Secondary return code; no nodes have been started.

X'F0000002'

Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:

The node with the local LU is not started.

The local LU is not configured.

AP_INVALID_VERB_SEGMENT

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

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

AP_CONV_BUSY

Primary return code; there can only be one outstanding conversation verb at a time on any conversation. This may occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same conv_id.

AP_THREAD_BLOCKING

Primary return code; the calling thread is already in a blocking call.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

Remarks

This verb is issued by the invoking TP to conduct an entire conversation with the remote TP. If the remote TP rejects either the conversation initiation or the data, the invoking TP will not receive notification of the rejection.

The conversation state is RESET when the TP issues this verb. There is no state change.

Several parameters of [MC_]SEND_CONVERSATION are EBCDIC or ASCII strings. A TP can use the CSV CONVERT to translate a string from one character set to the other. For more information, see Chapter 8, "Common Service Verbs."

Normally, the value of mode_name must match the name of a mode configured for the invoked TP's node and associated during configuration with the partner LU. If one of the modes associated with the partner LU on the invoked TP's node is an implicit mode, the session established between the two LUs will be of the implicit mode when no mode name associated with the partner LU matches the value of mode_name.


[MC_]SEND_DATA
APPC Conversation Verbs	16 of 18

[MC_]SEND_DATA

Places data in the local LU's send buffer for transmission to the partner TP.

For the Windows version 3.x system, Microsoft recommends that you use WinAsyncAPPC rather than the blocking version of these calls. For more information on using the Windows extension, see Chapter 6, "APPC Extensions for the Windows Environment."

Syntax

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
rts_rcvd	unsigned char
reserv3	unsigned char
dlen	unsigned short int
dptr	unsigned char far *
type	unsigned char
reserv4	unsigned char
Parameter		Description
opcode		Supplied parameter; allowed values include AP_M_SEND_DATA for MC_SEND_DATA and AP_B_SEND_DATA for SEND_DATA.
opext		Supplied parameter; allowed values include AP_MAPPED _CONVERSATION for MC_SEND_DATA and AP_BASIC _CONVERSATION for SEND_DATA.
tp_id		Supplied parameter; identifies the local TP. The value of this parameter is returned by TP_STARTED in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
conv_id		Supplied parameter; provides the conversation identifier. The value of this parameter is returned by [MC_]ALLOCATE in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
rts_rcvd		Returned parameter; provides the request-to-send-received indicator. AP_YES indicates that the partner TP has issued [MC_]REQUEST_TO_SEND, which requests that the local TP change the conversation to RECEIVE state. To change to RECEIVE state, the local TP can use [MC_]PREPARE_TO _RECEIVE, [MC_]RECEIVE_AND_WAIT, or [MC_]RECEIVE_AND_POST (Windows NT and OS/2 operating systems). AP_NO indicates that the partner TP has not issued [MC_]REQUEST_TO_SEND.
dlen		Supplied parameter; specifies the number of bytes of data to be put in the local LU's send buffer. The range is from 0 through 65,535.
dptr		Supplied parameter; specifies the address of the buffer containing the data to be put in the local LU's send buffer. For the Windows NT operating system and the Windows graphical environment, the data buffer can reside in a static data area or in a globally allocated area. The data buffer must fit entirely within this area. For OS/2, the data buffer must reside on an unnamed, shared segment, which is allocated by the function DosAllocSeg with Flags equal to 1. The data buffer must fit entirely on the data segment.
type		Supplied parameter; allows a TP to send data and perform other functions within one API call. For example, you can combine [MC_]SEND_DATA with type set to CONFIRM to accomplish the same objective as issuing [MC_]SEND_DATA followed by [MC_]CONFIRM. AP_SEND_DATA_CONFIRM corresponds to [MC_]SEND_DATA followed by [MC_]CONFIRM. AP_SEND_DATA_FLUSH corresponds to [MC_]SEND_DATA followed by [MC_]FLUSH. AP_SEND_DATA_DEALLOC_ABEND, for a Mapped conversation, corresponds to [MC_]SEND_DATA followed by MC_DEALLOCATE with a dealloc_type of AP_ABEND For a Basic conversation, AP_SEND_DATA_DEALLOC_ABEND corresponds to [MC_]SEND_DATA followed by DEALLOCATE with a dealloc_type of AP_ABEND_PROG. AP_SEND_DATA_DEALLOC_FLUSH corresponds to [MC_]SEND_DATA followed by [MC_]DEALLOCATE with a dealloc_type of AP_FLUSH. AP_SEND_DATA_DEALLOC_SYNC_LEVEL corresponds to [MC_]SEND_DATA followed by [MC_]DEALLOCATE with a dealloc_type of AP_SYNC_LEVEL. AP_SEND_DATA_P_TO_R_FLUSH corresponds to [MC_]SEND _DATA followed by [MC_]PREPARE_TO_RECEIVE with a ptr_type of AP_FLUSH. AP_SEND_DATA_P_TO_R_SYNC_LEVEL corresponds to [MC_]SEND_DATA followed by [MC_]PREPARE_TO _RECEIVE with a ptr_type of AP_SYNC_LEVEL and locks set to AP_SHORT.
Return Codes

AP_OK

Primary return code; the verb executed successfully.

AP_PARAMETER_CHECK

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

AP_BAD_CONV_ID

Secondary return code; the value of conv_id did not match a conversation identifier assigned by APPC.

AP_BAD_LL (for a Basic conversation)

Secondary return code; the logical record length field of a logical record contained an invalid value—X'0000', X'0001', X'8000', or X'8001'. See Chapter 2, "Transaction Programs," for information on logical records.

AP_BAD_TP_ID

Secondary return code; the value of tp_id did not match a TP identifier assigned by APPC.

AP_INVALID_DATA_SEGMENT

Secondary return code; the length specified for the data buffer was longer than the segment allocated to contain the buffer.

AP_SEND_DATA_INVALID_TYPE

Secondary return code; the specified type was not recognized by APPC.

AP_SEND_DATA_CONFIRM_SYNC_NONE

Secondary return code; the type CONFIRM is not permitted for a conversation that was allocated with a sync_level of NONE.

AP_STATE_CHECK

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

AP_SEND_DATA_NOT_SEND_STATE

Secondary return code; the local TP issued [MC_]SEND_DATA, but the conversation was not in SEND state.

AP_SEND_DATA_NOT_LL_BDY (for a Basic conversation)

Secondary return code; the TP started but did not finish sending a logical record. This occurs only when the type parameter is one of the following:

AP_SEND_DATA_CONFIRM
AP_SEND_DATA_DEALLOC_FLUSH
AP_SEND_DATA_DEALLOC_SYNC_LEVEL
AP_SEND_DATA_P_TO_R_FLUSH
AP_SEND_DATA_P_TO_R_SYNC_LEVEL

AP_ALLOCATION_ERROR

Primary return code; APPC has failed to allocate a conversation. The conversation state is set to RESET.

This code may be returned through a verb issued after [MC_]ALLOCATE.

AP_ALLOCATION_FAILURE_NO_RETRY

Secondary return code; the conversation cannot be allocated because of a permanent condition, such as a configuration error or session protocol error. To determine the error, the system administrator should examine the error log file. Do not retry the allocation until the error has been corrected.

AP_ALLOCATION_FAILURE_RETRY

Secondary return code; the conversation could not be allocated because of a temporary condition, such as a link failure. The reason for the failure is logged in the system error log. Retry the allocation.

AP_CONVERSATION_TYPE_MISMATCH

Secondary return code; the partner LU or TP does not support the conversation type (Basic or Mapped) specified in the allocation request.

AP_PIP_NOT_ALLOWED

Secondary return code; the allocation request specified PIP data, but either the partner TP does not require this data, or the partner LU does not support it.

AP_PIP_NOT_SPECIFIED_CORRECTLY

Secondary return code; the partner TP requires PIP data, but the allocation request specified either no PIP data or an incorrect number of parameters.

AP_SECURITY_NOT_VALID

Secondary return code; the user ID or password specified in the allocation request was not accepted by the partner LU.

AP_SYNC_LEVEL_NOT_SUPPORTED

Secondary return code; the partner TP does not support the sync_level (AP_NONE or AP_CONFIRM_SYNC_LEVEL) specified in the allocation request, or the sync_level was not recognized.

AP_TP_NAME_NOT_RECOGNIZED

Secondary return code; the partner LU does not recognize the TP name specified in the allocation request.

AP_TRANS_PGM_NOT_AVAIL_NO_RETRY

Secondary return code; the remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition is permanent. The reason for the error may be logged on the remote node. Do not retry the allocation until the error has been corrected.

AP_TRANS_PGM_NOT_AVAIL_RETRY

Secondary return code; the remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition may be temporary, such as a time-out. The reason for the error may be logged on the remote node. Retry the allocation.

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

The system administrator should examine the error log to determine the reason for the ABEND.

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

When this return code is used with [MC_]ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there isn't a node available that can satisfy the [MC_]ALLOCATE request.

When [MC_]ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:

X'F0000001'

Secondary return code; no nodes have been started.

X'F0000002'

Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:

The node with the local LU is not started.

The local LU is not configured.

AP_CONV_FAILURE_NO_RETRY

Primary return code; the conversation was terminated because of a permanent condition, such as a session protocol error. The system administrator should examine the system error log to determine the cause of the error. Do not retry the conversation until the error has been corrected.

AP_CONV_FAILURE_RETRY

Primary return code; the conversation was terminated because of a temporary error. Restart the TP to see if the problem occurs again. If it does, the system administrator should examine the error log to determine the cause of the error.

AP_CONVERSATION_TYPE_MIXED

Primary return code; the TP has issued both Basic and Mapped conversation verbs. Only one type can be issued in a single conversation.

AP_INVALID_VERB_SEGMENT

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

AP_PROG_ERROR_PURGING

Primary return code; while in RECEIVE, PENDING, PENDING_POST (Windows NT and OS/2 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state, the partner TP issued one of the following verbs:

SEND_ERROR with err_type set to AP_PROG

MC_SEND_ERROR

Data sent but not yet received is purged.

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

AP_CONV_BUSY

Primary return code; there can only be one outstanding conversation verb at a time on any conversation. This may occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same conv_id.

AP_THREAD_BLOCKING

Primary return code; the calling thread is already in a blocking call.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

The following primary return code is returned only by MC_SEND_DATA in Mapped conversations:

AP_DEALLOC_ABEND

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner TP issued MC_DEALLOCATE with dealloc_type set to AP_ABEND.

The partner TP encountered an ABEND, causing the partner LU to send an MC_DEALLOCATE request.

The following primary return codes are returned only by SEND_DATA in Basic conversations:

AP_DEALLOC_ABEND_PROG

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner TP has issued DEALLOCATE with dealloc_type set to AP_ABEND_PROG.

The partner TP has encountered an ABEND, causing the partner LU to send a DEALLOCATE request.

AP_DEALLOC_ABEND_SVC

Primary return code; the conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_SVC.

AP_DEALLOC_ABEND_TIMER

Primary return code; the conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_TIMER.

AP_SVC_ERROR_PURGING

Primary return code; the partner TP (or partner LU) issued a SEND_ERROR verb with err_type set to AP_SVC while in RECEIVE, PENDING_POST (Windows NT and OS/2 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state. Data sent to the partner TP may have been purged.

Remarks

The conversation must be in SEND state when the TP issues this verb. State changes, based on primary_rc, are summarized in the following table.

primary_rc		New state
AP_OK		NO CHANGE
AP_ALLOCATION_ERROR		RESET
AP_CONV_FAILURE_RETRY		RESET
AP_CONV_FAILURE_NO_RETRY		RESET
AP_DEALLOC_ABEND		RESET
AP_DEALLOC_ABEND_PROG		RESET
AP_DEALLOC_ABEND_SVC		RESET
AP_DEALLOC_ABEND_TIMER		RESET
AP_PROG_ERROR_PURGING		RECEIVE
AP_SVC_ERROR_PURGING		RECEIVE
[MC_]SEND_DATA may wait indefinitely because the partner TP has not issued a receive verb. If this occurs, the send buffer may fill up.

The data collected in the local LU's send buffer is transmitted to the partner LU (and partner TP) when one of the following occurs:

The send buffer fills up.

The local TP issues [MC_]FLUSH, [MC_]CONFIRM, or [MC_]DEALLOCATE (or other verb that flushes the LU's send buffer).


[MC_]SEND_ERROR
APPC Conversation Verbs	17 of 18

[MC_]SEND_ERROR

Notifies the partner TP that the local TP has encountered an application-level error.

For the Windows version 3.x system, Microsoft recommends that you use WinAsyncAPPC rather than the blocking version of these calls. For more information on using the Windows extension, see Chapter 6, "APPC Extensions for the Windows Environment."

Syntax

For a Mapped conversation:

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
rts_rcvd	unsigned char
reserv3	unsigned char
err_dir	unsigned char
reserv4	unsigned char
reserv5	unsigned char [2]
reserv6	unsigned char [4]
For a Basic conversation:

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
rts_rcvd	unsigned char
err_type	unsigned char
err_dir	unsigned char
reserv3	unsigned char
log_dlen	unsigned short int
log_dptr	unsigned char far *
Parameter		Description
opcode		Supplied parameter; allowed values include AP_M_SEND_ERROR for MC_SEND_ERROR and AP_B_SEND_ERROR for SEND_ERROR.
opext		Supplied parameter; allowed values include AP_MAPPED_CONVERSATION for MC_SEND_ERROR and AP_BASIC_CONVERSATION for SEND_ERROR.
tp_id		Supplied parameter; identifies the local TP. The value of this parameter is returned by TP_STARTED in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
conv_id		Supplied parameter; provides the conversation identifier. The value of this parameter is returned by [MC_]ALLOCATE in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
rts_rcvd		Returned parameter; indicates whether the partner TP issued [MC_]REQUEST_TO_SEND. Possible values include: AP_YES indicates that the partner TP has issued [MC_]REQUEST_TO_SEND, which requests that the local TP change the conversation to RECEIVE state. To change to RECEIVE state, the local TP can use [MC_]PREPARE_TO_RECEIVE, [MC_]RECEIVE _AND_WAIT, or [MC_]RECEIVE_AND_POST. AP_NO indicates that the partner TP has not issued [MC_]REQUEST_TO_SEND.
err_type		Supplied parameter; for a Basic conversation, indicates the type of the error being reported—application program or service program. The parameter is used only by SEND_ERROR. AP_PROG indicates that the error is to be reported to an end-user application program. This value causes APPC to send one of the following return codes to the partner TP: AP_PROG_ERROR_NO_TRUNC AP_PROG_ERROR_PURGING AP_PROG_ERROR_TRUNC AP_SVC indicates that the error is to be reported to a service program. This value causes APPC to send one of the following return codes to the partner TP: AP_SVC_ERROR_NO_TRUNC AP_SVC_ERROR_PURGING AP_SVC_ERROR_TRUNC
err_dir		Supplied parameter; indicates whether the error is with data just received or with data that is about to be sent. Use this parameter only when the conversation is in SEND_PENDING state. The parameter is ignored otherwise. The following are allowed values: AP_RCV_DIR_ERROR indicates that the TP issued [MC_]SEND_ERROR after detecting an error associated with the data just received.
		AP_SEND_DIR_ERROR indicates that the TP issued [MC_]SEND_ERROR after detecting an error associated with data it was going to send. For example, the TP encountered an error while reading data from the disk drive.
log_dlen		Supplied parameter for Basic conversations; specifies the number of bytes of data to be sent to the error log file. The range is from 0 through 32,767. A length of 0 indicates that there is no error log data.
log_dptr		Supplied parameter for Basic conversations; specifies the address of the data buffer containing error information. The data is sent to the local error log and to the partner LU. This parameter is used by SEND_ERROR if log_dlen is greater than 0. For the Windows NT operating system and the Windows graphical environment, the data buffer can reside in a static data area or in a globally allocated area. The data buffer must fit entirely within this area. For the OS/2 operating system, the log data buffer must reside on an unnamed, shared segment, which is allocated by the function DosAllocSeg with Flags equal to 1. The log data buffer must fit entirely on the segment. The TP must format the error data as a GDS error log variable. For more information, see your IBM SNA manual(s).
Return Codes

AP_OK

Primary return code; the verb executed successfully.

AP_PARAMETER_CHECK

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

AP_BAD_CONV_ID

Secondary return code; the value of conv_id did not match a conversation identifier assigned by APPC.

AP_BAD_TP_ID

Secondary return code; the value of tp_id did not match a TP identifier assigned by APPC.

AP_BAD_ERROR_DIRECTION

Secondary return code; the specified err_dir was not recognized by APPC.

AP_INVALID_DATA_SEGMENT (for a Basic conversation)

Secondary return code; the error data for the log file was longer than the segment allocated to contain the error data, or the address of the error data buffer was wrong.

AP_SEND_ERROR_BAD_TYPE

Secondary return code; the value of err_type was invalid.

AP_SEND_ERROR_LOG_LL_WRONG

Secondary return code; the LL field of the error log GDS variable did not match the actual length of the data.

The following return codes can be generated when [MC_]SEND_ERROR is issued in any allowed state:

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

The system administrator should examine the error log to determine the reason for the ABEND.

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

When this return code is used with [MC_]ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there isn't a node available that can satisfy the [MC_]ALLOCATE request.

When [MC_]ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:

X'F0000001'

Secondary return code; no nodes have been started.

X'F0000002'

Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:

The node with the local LU is not started.

The local LU is not configured.

AP_CONV_FAILURE_NO_RETRY

Primary return code; the conversation was terminated because of a permanent condition, such as a session protocol error. The system administrator should examine the system error log to determine the cause of the error. Do not retry the conversation until the error has been corrected.

AP_CONV_FAILURE_RETRY

Primary return code; the conversation was terminated because of a temporary error. Restart the TP to see if the problem occurs again. If it does, the system administrator should examine the error log to determine the cause of the error.

AP_CONVERSATION_TYPE_MIXED

Primary return code; the TP has issued both Basic and Mapped conversation verbs. Only one type can be issued in a single conversation.

AP_INVALID_VERB_SEGMENT

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

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

AP_CONV_BUSY

Primary return code; there can only be one outstanding conversation verb at a time on any conversation. This may occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same conv_id.

AP_THREAD_BLOCKING

Primary return code; the calling thread is already in a blocking call.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

The following return codes can be generated only if [MC_]SEND_ERROR is issued in SEND:

AP_ALLOCATION_ERROR

Primary return code; APPC has failed to allocate a conversation. The conversation state is set to RESET.

This code may be returned through a verb issued after [MC_]ALLOCATE.

AP_ALLOCATION_FAILURE_NO_RETRY

Secondary return code; the conversation cannot be allocated because of a permanent condition, such as a configuration error or session protocol error. To determine the error, the system administrator should examine the error log file. Do not retry the allocation until the error has been corrected.

AP_ALLOCATION_FAILURE_RETRY

Secondary return code; the conversation could not be allocated because of a temporary condition, such as a link failure. The reason for the failure is logged in the system error log. Retry the allocation.

AP_CONVERSATION_TYPE_MISMATCH

Secondary return code; the partner LU or TP does not support the conversation type (Basic or Mapped) specified in the allocation request.

AP_PIP_NOT_ALLOWED

Secondary return code; the allocation request specified PIP data, but either the partner TP does not require this data, or the partner LU does not support it.

AP_PIP_NOT_SPECIFIED_CORRECTLY

Secondary return code; the partner TP requires PIP data, but the allocation request specified either no PIP data or an incorrect number of parameters.

AP_SECURITY_NOT_VALID

Secondary return code; the user ID or password specified in the allocation request was not accepted by the partner LU.

AP_SYNC_LEVEL_NOT_SUPPORTED

Secondary return code; the partner TP does not support the sync_level (AP_NONE or AP_CONFIRM_SYNC_LEVEL) specified in the allocation request, or the sync_level was not recognized.

AP_TP_NAME_NOT_RECOGNIZED

Secondary return code; the partner LU does not recognize the TP name specified in the allocation request.

AP_TRANS_PGM_NOT_AVAIL_NO_RETRY

Secondary return code; the remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition is permanent. The reason for the error may be logged on the remote node. Do not retry the allocation until the error has been corrected.

AP_TRANS_PGM_NOT_AVAIL_RETRY

Secondary return code; the remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition may be temporary, such as a time-out. The reason for the error may be logged on the remote node. Retry the allocation.

AP_PROG_ERROR_PURGING

Primary return code; while in RECEIVE, PENDING, PENDING_POST (Windows NT and OS/2 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state, the partner TP issued one of the following verbs:

SEND_ERROR with err_type set to AP_PROG

MC_SEND_ERROR

Data sent but not yet received is purged.

AP_DEALLOC_ABEND (for a Mapped conversation)

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner TP issued MC_DEALLOCATE with dealloc_type set to AP_ABEND.

The partner TP encountered an ABEND, causing the partner LU to send an MC_DEALLOCATE request.

The following return codes can be generated only if SEND_ERROR is issued in SEND state:

AP_DEALLOC_ABEND_PROG

Primary return code; the conversation has been deallocated for one of the following reasons:

The partner TP has issued DEALLOCATE with dealloc_type set to AP_ABEND_PROG.

The partner TP has encountered an ABEND, causing the partner LU to send a DEALLOCATE request.

AP_DEALLOC_ABEND_SVC

Primary return code; the conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_SVC.

AP_DEALLOC_ABEND_TIMER

Primary return code; the conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_TIMER.

AP_SVC_ERROR_PURGING

Primary return code; the partner TP (or partner LU) issued SEND_ERROR with err_type set to AP_SVC while in RECEIVE, PENDING_POST (Windows NT and OS/2 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state. Data sent to the partner TP may have been purged.

The following return code can be generated only if [MC_]SEND_ERROR is issued in RECEIVE state:

AP_DEALLOC_NORMAL

Primary return code; this return code does not indicate an error.

The partner TP issued [MC_]DEALLOCATE with dealloc_type set to one of the following:

AP_FLUSH

AP_SYNC_LEVEL with the synchronization level of the conversation specified as AP_NONE

Remarks

The conversation can be in any state except RESET when the TP issues this verb. The conversation state must be SEND_PENDING if err_dir is used.

The local TP sends the error notification immediately to the partner TP; it does not hold the information in the local LU's send buffer.

Upon successful execution of this verb, the conversation is in SEND state for the local TP and in RECEIVE state for the partner TP.

The new state is determined by primary_rc. Possible state changes are summarized in the following table.

primary_rc		New state
AP_OK		SEND
AP_ALLOCATION_ERROR		RESET
AP_CONV_FAILURE_RETRY		RESET
AP_CONV_FAILURE_NO_RETRY		RESET
AP_DEALLOC_ABEND		RESET
AP_DEALLOC_ABEND_PROG		RESET
AP_DEALLOC_ABEND_SVC		RESET
AP_DEALLOC_ABEND_TIMER		RESET
AP_DEALLOC_NORMAL		RESET
AP_PROG_ERROR_PURGING		RECEIVE
AP_SVC_ERROR_PURGING		RECEIVE
If the conversation is in RECEIVE state when the TP issues [MC_]SEND_ERROR, incoming data is purged by APPC. This data includes:

Data sent by [MC_]SEND_DATA.

Return code indicators.

Confirmation requests.

Deallocation requests.

APPC does not purge an incoming request-to-send indicator. APPC replaces purged incoming return code indicators with other return codes. The primary return code AP_OK replaces the following purged return code indicators:

AP_PROG_ERROR_NO_TRUNC

AP_PROG_ERROR_PURGING

AP_PROG_ERROR_TRUNC

AP_SVC_ERROR_NO_TRUNC

AP_SVC_ERROR_PURGING

AP_SVC_ERROR_TRUNC

The primary return code AP_DEALLOC_NORMAL replaces the following purged return code indicators:

AP_ALLOCATION_ERROR

AP_ALLOCATION_FAILURE_NO_RETRY

AP_ALLOCATION_FAILURE_RETRY

AP_CONVERSATION_TYPE_MISMATCH

AP_PIP_NOT_ALLOWED

AP_PIP_NOT_SPECIFIED_CORRECTLY

AP_SECURITY_NOT_VALID

AP_SYNC_LEVEL_NOT_SUPPORTED

AP_TP_NAME_NOT_RECOGNIZED

AP_TRANS_PGM_NOT_AVAIL_NO_RETRY

AP_TRANS_PGM_NOT_AVAIL_RETRY

AP_DEALLOC_ABEND

AP_DEALLOC_ABEND_PROG

AP_DEALLOC_ABEND_SVC

AP_DEALLOC_ABEND_TIMER

When the conversation is in SEND_PENDING state, APPC reports the following return codes to the partner TP based on the value in err_dir:

AP_PROG_ERROR_PURGING

The local TP issued [MC_]SEND_ERROR with RECEIVE as the err_dir.

AP_PROG_ERROR_NO_TRUNC

The local TP issued [MC_]SEND_ERROR with SEND as the err_dir.

The following return codes apply to Basic conversations only:

AP_SVC_ERROR_PURGING

The local TP issued SEND_ERROR with RECEIVE as the err_dir.

AP_SVC_ERROR_NO_TRUNC

The local TP issued SEND_ERROR with SEND as the err_dir.


[MC_]TEST_RTS
APPC Conversation Verbs	18 of 18

[MC_]TEST_RTS

Determines whether a request-to-send notification has been received from the partner TP.

Syntax

opcode	unsigned short int
opext	unsigned char
reserv2	unsigned char
primary_rc	unsigned short int
secondary_rc	unsigned long int
tp_id	unsigned char [8]
conv_id	unsigned long int
reserv3	unsigned char
Parameter		Description
opcode		Supplied parameter; allowed values include AP_M_TEST _RTS for MC_TEST_RTS and AP_B_TEST_RTS for TEST_RTS.
opext		Supplied parameter; allowed values include AP_MAPPED _CONVERSATION for MC_TEST_RTS and AP_BASIC _CONVERSATION for TEST_RTS.
tp_id		Supplied parameter; identifies the local TP. The value of this parameter was returned by TP_STARTED in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
conv_id		Supplied parameter; provides the conversation identifier. The value of this parameter was returned by [MC_]ALLOCATE in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP.
Return Codes

AP_OK

Primary return code; the verb executed successfully.

AP_UNSUCCESSFUL

Primary return code; request-to-send notification has not been received.

AP_PARAMETER_CHECK

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

AP_BAD_CONV_ID

Secondary return code; the value of conv_id did not match a conversation identifier assigned by APPC.

AP_BAD_TP_ID

Secondary return code; the value of tp_id did not match a TP identifier assigned by APPC.

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

The system administrator should examine the error log to determine the reason for the ABEND.

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

When this return code is used with [MC_]ALLOCATE, it may indicate that no communications subsystem could be found to support the local LU. (For example, the local LU alias specified with TP_STARTED is incorrect or has not been configured.) Note that if lu_alias or mode_name is fewer than eight characters, you must ensure that these fields are filled with spaces to the right. This error is returned if these parameters are not filled with spaces, since there isn't a node available that can satisfy the [MC_]ALLOCATE request.

When [MC_]ALLOCATE produces this return code for an SNA Server system configured with multiple nodes, there are two secondary return codes as follows:

X'F0000001'

Secondary return code; no nodes have been started.

X'F0000002'

Secondary return code; at least one node has been started, but the local LU (when TP_STARTED is issued) is not configured on any active nodes. The problem could be either of the following:

The node with the local LU is not started.

The local LU is not configured.

AP_CONVERSATION_TYPE_MIXED

Primary return code; the TP has issued both Basic and Mapped conversation verbs. Only one type can be issued in a single conversation.

AP_INVALID_VERB_SEGMENT

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

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

AP_CONV_BUSY

Primary return code; there can only be one outstanding conversation verb at a time on any conversation. This may occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same conv_id.

AP_THREAD_BLOCKING

Primary return code; the calling thread is already in a blocking call.

AP_UNEXPECTED_DOS_ERROR

Primary return code; the operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

Remarks

The conversation can be in any state except RESET when the TP issues this verb.

There is no state change.


APPC Extensions for the Windows Environment
Chapter 6	1 of 10

APPC Extensions for the Windows Environment

This chapter describes API extensions to the Windows APPC that allow asynchronous communication. Asynchronous communication occurs when a function returns before the request completes. The application is notified when the request completes.

The extensions described in this chapter have been designed for all implementations and versions of the Microsoft Windows graphical environment version 3.0 and later with the exception of real mode 3.0. They provide support for maximum Windows programming compatibility and optimum application performance in both 16bit and 32bit operating environments.

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


WinAsyncAPPC( )
APPC Extensions for the Windows Environment	2 of 10

WinAsyncAPPC( )

Provides an asynchronous entry point for all of the APPC verbs. Use this extension instead of the blocking versions of the verbs if you will run your application under Windows version 3.x.

Syntax

HANDLE WINAPI WinAsyncAPPC(hWnd, LPAPPC);

Returns

The return value specifies whether the asynchronous resolution request was successful. If the extension was successful, the actual return value is an asynchronous task handle. If the function was not successful, a 0 is returned.

Remarks

APPC verbs that can block are as follows:

[MC_]ALLOCATE

[MC_]CONFIRM

[MC_]CONFIRMED

[MC_]DEALLOCATE

[MC_]FLUSH

[MC_]PREPARE_TO_RECEIVE

RECEIVE_ALLOCATE

[MC_]RECEIVE_AND_WAIT

[MC_]REQUEST_TO_SEND

[MC_]SEND_CONVERSATION

[MC_]SEND_DATA

[MC_]SEND_ERROR

TP_ENDED

TP_STARTED

When using the synchronous or asynchronous versions of a verb, an application may only have one outstanding function in progress on a conversation at a time. An attempt to initiate a second function will result in the error code AP_CONV_BUSY.

Note

The exceptions to the previous paragraph are RECEIVE_AND_POST and RECEIVE_AND_WAIT. To allow full use to be made of the asynchronous support, asynchronously issued RECEIVE_AND_WAIT verbs have been altered to act like the RECEIVE_AND_POST verb. Specifically, while an asynchronous RECEIVE_AND_POST or RECEIVE_AND_WAIT is outstanding, the following verbs can be issued on the same conversation:

REQUEST_TO_SEND

GET_TYPE

GET_ATTRIBUTES

TEST_RTS

DEALLOCATE (AP_ABEND_PROG, AP_ABEND_SVC, or AP_ABEND_TIMER)

SEND_ERROR

TP_ENDED

This allows an application, and in particular, a 5250 emulator, to use an asynchronous RECEIVE_AND_WAIT to receive data. While the RECEIVE_AND_POST or RECEIVE_AND_WAIT is outstanding, it can still use SEND_ERROR and REQUEST_TO_SEND. Microsoft recommends that you use this feature for full asynchronous support.

When the asynchronous operation is complete, the application's window hWnd receives the message returned by RegisterWindowMessage with "WinAsyncAPPC" as the input string. The wParam argument contains the asynchronous task handle returned by the original function call. The lParam argument contains the original VCB pointer and can be dereferenced to determine the final return code.

As part of the Windows APPC definition, WinAPPCCancelAsyncRequest allows an application to cancel any asynchronous APPC action; but will terminate the related conversation or TP as appropriate. Any outstanding operations will return with AP_CANCELED as the return code.

If the function returns successfully, a WinAsyncAPPC( ) message will be posted to the application when the operation completes or the conversation is canceled.

See Also

WinAPPCCancelAsyncRequest( )


WinAsyncAPPCEx( )
APPC Extensions for the Windows Environment	3 of 10

WinAsyncAPPCEx( )

Provides an asynchronous entry point for all of the APPC verbs. Use this extension instead of the blocking versions of the verbs to allow multiple sessions to be handled on the same thread. This verb is only supported in Windows NT or Windows NT Advanced Server.

Syntax

HANDLE WINAPI WinAsyncAPPCEx(HANDLE, LPAPPC);

Returns

The return value specifies whether the asynchronous resolution request was successful. If the extension was successful, the actual return value is an asynchronous task handle. If the function was not successful, a 0 is returned.

Remarks

This verb is intended for use with WaitForMultipleObjects in the Win32 API. For more information about this function, see the programming documentation for the Win32 API.

For an example of how to use this verb in multithreaded TPs, see the multithreaded send and receive sample TPs (in the SDK).

APPC verbs that can block are as follows:

[MC_]ALLOCATE

[MC_]CONFIRM

[MC_]CONFIRMED

[MC_]DEALLOCATE

[MC_]FLUSH

[MC_]PREPARE_TO_RECEIVE

RECEIVE_ALLOCATE

[MC_]RECEIVE_AND_WAIT

[MC_]REQUEST_TO_SEND

[MC_]SEND_CONVERSATION

[MC_]SEND_DATA

[MC_]SEND_ERROR

TP_ENDED

TP_STARTED

When using the synchronous or asynchronous versions of a verb, an application may only have one outstanding function in progress on a conversation at a time. An attempt to initiate a second function will result in the error code AP_CONV_BUSY.

Note

The exceptions to the previous paragraph are RECEIVE_AND_POST and RECEIVE_AND_WAIT. To allow full use to be made of the asynchronous support, asynchronously issued RECEIVE_AND_WAIT verbs have been altered to act like the RECEIVE_AND_POST verb. Specifically, while an asynchronous RECEIVE_AND_POST or RECEIVE_AND_WAIT is outstanding, the following verbs can be issued on the same conversation:

REQUEST_TO_SEND

GET_TYPE

GET_ATTRIBUTES

TEST_RTS

DEALLOCATE (AP_ABEND_PROG, AP_ABEND_SVC, or AP_ABEND_TIMER)

SEND_ERROR

TP_ENDED

This allows an application, and in particular, a server application, to use an asynchronous RECEIVE_AND_WAIT to receive data. While the RECEIVE_AND_POST or RECEIVE_AND_WAIT is outstanding, it can still use SEND_ERROR and REQUEST_TO_SEND. Microsoft recommends that you use this feature for full asynchronous support, and in particular, for support of multiple conversations on the same thread.

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

WinAPPCCancelAsyncRequest( )

WaitForMultipleObjects( ) in the Win32 API programming documentation.


WinAPPCCancelAsyncRequest( )
APPC Extensions for the Windows Environment	4 of 10

WinAPPCCancelAsyncRequest( )

Cancels an outstanding WinAsyncAPPC-based request.

Syntax

int WINAPI WinAPPCCancelAsyncRequest(HANDLE hAsyncTaskID)

Parameter	Description

hAsyncTaskID	Supplied parameter; specifies the asynchronous task to be canceled.

Returns

The return value specifies whether the asynchronous request was canceled. If the value is 0, the request was canceled. Otherwise, the value is one of the following:

WAPPCINVALID

An error code indicating that the specified asynchronous task ID was invalid.

WAPPCALREADY

An error code indicating that the asynchronous routine being canceled has already completed.

Remarks

An asynchronous task previously initiated by issuing one of the WinAsyncAPPC functions can be canceled prior to completion by issuing the WinAPPCCancelAsyncRequest( ) extension, specifying the asynchronous task ID as returned by the initial function in hAsyncTaskID.

If the outstanding verb relates to a conversation (for example, SEND_DATA or RECEIVE_AND_WAIT), the verb is purged and the session is brought down. If the verb relates to a TP (for example, RECEIVE_ALLOCATE or TP_STARTED), the TP is ended. In both cases, while the implementation will bring down conversations and session(s) as cleanly as possible, there will be no flushing of send buffers, waiting for confirmations, and so on. This call is synchronous, and after the processing described above is complete, a completion message is posted for the canceled verb.

Should an attempt to cancel an existing asynchronous WinAsyncAPPC routine fail with an error code of WAPPCALREADY, one of two things has occurred. Either the original routine has already completed and the application has dealt with the resulting message, or the original routine has already completed but the resulting message is still waiting in the application window queue.

See Also

WinAsyncAPPC( )


WinAPPCCancelBlockingCall( )
APPC Extensions for the Windows Environment	5 of 10

WinAPPCCancelBlockingCall( )

Cancels any outstanding blocking operation for its thread. Any outstanding blocked call canceled will cause an error code of WAPPCCANCEL to be generated.

Syntax

int WINAPI WinAPPCCancelBlockingCall(void)

Returns

The return value specifies whether the cancellation request was successful. If the value is 0, the request was canceled. Otherwise, the value is the following:

WAPPCINVALID

An error code indicating that there is no outstanding blocking call.

Remarks

If the outstanding verb relates to a conversation (for example, SEND_DATA or RECEIVE_AND_WAIT), the verb is purged and the session is brought down. If the verb relates to a TP (for example, RECEIVE_ALLOCATE or TP_STARTED), the TP is ended. In both cases, while the implementation will bring down conversations and session(s) as cleanly as possible, there will be no flushing of send buffers, waiting for confirmations, and so on. This call is synchronous and after the processing described above is complete, the function is finished.

In Windows NT, a multithreaded application may have multiple blocking operations outstanding, but only one per thread. To distinguish between multiple outstanding calls, WinAPPCCancelBlockingCall( ) cancels the outstanding operation on the current, or calling, application thread if one exists; otherwise, it fails. By default in Windows NT, Windows APPC will suspend the calling application thread while an operation is outstanding. As a result, the thread on which the blocking operation was initiated will not regain control (and therefore, will not be able to issue a call to WinAPPCCancelBlockingCall( )) unless a blocking hook is registered for the thread using WinAPPCSetBlockingHook. This condition does not apply to Windows version 3.x since applications only have one effective thread and the default blocking hook is registered by default.


WinAPPCCleanup( )
APPC Extensions for the Windows Environment	6 of 10

WinAPPCCleanup( )

Terminates and deregisters an application from a Windows APPC implementation.

Syntax

BOOL WINAPI WinAPPCCleanup(void)

Returns

The return value specifies whether the deregistration was successful. If the value is not 0, the application was successfully deregistered. The application was not deregistered if a value of 0 is returned.

Remarks

Use WinAPPCCleanup( ) to indicate deregistration of a Windows APPC application from a Windows APPC implementation.

Conversations that are still active will be terminated and TPs ended. This function is equivalent to issuing TP_ENDED(HARD) on all TPs owned by the application.

See Also

WinAPPCStartup( )


WinAPPCIsBlocking( )
APPC Extensions for the Windows Environment	7 of 10

WinAPPCIsBlocking( )

Determines if a thread is executing while waiting for a previous blocking call to finish.

Syntax

BOOL WINAPI WinAPPCIsBlocking(void)

Returns

The return value specifies the outcome of the function. If the value is not 0, there is an outstanding blocking call awaiting completion. A 0 indicates the absence of an outstanding blocking call.

Remarks

Although a call issued on a blocking function appears to an application as though it blocks, the Windows APPC DLL has to relinquish the processor to allow other applications to run. This means that it is possible for the application that issued the blocking call to be re-entered, depending on the message(s) it receives. In this instance, the WinAPPCIsBlocking( ) call can be used to determine whether the application task currently has been re-entered while waiting for an outstanding blocking call to finish. Note that Windows APPC prohibits more than one outstanding blocking call per thread.

The Windows APPC DLL prohibits more than one blocking call per thread and returns AP_THREAD_BLOCKING if this occurs.

See Also

WinAPPCSetBlockingHook( )

WinAPPCUnhookBlockingHook( )

WinAPPCCancelBlockingCall( )


WinAPPCStartup( )
APPC Extensions for the Windows Environment	8 of 10

WinAPPCStartup( )

Allows an application to specify the version of Windows APPC required and to retrieve details of the specific Windows APPC implementation. This function must be called by an application before issuing any further Windows APPC calls to register itself with a Windows APPC implementation.

Syntax

int WINAPI WinAPPCStartup(WORD wVersionRequired, LPWAPPCDATA)

Parameter	Description

wVersionRequired	Specifies the version of Windows APPC 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 APPC 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:

WAPPCSYSNOTREADY

The underlying network subsystem is not ready for network communication.

WAPPCVERNOTSUPPORTED

The version of Windows APPC support requested is not provided by this particular Windows APPC implementation.

WAPPCINVALID

The Windows APPC version specified by the application is not supported by this DLL.

Remarks

In order to support future Windows APPC implementations and applications that may have functionality differences from Windows APPC version 1.0, a negotiation takes place in WinAPPCStartup( ). An application passes to WinAPPCStartup( ) the Windows APPC version that it can use. If this version is lower than the lowest version supported by the Windows APPC DLL, the DLL cannot support the application and WinAPPCStartup( ) fails. If the version is not lower, however, the call succeeds and returns the highest version of Windows APPC 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 APPC DLL on the system.

This negotiation allows both a Windows APPC DLL and a Windows APPC application to support a range of Windows APPC versions. An application can successfully use a DLL if there is any overlap in the versions. The following table illustrates how WinAPPCStartup( ) works in conjunction with different application and DLL versions.

App versions		DLL versions	To WinAPPCStartup( )	From WinAPPCStartup( )	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	WAPPCINVALID	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
Details of the actual Windows APPC implementation are described in the WAPPCDATA structure defined as follows:

typedef struct tagWAPPCDDATA { WORD wVersion;

char szDescription[WAPPCDESCRIPTION_LEN+1];

} WAPPCDATA, FAR *LPWAPPCDATA;

Having made its last Windows APPC call, an application should call the WinAPPCCleanup routine.

Each Windows APPC implementation must make a WinAPPCStartup( ) call before issuing any other Windows APPC calls.

See Also

WinAPPCCleanup( )


WinAPPCSetBlockingHook( )
APPC Extensions for the Windows Environment	9 of 10

WinAPPCSetBlockingHook( )

Allows a Windows APPC implementation to block APPC function calls by means of a new function. This call is used by Windows version 3.x applications to make blocking calls without blocking the rest of the system. By default in Windows NT, blocking calls will suspend the calling application's thread until the request is finished. Therefore, if a single-threaded application is targeted at both Windows NT and Windows version 3.x, and relies on this functionality, it should register a blocking hook even if the default hook will suffice.

Syntax

FARPROC WINAPI WinAPPCSetBlockingHook (FARPROC 1pBlockFunc)

Parameter	Description

lpBlockFunc	Specifies the procedure instance address of the blocking function to be installed.

Returns

The return value points to the procedure instance of the previously installed blocking function. The application or library that calls the SetBlockingHook function should save this return value so that it can be restored if needed. (If nesting is not important, the application may simply discard the value returned by WinAPPCSetBlockingHook( ) and eventually use WinAPPCUnhookBlocking-Hook to restore the default mechanism.)

Remarks

A Windows APPC implementation has a default mechanism by which blocking APPC functions are implemented. This function gives the application the ability to execute its own function at blocking time in place of the default function.

The default blocking function is equivalent to:

BOOL DefaultBlockingHook (void)  {

MSG msg;

/* get the next message if any */

if ( PeekMessage (&msg,0,0,PM_NOREMOVE)  )  {

if ( msg.message = = WM_QUIT  )

return FALSE;   // let app process WM_QUIT

PeekMessage (&msg,0,0,PM_REMOVE) ;

TranslateMessage (&msg) ;

DispatchMessage (&msg) ;

}

/* TRUE if no WM_QUIT received */

return TRUE;

}

A blocking function must return FALSE if it receives a WM_QUIT message so Windows APPC can return control to the application to process the message and terminate gracefully. Otherwise, the function should return TRUE.

This function is implemented on a per-thread basis. It provides for a particular thread to replace the blocking mechanism without affecting other threads.

The WinAPPCSetBlockingHook( ) function is provided to support those applications that require more complex message processing — for example, those employing the multiple document interface (MDI) model.

See Also

WinAPPCUnhookBlockingHook( )

WinAPPCIsBlocking( )

WinAPPCCancelBlockingCall( )


WinAPPCUnhookBlockingHook( )
APPC Extensions for the Windows Environment	10 of 10

WinAPPCUnhookBlockingHook( )

Removes any previous blocking hook that has been installed and reinstalls the default blocking mechanism.

Syntax

BOOL WINAPI WinAPPCUnhookBlockingHook(void)

Returns

The return value specifies the outcome of the function. It is not 0 if the default mechanism is successfully reinstalled. The value is 0 if the mechanism did not reinstall.

See Also

WinAPPCSetBlockingHook( )


SNA Server Enhancements to the Windows Environment
Chapter 7	1 of 4

SNA Server Enhancements to the Windows Environment

This chapter describes the SNA Server-specific extensions to Windows APPC and CSV.

The function GetAppcConfig takes a local LU/mode pair and returns the remote LUs that are accessible to the user through that pair. If left blank, and a default local LU has been configured, the user's default local LU will be used. In all instances, if one of the returned remote LUs is the user's default, this is indicated as such. For more information on configuring default local and remote LUs, see the Microsoft SNA Server Administration Guide. The call is asynchronous and completion is normally signaled by the posting of a Windows message. However, an alternative completion mechanism is provided for console applications.

The functions GetAppcReturnCode and GetCsvReturnCode convert the primary and secondary return codes in the VCB to a printable string. These functions provide a standard set of error strings for use by applications.

The extensions described in this chapter provide a definition of the function, syntax, returns, and remarks for using the extension.


GetAppcConfig( )
	SNA Server Enhancements to the Windows Environment	2 of 4
GetAppcConfig( )

Provides an asynchronous entry point for retrieving the remote systems to which a particular local LU/mode can connect.

Syntax

HANDLE WINAPI GetAppcConfig(HANDLE hWnd,LPSTR pLocalLu,LPSTR pMode,LPINT pNumRemLu,INT iMaxRemLu,LPSTR pRemLu,LPINT pAsyncRetCode)

Parameter	Description

hWnd	Supplied parameter; provides the asynchronous completion message if non-null is the handle of the window to which completion is to be posted. In this case (recommended for a Windows application) pAsyncRetCode (the last parameter) must be NULL.

pLocalLu	Supplied parameter; specifies the address of a buffer containing the local LU name for which information is returned. This must be:

   Nonpadded

   Null terminated

   ASCII string

   Maximum length of 8 bytes (excluding the terminator)

To request that the user's default local LU is used, the buffer should contain eight spaces followed by a NULL.

pMode	Supplied parameter; specifies the address of a buffer containing the mode name for which information is returned. This must be:

   Nonpadded

   Null terminated

   ASCII string

   Maximum length of 8 bytes (excluding the terminator)

pNumRemLu	Returned parameter; specifies the address of an INT to take the number of remote LUs that would have been returned, had the buffer specified by pRemLu been large enough to accommodate it.

iMaxRemLu	Supplied parameter; specifies the number of remote LU names that can be held by the buffer indicated by pRemLu.

pRemLu	Returned parameter; specifies the address of the buffer that will hold the remote LU names. The information will be returned as an array of strings. Each remote LU name will be:

   Nonpadded

   Null terminated

   ASCII string

   Maximum length of 8 bytes (excluding the terminator)

The strings start every nine bytes in the buffer, and thus (pRemLu + (i - 1)*9) gives the start of the ith string. In the case where the buffer is too small to hold all the names, only iMaxRemLu strings will be returned.

pAsyncRetCode	Returned parameter; specifies the address of an INT to take the asynchronous return code from the call if non-NULL. These return codes will be the same as those returned by the asynchronous completion message. While the call is completing, the value of the INT will be APPC_CFG_PENDING.

Note that if pAsyncRetCode is used, hWnd must be NULL.

Returns

The meaning of the immediate return value depends on whether or not the asynchronous request was accepted. To test for acceptance, evaluate the expression:

(<Returned Handle> & APPC_CFG_SUCCESS)

If the expression is FALSE, the request was rejected. The return value will then be one of the synchronous return codes listed in the following table. If the expression is TRUE, the request was accepted, and one of the following cases will apply.

If hWnd was non-NULL, a completion message will arrive in the following form:

Message Parameter	Description

hWnd	Is the handle of the target window. This value is the same as the value passed in hWnd on the initial call.

uMsg	Matches the number returned by a call to RegisterWindowMessage, with "WinAppcCfg" used as the identifying string. This string is available by the #define WIN_APPC_CFG_COMPLETION_MSG.

wParam	Matches the HANDLE returned from the initial call. It is used as a correlator.

lParam	Contains one of the asynchronous return codes listed in the following sections.

If pAsyncRetCode was non-NULL, then the specified INT will be set to APPC_CFG_PENDING. After a time, its value will change to one of the asynchronous return codes specified below.

Synchronous Return Codes

APPC_CFG_ERROR_NO_APPC_INIT

The Windows APPC library needs to be initialized by a call to WinAPPCStartup before calling GetAPPCConfig( ) and this has not been done.

APPC_CFG_ERROR_INVALID_HWND

The handle passed in hWnd was non-NULL, yet not a valid window handle.

APPC_CFG_ERROR_BAD_POINTER

The hWnd parameter was NULL, indicating that completion was signaled by setting the INT pointed to by pAsyncRetCode, but pAsyncRetCode was not a valid pointer.

APPC_CFG_ERROR_UNCLEAR_COMPLETION_MODE

Both hWnd and pAsyncCompletion were non-NULL, so GetAPPCConfig( ) was unable to decide how completion should be signaled.

APPC_CFG_ERROR_TOO_MANY_REQUESTS

Too many GetAPPCConfig( ) calls are already being processed (currently, this indicates 16 requests are outstanding). Try the call again after a delay. For the Windows version 3.x system, you must yield during this period.

APPC_CFG_ERROR_GENERAL_FAILURE

An unexpected error occurred, probably of a system nature.

Asynchronous Return Codes

APPC_CFG_SUCCESS_NO_DEFAULT_REMOTE

The configuration information has been retrieved, and either no default remote LU was defined or it was not accessible by the specified local LU/mode combination.

APPC_CFG_SUCCESS_DEFAULT_REMOTE

The configuration information has been retrieved, and there is a default remote LU that is accessible by the specified local LU/mode combination.

APPC_CFG_ERROR_NO_DEFAULT_LOCAL_LU

An attempt was made to retrieve remote LUs partnered with the default local LU, but no default local LU was configured.

APPC_CFG_ERROR_BAD_LOCAL_LU

The local LU specified is either not configured, or is not valid for the calling verb.

APPC_CFG_ERROR_GENERAL_FAILURE

An unexpected error occurred, probably of a systems nature.

Remarks

WinAPPCStartup must be called before using GetAPPCConfig( ).

Whether an error code represents success or failure can be determined by evaluating either (RetCode& APPC_CFG_SUCCESS) to test for success or (RetCode& APPC_CFG_FAILURE) to test for failure.

The following code fragment shows how a console application can test completion:

while (*pAsyncRetCode == APPC_CFG_PENDING)

{

sleep(250);

}


GetAppcReturnCode( )
	SNA Server Enhancements to the Windows Environment	3 of 4
GetAppcReturnCode( )

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 APPC applications such as 5250 emulators.

Syntax

int WINAPI GetAppcReturnCode (struct appc_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 APPC string library APPCSTR.DLL (for Windows) or APPCST32.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 APPCSTR.DLL (for Windows) or APPCST32.DLL (for Windows NT) and can be customized for different languages.


GetCsvReturnCode( )
	SNA Server Enhancements to the Windows Environment	4 of 4
GetCsvReturnCode( )

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 applications using CSVs.

Syntax

int WINAPI GetCsvReturnCode (struct csv_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 CSV string library CSVSTR.DLL (for Windows) or CSVST32.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 CSVSTR.DLL (for Windows) or CSVST32.DLL (for Windows NT) and can be customized for different languages.


Common Service Verbs
Chapter 8	1 of 19

Common Service Verbs

Common service verbs (CSVs) are a set of programming functions provided by Microsoft SNA Server. The CSVs provide convert, log, trace, and transfer services to applications.

The first part of this chapter describes the verbs available to you and explains how to use them with your applications. A detailed description of each verb is provided in the second part of the chapter.

Table 8.1 briefly describes the CSVs.

Table 8.1    Common Service Verbs

Verb	Purpose

CONVERT	Converts a character string from ASCII to EBCDIC or from EBCDIC to ASCII.

COPY_TRACE_TO_FILE	Concatenates the contents of the individual application programming interface (API)/link service trace files to form a single trace file.

DEFINE_TRACE	Enables or disables tracing for specific APIs.

GET_CP_CONVERT_TABLE	Creates and returns a 256-byte conversion table to translate character strings from a source code page to a target code page.

LOG_MESSAGE	For OS/2 only, takes a message from a message file, adds specified data to it, and records the message in the error log file. This verb optionally displays the message on the user's screen.

TRANSFER_MS_DATA	Builds a Systems Network Architecture (SNA) request unit (RU) containing Network Management Vector Transport (NMVT) data. The verb can send the NMVT data to NetView [image] for centralized problem diagnosis and resolution. The data is optionally logged in the event log for Windows NT, Windows version 3.x, or MS-DOS, and in the local audit log file for OS/2.


Windows CSV Overview
Common Service Verbs	2 of 19

Windows CSV Overview

The CSVs and information presented in this guide represent an evolving CSV that is composed of IBM Extended Services for OS/2 version 1.0 (IBM ES for OS/2 version 1.0) and a set of Windows extensions that allow for registering and deregistering the application and that provide an asynchronous entry point for TRANSFER_MS_DATA.


SNA Server Asynchronous Support
Common Service Verbs	3 of 19

Windows CSV Overview

SNA Server Asynchronous Support

Asynchronous call completion returns the initial call immediately so the application can continue with other processes. An application that issues a call 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.

Through RegisterWindowsMessage with "WinAsyncCSV" as the string, you pass a Windows handle by which you will be notified of call 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 call is complete.


Before Using Windows CSV
Common Service Verbs	4 of 19

Windows CSV Overview

Before Using Windows CSV

The following Windows enhancements are of particular importance and should be reviewed before using Windows CSV:

WinAsyncCSV

Provides an asynchronous entry point for TRANSFER_MS_DATA only. If used for any other verb, the behavior will be synchronous. Use this extension instead of the blocking version of the verb if you will run your application under Windows version 3.x.

When the asynchronous operation is complete, the application's window hWnd receives the message returned by RegisterWindowMessage with "WinAsyncCSV" as the input string. The wParam argument contains the asynchronous task handle returned by the original function call. The lParam argument contains the original verb control block (VCB) pointer and can be dereferenced to determine the final return code.

If the function returns successfully, a "WinAsyncCSV" message will be posted to the application when the operation completes or the conversation is canceled.

WinCSVStartup

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

Important

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

WinCSVCleanup

Terminates and deregisters an application from a Windows CSV implementation.

Important

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

For more information on CSVs and the Windows extensions, see the verb descriptions in this chapter as well as Chapter 9, "CSV Extensions for the Windows Environment."


Creating Specific NetView User Alerts
Common Service Verbs	5 of 19

Creating Specific NetView User Alerts

You can create NetView user alerts for users to send. Users identify the alerts by number; each number corresponds to a specific collection of information or requests that the user wants to send via NetView to a host operator.

SNA Server leaves blank fields for the user alert information in the structure that is returned from SEPDCREC. To create specific user alerts, create appropriate data structures, and call the TRANSFER_MS_DATA verb to send the user alert to NetView.

For information about SEPDCREC, see the 3270 Emulator Interface Specification.


Using CSVs in C Programs
Common Service Verbs	6 of 19

Using CSVs in C Programs

CSVs are available to applications written in Microsoft C version 5.1 or later. A program written in C calls CSVs through the external function WINCSV.


Sample Programs
Common Service Verbs	7 of 19

Using CSVs in C Programs

Sample Programs

A collection of sample programs is delivered with the SNA Server Software Development Kit in the \SDK\SAMPLES directory on the SNA Server CD. For more information, see Appendix C, "Sample APPC TPs in the SDK."


Verb Control Block
Common Service Verbs	8 of 19

Using CSVs in C Programs

Verb Control Block

The only parameter passed to the WINCSV function is the address of a VCB. The VCB is a structure made up of variables that identify the verb to be executed, supply information to be used by the verb, and contain information returned by the verb when execution is complete. Each verb has its own VCB structure, which is declared in the file WINCSV.H.


Bit Ordering
Common Service Verbs	9 of 19

Using CSVs in C Programs

Bit Ordering

Bit 0 refers to the high-order bit in a byte or word. To set bit 0 on in a byte, use the bitwise OR operation ( ¦= ) with a value of 128.


WINCSV Definition
Common Service Verbs	10 of 19

Using CSVs in C Programs

WINCSV Definition

The prototype definition of the WINCSV function is as follows:

extern void WINAPI WINCSV (LPCSV);

The VCB address parameter, a 32bit pointer, is declared as a long integer and requires casting from a pointer to a long integer.


WINCSV.H File
Common Service Verbs	11 of 19

Using CSVs in C Programs

WINCSV.H File

Use the #include command to include the WINCSV.H file in any application that issues CSVs.

The WINCSV.H file, which is delivered on the SNA Server Software Development Tool Kit, contains:

The CSV function prototype.

The structure declarations for the CSV VCBs.

The #define statements that substitute meaningful symbolic constants for hexadecimal values supplied to and returned by CSVs.

If a #define statement pertains to a hexadecimal value that is longer than 1 byte, a comment shows how the hexadecimal value is stored in memory.

When setting or testing CSV parameters, use the symbolic constants defined by the WINCSV.H file. When examining trace files or the contents of memory, use the hexadecimal values.


Issuing a CSV
Common Service Verbs	12 of 19

Using CSVs in C Programs

Issuing a CSV

The procedure for issuing a CSV is shown in the following sample code that uses CONVERT.

1.	Create a structure variable from the VCB structure that applies to the verb to be issued.

#include <wincsv.h>
    .
    .
    .
struct convert  conv_block;

The VCB structures are declared in the WINCSV.H file; one of these structures is named CONVERT.

2.	Clear (set to 0) the variables within the structure.

memset( conv_block, '\0', sizeof( conv_block ) );

This procedure is not required. However, it helps in debugging and reading the contents of memory. It also eliminates the possibility that future versions of a verb are sensitive to fields that are ignored in the current version.

3.	Assign values to the required VCB variables.

conv_block.opcode = SV_CONVERT;
conv_block.direction = SV_ASCII_TO_EBCDIC;
conv_block.char_set = SV_AE;
conv_block.len = sizeof(tpstart_name);
conv_block.source = (LPBYTE) tpstart_name;
conv_block.target = (LPBYTE) tpstart.tp_name;

The values SV_CONVERT, SV_ASCII_TO_EBCDIC, and SV_AE are symbolic constants representing integers. These constants are defined in the WINCSV.H file.

The character array TPSTART_NAME contains an ASCII string to be converted to EBCDIC and placed in the character array TPSTART.TP_NAME.

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

ACSSVC((LONG) &conv_block);

You can also use the following statement:

ACSSVC_C((LONG) &conv_block);

5.	Use the values returned by the verb.

if( conv_block.primary_rc == SV_OK ) {
/* other statements */
    .
    .
    .


Common Service Verbs
Common Service Verbs	13 of 19

Common Service Verbs

The remainder of this chapter describes each of the CSVs and provides:

A definition of the verb.

The structure that defines the VCB used by the verb. The structure is declared in the WINCSV.H file.

The parameters (VCB fields) supplied for and returned by the verb. For each parameter, the following information is provided:

Description

Possible values

Additional information

Additional information describing the use of the verb.

Most parameters supplied to and returned by CSVs are hexadecimal values. To simplify coding, these values are represented by meaningful symbolic constants, which are established by #define statements in the header file WINCSV.H. For example, the opcode (operation code) parameter for CONVERT is the hexadecimal value represented by the symbolic constant SV_CONVERT. Use only the symbolic constants when programming CSVs.


CONVERT
Common Service Verbs	14 of 19

CONVERT

Translates an ASCII character string to EBCDIC or an EBCDIC character string to ASCII. The string to be converted is called the source string. The converted string is called the target string.

Syntax

opcode		unsigned short int
opext		unsigned char
reserv2		reserved unsigned char
primary_rc		reserved unsigned short int
secondary_rc		unsigned long int
direction		unsigned char
char_set		unsigned char
len		unsigned short int
source		unsigned char far *
target		unsigned char far *
Parameter	Description

opcode	Supplied parameter; SV_CONVERT.

direction	Supplied parameter; specifies the direction of the conversion. To convert from ASCII to EBCDIC, use SV_ASCII_TO_EBCDIC. To convert from EBCDIC to ASCII, use SV_EBCDIC_TO_ASCII.

char_set	Supplied parameter; specifies the character set to use in converting the source string. Allowed values include SV_A (Type A character set), SV_AE (Type AE character set),  and SV_G (Type G character set).

len	Supplied parameter; specifies the number of characters to be converted.

This length plus the offset from the beginning of the source or target buffer must not exceed the segment boundary.

source	Supplied parameter; specifies the address of the buffer containing the character string to be converted.

target 	Supplied parameter; specifies the address of the buffer to contain the converted character string.

This buffer can overlap or coincide with the buffer pointed to by the source parameter. In this case, the converted data string overwrites the source data string.

Return Codes

SV_OK

Primary return code; the verb executed successfully.

SV_PARAMETER_CHECK

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

SV_CONVERSION_ERROR

Secondary return code; one or more characters in the source string were not found in the conversion table. These characters were converted to nulls (X'00'). The verb still executed.

SV_INVALID_CHARACTER_SET

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

SV_INVALID_DATA_SEGMENT

Secondary return code; the data buffer containing the source or target string did not fit in one segment, or the target segment was not a read/write segment. This applies only to the Windows NT, Windows version 3.x, and OS/2 operating systems.

SV_INVALID_DIRECTION

Secondary return code; the direction contained an invalid value.

SV_INVALID_FIRST_CHARACTER

Secondary return code; the first character of a type A source string was invalid.

SV_TABLE_ERROR

Secondary return code; one of the following occurred:

The file containing the user-written type G conversion table was not specified by the environment variable CSVTBLG.

The table was not in the correct format.

The file specified by the CSVTBLG variable was not found.

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

SV_INVALID_VERB

Primary return code; the opcode parameter did not match the operation code of any verb. No verb executed.

SV_INVALID_VERB_SEGMENT

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

SV_UNEXPECTED_DOS_ERROR

Primary return code; one of the following conditions has occurred:

The Windows NT, Windows version 3.x, MS-DOS, or OS/2 system encountered an error while processing the verb. The operating system return code was returned through the secondary return code. If the problem persists, contact the system administrator for corrective action.

A CSV was issued from a message loop that was invoked by another application issuing a Windows SendMessage function call, rather than the more common Windows PostMessage function call. Verb processing cannot take place.

A CSV was issued when SendMessage invoked your application. You can determine whether your application has been invoked with SendMessage by using the InSendMessage Windows API function call.

Remarks

The type A character set consists of:

Uppercase letters.

Numerals 0 through 9.

Special characters $, #, @, and space.

This character set is supported by a system-supplied type A conversion table.

The first character of the source string must be an uppercase letter or the special character $, #, or @. Spaces are allowed only in trailing positions. Lowercase ASCII letters are translated to uppercase EBCDIC letters when the direction is ASCII to EBCDIC.

The type AE character set consists of:

Uppercase letters.

Lowercase letters.

Numerals 0 through 9.

Special characters $, #, @, period, and space.

This character set is supported by a system-supplied type AE conversion table.

The first character of the source string can be any character in the character set, except the space. Spaces are allowed only in trailing positions.

During conversion, embedded blanks (including blanks in the first position) are converted to X'00'. Although such a conversion will complete, CONVERSION_ERROR is returned as the secondary return code, indicating that the CSV library has completed an irreversible conversion on the supplied data.

For the Windows NT system, a description of COMTBLG should point to the Windows NT Registry under \SnaBase\Parameters\Client. For the Windows version 3.x system, the fully qualified filename for a type G conversion table must be the COMTBLG=filename entry of the [WNAP] section in the WIN.INI file. Entries in this section of the WIN.INI file are used in all places where MS-DOS and OS/2 use environment variables. (If the file is not found, the system returns the parameter check SV_TABLE_ERROR.)

The data for a type G conversion table must be an ASCII file 32 lines long. Each line must consist of 32 hexadecimal digits, representing 16 characters, and be terminated by a carriage return and line feed. The first 16 lines (256 characters) specify the EBCDIC characters to which ASCII characters are converted; the remaining 16 lines specify the ASCII characters to which EBCDIC characters are converted.

The hexadecimal digits A through F can be either uppercase or lowercase. How-ever, you may want to make these digits uppercase to ensure compatibility with IBM ES for OS/2 version 1.0.

Note

You can use GET_CP_CONVERT_TABLE to build a type G, user-written conversion table in memory, and then store the table in a file. For more information, see GET_CP_CONVERT_TABLE later in this chapter.


COPY_TRACE_TO_FILE
Common Service Verbs	15 of 19

COPY_TRACE_TO_FILE

Concatenates individual API/link service trace files to form a single file.

Syntax

opcode		unsigned short int
opext		unsigned char
reserv2		reserved unsigned char
primary_rc		reserved unsigned short int
secondary_rc		unsigned long int
reserv3		unsigned char
file_name		reserved unsigned char [64]
file_option		unsigned char
reserv4		unsigned char
Parameter	Description

opcode	Supplied parameter; SV_COPY_TRACE_TO_FILE.

file_name	Supplied parameter; specifies the name of the file to which trace data is to be copied. This parameter is a 64-byte character string, and it can include a path. If the name is fewer than 64 bytes, use spaces to pad it on the right.

file_option	Supplied parameter; specifies the output file copy option:

   Use SV_NEW to copy the trace only if the specified file does not already exist.

   Use SV_OVERWRITE to copy the trace to an existing file, overwriting the current data. The size of the file is increased, if necessary; and the file is created if it does not already exist.

Return Codes

SV_OK

Primary return code; the verb executed successfully.

SV_PARAMETER_CHECK

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

SV_INVALID_FILE_OPTION

Secondary return code; a value other than SV_NEW or SV_OVERWRITE was specified for file_option.

SV_STATE_CHECK

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

SV_COPY_TRACE_IN_PROGRESS

Secondary return code; a previously issued COPY_TRACE_TO_FILE verb is still in progress.

SV_TRACE_FILE_EMPTY

Secondary return code; there is no data in the trace files.

SV_TRACE_NOT_STOPPED

Secondary return code; a trace was in progress when the verb was issued.

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

SV_FILE_ALREADY_EXISTS

Primary return code; when the SV_NEW file option was used, the filename specified was the name of an existing file.

SV_INVALID_VERB

Primary return code; the opcode parameter did not match the operation code of any verb. No verb executed.

SV_INVALID_VERB_SEGMENT

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

SV_OUTPUT_DEVICE_FULL

Primary return code; there is insufficient space on the device where the output file resides. Retry the operation after freeing additional disk space.

SV_UNEXPECTED_DOS_ERROR

Primary return code; one of the following conditions has occurred:

The Windows NT, Windows version 3.x, MS-DOS, or OS/2 system encountered an error while processing the verb. The operating system return code was returned through the secondary return code. If the problem persists, contact the system administrator for corrective action.

A CSV was issued from a message loop that was invoked by another application issuing a Windows SendMessage function call, rather than the more common Windows PostMessage function call. Verb processing cannot take place.

A CSV was issued when SendMessage invoked your application. You can determine whether your application has been invoked with SendMessage by using the InSendMessage Windows API function call.

Remarks

There are two API/link-service trace files. The files are used alternately; tracing switches from one file to the other when one file is full (larger than 250 kilobytes [K]). When COPY_TRACE_TO_FILE is called, these trace files are concatenated and copied to a single file, the name of which is specified as a parameter to the call.

API/link-service tracing is stopped before issuing the verb, and restarted once the copy is complete. The trace files are reset when this verb is successfully completed.


DEFINE_TRACE
Common Service Verbs	16 of 19

DEFINE_TRACE

Enables or disables tracing for specified APIs and controls the amount of tracing.

Syntax

opcode		unsigned short int
opext		unsigned char
reserv2		reserved unsigned char
primary_rc		reserved unsigned short int
secondary_rc		unsigned long int
reserv3		unsigned char [8]
dt_set		unsigned char
appc		unsigned char
reserv4		unsigned char
srpi		reserved unsigned char
sdlc		reserved unsigned char
tkn_rng_dlc		reserved unsigned char
pcnet_dlc		reserved unsigned char
dft		reserved unsigned char
acdi		reserved unsigned char
reserv5		reserved unsigned char
ehllapi		unsigned char
x25_api		reserved unsigned char
x25_dlc		reserved unsigned char
twinax		reserved unsigned char
reserv6		reserved unsigned char
lua_api		reserved unsigned char
etherand		reserved unsigned char
subsym		reserved unsigned char
reserv7		reserved unsigned char [8]
reset_trc		reserved unsigned char
trunc		reserved unsigned short int
strg_size		unsigned short int
reserv8		reserved unsigned char
phys_link		unsigned char
reserv9		unsigned char
Parameter	Description

opcode	Supplied parameter; SV_DEFINE_TRACE.

dt_set	Supplied parameter:

   Use SV_ON to enable tracing for a particular API if the parameter pertaining to the API (such as appc or comm_serv) is set to SV_CHANGE.

   Use SV_OFF to disable tracing for a particular API if the parameter pertaining to the API  is set to SV_CHANGE.

appc 	Supplied parameter:

   Use SV_CHANGE to enable or disable tracing for APPC, depending on the dt_set parameter.

   Use SV_IGNORE to leave tracing in its current state for APPC.

The allowed values turn bit 0 on or off; bits 1 through 7 are reserved.

reset_trc	Supplied parameter:

   Use SV_NO to not reset the trace file pointer to the start of the file. Previous trace records are not overwritten.

   Use SV_YES to reset the trace file pointer to the start of the trace file. Previous trace records are overwritten.

trunc	Supplied parameter; specifies the maximum number of bytes for each trace record. Excess bytes are truncated. Set this value to 0 if you do not want truncation.

Return Codes

SV_OK

Primary return code; the verb executed successfully.

SV_PARAMETER_CHECK

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

SV_INVALID_RESET_TRACE

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

SV_INVALID_SET

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

SV_STATE_CHECK

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

SV_COPY_TRACE_IN_PROGRESS

Secondary return code; a previously issued COPY_TRACE_TO_FILE is still in progress. Traces cannot be active while using DEFINE_TRACE.

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

SV_INVALID_VERB

Primary return code; the opcode parameter did not match the operation code of any verb. No verb executed.

SV_INVALID_VERB_SEGMENT

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

SV_UNEXPECTED_DOS_ERROR

Primary return code; one of the following conditions has occurred:

The Windows NT, Windows version 3.x, MS-DOS, or OS/2 system encountered an error while processing the verb. The operating system return code was returned through the secondary return code. If the problem persists, contact the system administrator for corrective action.

A CSV was issued from a message loop that was invoked by another application issuing a Windows SendMessage function call, rather than the more common Windows PostMessage function call. Verb processing cannot take place.

A CSV was issued when SendMessage invoked your application. You can determine whether your application has been invoked with SendMessage by using the InSendMessage Windows API function call.

Remarks

For information on how to run and use traces, see the appropriate manual for your product.


GET_CP_CONVERT_TABLE
Common Service Verbs	17 of 19

GET_CP_CONVERT_TABLE

Creates and returns a 256-byte conversion table to translate character strings from a source code page to a target code page.

Syntax

opcode		unsigned short int
opext		unsigned char
reserv2		reserved unsigned char
primary_rc		reserved unsigned short int
secondary_rc		unsigned long int
source_cp		unsigned short int
target_cp		unsigned short int
conv_tbl_addr		unsigned char far *
char_not_fnd		unsigned char
substitute_char		unsigned char
Parameter	Description

opcode	Supplied parameter; SV_GET_CP_CONVERT_TABLE.

source_cp	Supplied parameter; specifies the source code page (from which characters are converted). The allowed code pages (decimal values) are as follows:

   ASCII437437, 850, 860, 863, 865

   EBCDIC037, 273, 277, 278, 280, 284, 285, 297, 500

This value is user defined; it can range from 65280 through 65534

ASCII code pages are sometimes referred to as PC code pages; EBCDIC code pages are sometimes referred to as host code pages.

target_cp	Supplied parameter; specifies the target code page (to which characters are converted). For allowed code pages, see the preceding definition for source_cp.

conv_tbl_addr	Supplied parameter; specifies the address of the buffer to contain the 256-byte conversion table. The buffer must be in a writable segment and long enough to contain the table.

char_not_fnd	Supplied parameter; specifies the action to take if a character in the source code page does not exist in the target code page:

   Use SV_ROUND_TRIP to store a unique value in the conversion table for each source code-page character.

   Use SV_SUBSTITUTE to store a substitute character (specified by substitute_char) in the conversion table.

substitute_char	Supplied parameter; specifies the character to store in the conversion table when a character from the source code page has no equivalent in the target code page.

Return Codes

SV_OK

Primary return code; the verb executed successfully.

SV_PARAMETER_CHECK

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

SV_INVALID_CHAR_NOT_FOUND

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

SV_INVALID_DATA_SEGMENT

Secondary return code; the 256-byte area specified for the conversion table extended beyond the segment boundary, or the segment was not writable.

SV_INVALID_SOURCE_CODE_PAGE

Secondary return code; the code page specified by source_cp is not supported.

SV_INVALID_TARGET_CODE_PAGE

Secondary return code; the code page specified by target_cp is not supported.

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

SV_INVALID_VERB

Primary return code; the opcode parameter did not match the operation code of any verb. No verb executed.

SV_INVALID_VERB_SEGMENT

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

SV_UNEXPECTED_DOS_ERROR

Primary return code; one of the following conditions has occurred:

The Windows NT, Windows version 3.x, MS-DOS, or OS/2 system encountered an error while processing the verb. The operating system return code was returned through the secondary return code. If the problem persists, contact the system administrator for corrective action.

A CSV was issued from a message loop that was invoked by another application issuing a Windows SendMessage function call, rather than the more common Windows PostMessage function call. Verb processing cannot take place.

A CSV was issued when SendMessage invoked your application. You can determine whether your application has been invoked with SendMessage by using the InSendMessage Windows API function call.

Remarks

The type A character set consists of:

Uppercase letters.

Numerals 0 through 9.

Special characters $, #, @, and space.

This character set is supported by a system-supplied type A conversion table.

The first character of the source string must be an uppercase letter or the special character $, #, or @. Spaces are allowed only in trailing positions. Lowercase ASCII letters are translated to uppercase EBCDIC letters when the direction is ASCII to EBCDIC.

The type AE character set consists of:

Uppercase letters.

Lowercase letters.

Numerals 0 through 9.

Special characters $, #, @, period, and space.

This character set is supported by a system-supplied type AE conversion table.

The first character of the source string can be any character in the character set, except the space.

During conversion, embedded blanks (including blanks in the first position) are converted to X'00'. Although such a conversion will complete, CONVERSION_ERROR is returned as the secondary return code, indicating that the CSV library has completed an irreversible conversion on the supplied data.

For the Windows NT system, a description of COMTBLG should point to the Registry under \SnaBase\Parameters\Client. For the OS/2 operating system, the directory and file containing the table must be specified by the environment variable COMTBLG. (If the file is not found, the system returns the SV_TABLE_ERROR parameter check.).

The SV_ROUND_TRIP value for char_not_fnd is useful only if you build a second conversion table to convert between the same two code pages in the reverse direction. If you specify the SV_ROUND_TRIP value in building both conversion tables, any character translated from one code page to the other and then back will be unchanged.

When using the SV_SUBSTITUTE value for char_not_fnd, converting the translated character string back to the original code page will not necessarily re-create the original character string.

Use substitute_char only if char_not_fnd is set to SV_SUBSTITUTE.

The value stored in the conversion table is the ASCII value associated with the character. If the table is used for conversion from ASCII to EBCDIC, the character that appears in the converted string is the character associated with the numeric EBCDIC value rather than ASCII.

For example, if you supply the underscore (_) character (ASCII value F6) while creating an ASCII to EBCDIC conversion table, the character that appears in the converted strings will be 6, the character associated with the value F6 in EBCDIC. To use the _ character as the substitute character in an ASCII to EBCDIC conversion table, you should supply the value E1 (the value associated with the _ character in EBCDIC) rather than the actual character.

A code page is a table that associates specific ASCII or EBCDIC values with specific characters. If a character from the source code page does not exist in the target code page, the translated (target) string differs from the original (source) string.


LOG_MESSAGE
Common Service Verbs	18 of 19

LOG_MESSAGE

For OS/2 only, records a message in the error log file and optionally displays the message on the user's screen. This verb is included for compatibility with existing applications.

Syntax

opcode		unsigned short int
opext		unsigned char
reserv2		unsigned char
primary_rc		unsigned short int
secondary_rc		unsigned long int
msg_num		unsigned short int
origntr_id		unsigned char [8]
msg_file_name		unsigned char [3]
msg_act		unsigned char
msg_ins_len		unsigned short int
msg_ins_ptr		unsigned char far *
Parameter	Description

opcode	Supplied parameter; SV_LOG_MESSAGE.

msg_num	Supplied parameter; specifies the number of the message in the message file specified by msg_file_name.

origntr_id	Supplied parameter; specifies the name of the component issuing LOG_MESSAGE or an 8-byte, user-supplied string.

msg_file_name	Supplied parameter; specifies the name of the file containing the message to be logged.

msg_act 	Supplied parameter; specifies the action to be taken when processing the message:

  Use SV_INTRV to log the intervention with a severity level of 12 and display the message on the user's screen. The user must press a key to remove the message from the screen.

  Use SV_NO_INTRV to log the intervention with a severity level of 12 but not display the message.

msg_ins_len	Supplied parameter; specifies the length of data to be inserted into the message. Set this parameter to 0 if no data is to be inserted.

msg_ins_ptr	Supplied parameter; specifies the address of the data to be inserted into the message.

Use this parameter only if msg_ins_len is greater than 0.

Return Codes

SV_OK

Primary return code; the verb executed successfully.

SV_PARAMETER_CHECK

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

SV_INVALID_DATA_SEGMENT

Secondary return code; the data that was to be inserted into the message extended beyond the segment boundary.

SV_INVALID_MESSAGE_ACTION

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

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

SV_INVALID_VERB

Primary return code; the opcode parameter did not match the operation code of any verb. No verb executed.

SV_INVALID_VERB_SEGMENT

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

SV_UNEXPECTED_DOS_ERROR

Primary return code; one of the following conditions has occurred:

The Windows NT, Windows version 3.x, MS-DOS, or OS/2 system has encountered an error while processing the verb. The operating system return code was returned through the secondary return code. If the problem persists, contact the system administrator for corrective action.

A CSV was issued from a message loop that was invoked by another application issuing a Windows SendMessage function call, rather than the more common Windows PostMessage function call. Verb processing cannot take place.

A CSV was issued when SendMessage invoked your application. You can determine whether your application has been invoked with SendMessage by using the InSendMessage Windows API function call.

Remarks

The value for msg_file_name must be three characters long. Pad with spaces if necessary. The .MSG extension is added automatically.

The total length of msg_ins_len, including header information (40 bytes), message text, and inserted data, should not exceed 256 bytes. If the length is greater than 256 bytes, the communication system will attempt to log only the header information and inserted text; the message text will be left out.

When you create the log message file, you can specify where in the message the additional data is to be inserted. For further information, see the following section.

The data for msg_ins_ptr consists of a series of up to nine null-terminated strings. (Because IBM OS/2 ES version 1.0 supports only three data strings, you may want to limit the inserted text to three strings to ensure compatibility.)

Creating a Message File

If you want to create your own message file, you must use the utility MKMSGF. This utility can run with MS-DOS as well.

The first three characters of the message number must match the three-character name of the log message file. These three characters are declared at the top of the file as well.

The following paragraphs describe how the system finds the message file.

If you use your own message file, the system assumes the file is in the same directory as your program's executable file.

If you use the default message file, COM.MSG, the system finds the file automatically, provided the SnaBase for SNA Server is loaded.

If you use the default message file without loading the previously mentioned software, the system expects DPATH to indicate the path to the message file. This applies only to the Windows version 3.x and OS/2 operating systems.


TRANSFER_MS_DATA
Common Service Verbs	19 of 19

TRANSFER_MS_DATA

Builds an SNA request unit containing NMVT data. The verb can send the NMVT data to NetView for centralized problem diagnosis and resolution. The data is logged in the local audit file.

Syntax

opcode		unsigned short int
data_type		unsigned char
reserv2		unsigned char
primary_rc		reserved unsigned short int
secondary_rc		unsigned long int
options		unsigned char
reserv3		unsigned char
origntr_id		reserved unsigned char [8]
dlen		unsigned short int
dptr		unsigned char far *
Parameter	Description

opcode	Supplied parameter; SV_TRANSFER_MS_DATA.

data_type	Supplied parameter; specifies the type of data provided by this verb:

   Use SV_NMVT to generate an NMVT (including the NS header, the major network management vector, and subvectors).

   Use SV_ALERT_SUBVECTORS to generate
an RU containing data for an alert, in the appropriate format, without the NS header or major NMVT vector.

   Use SV_PDSTATS_SUBVECTORS to generate an RU containing data for problem determination statistics, in the appropriate format, without the NS header or major NMVT vector.

   Use SV_USER_DEFINED to generate user-defined data; this data is recorded in the error log but cannot be sent on the systems services control point-physical unit (SSCP-PU) session on the connection configured for diagnostics.

options	Supplied parameter; specify the desired options by turning individual bits on or off. (Bits 1, 2, and 3 are ignored if data_type is set to SV_USER_DEFINED.) See the "Remarks" section.

origntr_id	Supplied parameter; specifies the name of the component issuing TRANSFER_MS_DATA. This parameter is optional. Set it to X'00' if you want the system to ignore it.

dlen	Supplied parameter; specifies the length of data to be supplied to this verb. The total length of the data (user-supplied data and any added headers or subvectors) must fit into one RU. The maximum RU length is 512 bytes.

dptr	Supplied parameter; specifies the address of the data to be sent.

Return Codes

SV_OK

Primary return code; the verb executed successfully.

SV_PARAMETER_CHECK

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

SV_DATA_EXCEEDS_RU_SIZE

Secondary return code; the data to be sent was too long. The length of the user-supplied data plus headers and added subvectors must fit in a single RU that is not more than 512 bytes long.

SV_INVALID_DATA_SEGMENT

Secondary return code; the buffer pointed to by dptr was not a readable segment or extended beyond the segment boundary.

SV_INVALID_DATA_TYPE

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

SV_STATE_CHECK

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

SV_SSCP_PU_SESSION_NOT_ACTIVE

Secondary return code; the NMVT was not sent; either the SSCP-PU session was not active, the node configured to receive diagnostic information was not active, or no network management connection was configured.

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

SV_INVALID_VERB

Primary return code; the opcode parameter did not match the operation code of any verb. No verb executed.

SV_INVALID_VERB_SEGMENT

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

SV_UNEXPECTED_DOS_ERROR

Primary return code; one of the following conditions has occurred:

The Windows NT, Windows version 3.x, MS-DOS, or OS/2 system encountered an error while processing the verb. The operating system return code was returned through the secondary return code. If the problem persists, contact the system administrator for corrective action.

A CSV was issued from a message loop that was invoked by another application issuing a Windows SendMessage function call, rather than the more common Windows PostMessage function call. Verb processing cannot take place.

A CSV was issued when SendMessage invoked your application. You can determine whether your application has been invoked with SendMessage by using the InSendMessage Windows API function call.

SV_CANCELLED

Primary return code; this code is returned for an asynchronous verb when it has been shut down by a WinCSVCleanup call.

SV_SERVER_RESOURCE_NOT_FOUND

Primary return code; no communication server was found that could provide the requested function.

SV_SERVER_RESOURCE_LOST

Primary return code; the communications server that was providing the function was lost due to a connection failure.

SV_SERVER_COMM_FAILURE

Secondary return code; the connection to the server was lost due to physical path problems; for example, the server may have been powered off.

SV_THREAD_BLOCKING

Primary return code; this verb exceeds the maximum number of simultaneous synchronous verbs allowed.

Remarks

To specify options:

Bit	Description

0	TIME_STAMP_SUBVECTOR. Adds date/time subvector to data. Allowed values include SV_ADD and SV_NO_ADD.

1	PRODUCT_SET_ID_SUBVECTOR. Adds Product_Set_ID subvector to data. This allows network management services to identify the sender of an alert. Allowed values include SV_ADD and SV_NO_ADD.

2	SSCP_PU_SESSION. Sends the data on the SSCP-PU session on the connection configured for diagnostics if the session is active. (The data is added to the error log regardless of whether it is sent on the session or whether SV_STATE_CHECK or SV_COMM_SUBSYSTEM_NOT_LOADED is returned.) Allowed values include SV_SEND and SV_NO_SEND.

3	LOCAL_LOGGING. Logs local alerts that are retrieved from the error log and forwarded to the host. This option is valid only when data_type SV_NMVT or data_type SV_ALERT_SUBVECTORS with option SV_SEND is specified. Allowed values include SV_LOG and SV_NO_LOG.

4 through 7	Reserved

.


CSV Extensions for the Windows Environment
Chapter 9	1 of 4

CSV Extensions for the Windows Environment

This chapter describes API extensions to the Windows CSV. The extensions described in this chapter have been designed for all implementations and versions of the Microsoft Windows graphical environment, version 3.0 and later. They provide support for maximum Windows programming compatibility and optimum application performance in both 16bit and 32bit operating environments.

Windows CSV allows multithreaded Windows-based processes. Multithreading is the running of several processes in rapid sequence within a single program. 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.


WinCSVCleanup( )
CSV Extensions for the Windows Environment	2 of 4

WinCSVCleanup( )

Terminates and deregisters an application from a Windows CSV implementation.

Syntax

BOOL WINAPI WinCSVCleanup(void);

Returns

The return value specifies whether the deregistration was successful. If the value is not 0, the application was successfully deregistered. The application was not deregistered if a value of 0 is returned.

Remarks

Use WinCSVCleanup( ) to indicate deregistration of a Windows CSV application from a Windows CSV implementation. This function can be used, for example, to free up resources allocated to the specific application.


WinAsyncCSV( )
CSV Extensions for the Windows Environment	3 of 4

WinAsyncCSV( )

Provides an asynchronous entry point for TRANSFER_MS_DATA only. If this extension is used for any other verb, the behavior will be synchronous. Use this extension instead of the blocking version of the verb if you will run your application under Windows version 3.x.

Syntax

HANDLE WINAPI WinAsyncCSV(hwnd, LONG);

Returns

The return value specifies whether the asynchronous resolution request was successful. If the extension was successful, the actual return value is an asynchronous task handle. If the function was not successful, a 0 is returned.

Remarks

When the asynchronous operation is complete, the application's window hWnd receives the message returned by RegisterWindowMessage with "WinAsyncCSV" as the input string. The wParam argument contains the asynchronous task handle returned by the original function call. The lParam argument contains the original VCB pointer and can be dereferenced to determine the final return code.

If the function returns successfully, a WinAsyncCSV( ) message will be posted to the application when the operation completes or the conversation is canceled.


WinCSVStartup( )
CSV Extensions for the Windows Environment	4 of 4

WinCSVStartup( )

Allows an application to specify the version of Windows CSV required and to retrieve details of the specific Windows CSV implementation. This function must be called by an application before issuing any further Windows CSV calls to register itself with a Windows CSV implementation.

Syntax

int WINAPI WinCSVStartup(WORD wVersionRequired, LPWCSVDATA);

Parameter	Description

wVersionRequired	Specifies the version of Windows CSV support required. The high-order byte specifies the minor version (revision) number; the low-order byte specifies the major version number.

LPWCSVDATA	Contains information about the underlying Windows CSV DLL implementation. The first wVersion field has the same structure as the wVersionRequired parameter and the szDescription field contains a string identifying the vendor of the Windows CSV DLL. The description field is only meant to provide a display string for the application and should not be used to programatically distinguish between Windows CSV implementations.

Returns

The return value specifies whether the application was registered successfully and whether the Windows CSV implementation can support the specified version number. If the value is 0, it was registered successfully. Otherwise, the return value is one of the following:

WCSVSYSNOTRERADY

Indicates that the underlying network subsystem is not ready for network communication.

WCSVVERNOTSUPPORTED

The version of Windows CSV support requested is not provided by this particular Windows CSV implementation.

WCSVINVALID

The Windows CSV version specified by the application is not supported by this DLL.

Remarks

In order to support future Windows CSV implementations and applications that may have functionality differences from Windows CSV version 1.0, a negotiation takes place in WinCSVStartup( ). An application passes to WinCSVStartup( ) the Windows CSV version that it can use. If this version is lower than the lowest version supported by the Windows CSV DLL, the DLL cannot support the application and WinCSVStartup( ) fails. If the version is not lower, however, the call succeeds and returns the highest version of Windows CSV 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 CSV DLL on the system.

This negotiation allows both a Windows CSV DLL and a Windows CSV application to support a range of Windows CSV versions. An application can successfully use a DLL if there is any overlap in the versions. The following table illustrates how WinCSVStartup( ) works in conjunction with different application and DLL versions.

App versions		DLL versions		To WinCSVStartup( )		From WinCSVStartup( )	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		WCSVINVALID	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
Details of the actual Windows CSV implementation are described in the WCSVDATA structure defined as follows:

typedef struct tagWCSVDATA { WORD wVersion;

char szDescription[WCSVDESCRIPTION_LEN+1];

} WCSVDATA, FAR *LPWCSVDATA;

Having made its last Windows CSV call, an application should call WinCSVCleanup.

Each Windows CSV implementation must make a WinCSVStartup( ) call before issuing any other Windows CSV calls. Consequently, this function can be used for initialization purposes.


tc "Return Codes"Common APPC Return Codes
Appendix A	1 of 3

Common APPC Return Codes

This appendix describes the primary and, if applicable, secondary return codes for the APPC verbs. The return codes are listed in hexadecimal order.


Primary Return Codes
Common APPC Return Codes	2 of 3

Primary Return Codes

0000

AP_OK

The verb executed successfully.

0001

AP_PARAMETER_CHECK

The verb did not execute because of a parameter error.

0002

AP_STATE_CHECK

The verb did not execute because it was issued in an invalid state.

0003

AP_ALLOCATION_ERROR

APPC has failed to allocate a conversation. The conversation state is set to RESET.

This code may be returned through a verb issued after [MC_]ALLOCATE.

0005

AP_DEALLOC_ABEND

The conversation has been deallocated for one of the following reasons:

The partner TP issued MC_DEALLOCATE with dealloc_type set to AP_ABEND.

The partner TP encountered an ABEND, causing the partner LU to send an MC_DEALLOCATE request.

0006

AP_DEALLOC_ABEND_PROG (for a Basic conversation)

The conversation has been deallocated for one of the following reasons:

The partner TP has issued DEALLOCATE with dealloc_type set to AP_ABEND_PROG.

The partner TP has encountered an ABEND, causing the partner LU to send a DEALLOCATE request.

0007

AP_DEALLOC_ABEND_SVC

The conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_SVC.

0008

AP_DEALLOC_ABEND_TIMER

The conversation has been deallocated because the partner TP issued DEALLOCATE with dealloc_type set to AP_ABEND_TIMER.

0009

AP_DEALLOC_NORMAL

The partner TP has deallocated the conversation without requesting confirmation.

000C

AP_PROG_ERROR_NO_TRUNC

The partner TP has issued one of the following verbs while the conversation was in SEND state:

SEND_ERROR with err_type set to AP_PROG

MC_SEND_ERROR

Data was not truncated.

000F

AP_CONV_FAILURE_RETRY

The conversation was terminated because of a temporary error. Restart the TP to see if the problem occurs again. If it does, the system administrator should examine the error log to determine the cause of the error.

0010

AP_CONV_FAILURE_NO_RETRY

The conversation was terminated because of a permanent condition, such as a session protocol error. The system administrator should examine the system error log to determine the cause of the error. Do not retry the conversation until the error has been corrected.

0011

AP_SVC_ERROR_NO_TRUNC

While in SEND state, the partner TP (or partner LU) issued SEND_ERROR with err_type set to AP_SVC. Data was not truncated.

0012

AP_PROG_ERROR_TRUNC/AP_SVC_ERROR_TRUNC

In SEND state, after sending an incomplete logical record, the partner TP issued SEND_ERROR. The local TP may have received the first part of the logical record.

0013

AP_SVC_ERROR_PURGING

The partner TP (or partner LU) issued SEND_ERROR with err_type set to AP_SVC while in RECEIVE, PENDING_POST (Windows NT and OS/2 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state. Data sent to the partner TP may have been purged.

0014

AP_UNSUCCESSFUL

No data is immediately available from the partner TP.

0017

AP_CNOS_LOCAL_RACE_REJECT

APPC is currently processing a CNOS verb issued by a local LU.

0018

AP_CNOS_PARTNER_LU_REJECT

The partner LU rejected a CNOS request from the local LU:

0019

AP_CONVERSATION_TYPE_MIXED

The TP has issued both Basic and Mapped conversation verbs. Only one type can be issued in a single conversation.

0021

AP_CANCELED

The local TP issued one of the following verbs, which canceled [MC_]RECEIVE_AND_POST:

DEALLOCATE with dealloc_type set to AP_ABEND_PROG, AP_ABEND_SVC, or AP_ABEND_TIMER

MC_DEALLOCATE with dealloc_type set to AP_ABEND

[MC_]SEND_ERROR

TP_ENDED

Issuing one of these verbs causes the semaphore to be cleared.

F002

AP_TP_BUSY

The local TP has issued a call to APPC while APPC was processing another call for the same TP. This may occur if the local TP has multiple threads, and more than one thread is issuing APPC calls using the same tp_id.

F003

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

The system administrator should examine the error log to determine the reason for the ABEND.

F004

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

F005

AP_CONV_BUSY

There can only be one outstanding conversation verb at a time on any conversation.

F006

AP_THREAD_BLOCKING

The calling thread is already in a blocking call.

F008

AP_INVALID_VERB_SEGMENT

The VCB extended beyond the end of the data segment.

F011

AP_UNEXPECTED_DOS_ERROR

The operating system has returned an error to APPC while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. It appears in Intel byte-swapped order. If the problem persists, consult the system administrator.

F015

AP_STACK_TOO_SMALL

The stack size of the application is too small to execute the verb. Increase the stack size of your application.

F020

AP_INVALID_KEY

The supplied key was incorrect.


Secondary Return Codes
Common APPC Return Codes	3 of 3

Secondary Return Codes

00000000

AP_CNOS_ACCEPTED

APPC accepts the session lines and responsibility as specified.

00000001

AP_BAD_TP_ID

The value of tp_id did not match a TP identifier assigned by APPC.

00000002

AP_BAD_CONV_ID

The value of conv_id did not match a conversation identifier assigned by APPC.

00000003

AP_BAD_LU_ALIAS

Secondary return code; APPC cannot find the specified lu_alias among those defined.

000000C4

AP_RCV_IMMD_BAD_FILL (for a BASIC conversation)

The fill parameter was set to an invalid value.

00000004

AP_ALLOCATION_FAILURE_NO_RETRY

The conversation cannot be allocated because of a permanent condition, such as a configuration error or session protocol error. To determine the error, the system administrator should examine the error log file. Do not retry the allocation until the error has been corrected.

00000005

AP_ALLOCATION_FAILURE_RETRY

The conversation could not be allocated because of a temporary condition, such as a link failure. The reason for the failure is logged in the system error log. Retry the allocation.

00000006

AP_INVALID_DATA_SEGMENT

The PIP data was longer than the allocated data segment, or the address of the PIP data buffer was wrong.

00000007

AP_CNOS_NEGOTIATED

APPC accepts the session limits and responsibility as negotiable by the partner LU. Values that can be negotiated are:

plu_mode_session_limit

min_conwinners_source

min_conwinners_target

responsible

drain_target

000000D7

AP_BAD_RETURN_STATUS_WITH_DATA

The specified rtn_status value was not recognized by APPC.

00000011

AP_BAD_CONV_TYPE (for a Basic conversation)

The value specified for conv_type was invalid.

00000012

AP_BAD_SYNC_LEVEL

The value specified for sync_level was invalid.

00000013

AP_BAD_SECURITY

The value specified for security was invalid.

00000014

AP_BAD_RETURN_CONTROL

The value specified for rtn_ctl was invalid.

00000016

AP_PIP_LEN_INCORRECT

The value of pip_dlen was greater than 32,767.

00000017

AP_NO_USE_OF_SNASVCMG (for a Mapped conversation)

SNASVCMG is not a valid value for mode_name.

00000018

AP_UNKNOWN_PARTNER_MODE

The value specified for mode_name was invalid.

00000031

AP_CONFIRM_ON_SYNC_LEVEL_NONE

The local TP attempted to use [MC_]CONFIRM in a conversation with a synchronization level of AP_NONE. The synchronization level, established by [MC_]ALLOCATE, must be AP_CONFIRM_SYNC_LEVEL.

00000032

AP_CONFIRM_BAD_STATE

The conversation was not in SEND state.

00000033

AP_CONFIRM_NOT_LL_BDY

The conversation for the local TP was in SEND state, and the local TP did not finish sending a logical record.

00000051

AP_DEALLOC_BAD_TYPE

The dealloc_type parameter was not set to a valid value.

00000053

AP_DEALLOC_CONFIRM_BAD_STATE

The conversation was not in SEND state, and the TP attempted to flush the send buffer and send a confirmation request.

00000055

AP_DEALLOC_NOT_LL_BDY (for a Basic conversation)

The conversation was in SEND state, and the TP did not finish sending a logical record. The dealloc_type parameter was set to AP_SYNC_LEVEL or AP_FLUSH.

00000057

AP_DEALLOC_LOG_LL_WRONG

The LL field of the GDS error log variable did not match the actual length of the log data.

00000061

AP_FLUSH_NOT_SEND_STATE

The conversation was not in SEND state.

000000A1

AP_P_TO_R_INVALID_TYPE

The ptr_type parameter was not set to a valid value.

000000A2

AP_P_TO_R_NOT_LL_BDY

The local TP did not finish sending a logical record.

000000A3

AP_P_TO_R_NOT_SEND_STATE

The conversation was not in SEND state.

000000B1

AP_RCV_AND_WAIT_BAD_STATE

The conversation was not in RECEIVE or SEND state when the TP issued this verb.

000000B2

AP_RCV_AND_WAIT_NOT_LL_BDY (for a Basic conversation)

The conversation was in SEND state; the TP began but did not finish sending a logical record.

000000B5

AP_RCV_AND_WAIT_BAD_FILL (for a Basic conversation)

The fill parameter was set to an invalid value.

000000C1

AP_RCV_IMMD_BAD_STATE

The conversation was not in RECEIVE state.

000000D1

AP_RCV_AND_POST_BAD_STATE

The conversation was not in RECEIVE or SEND state when the TP issued this verb.

000000D2

AP_RCV_AND_POST_NOT_LL_BDY

The conversation was in SEND state; the TP began but did not finish sending a logical record.

000000D5

AP_RCV_AND_POST_BAD_FILL

The fill parameter was set to an invalid value.

000000D6

AP_INVALID_SEMAPHORE_HANDLE

The address of the RAM semaphore or system semaphore handle was invalid.

Note

APPC cannot trap all invalid semaphore handles. If the TP passes a bad RAM semaphore handle, a protection violation results.

000000D7

AP_BAD_RETURN_STATUS_WITH_DATA

The specified rtn_status value was not recognized by APPC.

000000E1

AP_R_T_S_BAD_STATE

The conversation is not in an allowed state when the TP issued this verb.

000000F1

AP_BAD_LL (for a Basic conversation)

The logical record length field of a logical record contained an invalid value—X'0000', X'0001', X'8000', or X'8001'. See Chapter 2, "Transaction Programs," for information on logical records.

000000F2

AP_SEND_DATA_NOT_SEND_STATE

The local TP issued [MC_]SEND_DATA, but the conversation was not in SEND state.

000000F5

AP_SEND_DATA_CONFIRM_ON_SYNC_NONE

The type CONFIRM is not permitted for a conversation that was allocated with a sync_level of NONE.

000000F6

AP_SEND_DATA_NOT_LL_BDY (for a Basic conversation)

The TP started but did not finish sending a logical record. This occurs only when type is one of the following:

AP_SEND_DATA_CONFIRM

AP_SEND_DATA_DEALLOC_FLUSH

AP_SEND_DATA_DEALLOC_SYNC_LEVEL

AP_SEND_DATA_P_TO_R_FLUSH

AP_SEND_DATA_P_TO_R_SYNC_LEVEL

00000102

AP_SEND_ERROR_LOG_LL_WRONG (for a Basic conversation)

The LL field of the error log GDS variable did not match the actual length of the data.

00000103

AP_SEND_ERROR_BAD_TYPE (for a Basic conversation)

The value of err_type was invalid.

00000105

AP_BAD_ERROR_DIRECTION

The specified err_dir was not recognized by APPC.

00000150

AP_CNOS_IMPLICIT_PARALLEL

APPC does not permit a program to change the session limit for a mode other than SNASVCMG mode for the implicit partner template when the template specifies parallel sessions. (The term template is used because many of the actual values are yet to be filled in).

00000151

AP_CANT_RAISE_LIMITS

APPC does not permit setting session limits to a nonzero value unless the limits currently are 0.

00000152

AP_AUTOACT_EXCEEDS_SESSLIM

On the CNOS verb, the value for auto_activate is greater than the value for partner_lu_mode_session_limit.

00000153

AP_ALL_MODE_MUST_RESET

APPC does not permit a nonzero session limit when mode_name_select indicates ALL.

00000154

AP_BAD_SNASVCMG_LIMITS

Your program specified invalid settings for the partner_lu_mode_session _limit, min_conwinners_source, or min_conwinners_target parameters when mode_name was supplied.

00000155

AP_MIN_GT_TOTAL

The sum of min_conwinners_source and min_conwinners_target specifies a number greater than partner_lu_mode_session_limit.

00000156

AP_MODE_CLOSED

The local LU cannot negotiate a nonzero session limit because the local maximum session limit at the partner LU is 0.

00000156

AP_CNOS_MODE_CLOSED

The local LU cannot negotiate a nonzero session limit because the local maximum session limit at the partner LU is 0.

00000157

AP_CNOS_MODE_NAME_REJECT

The partner LU does not recognize the specified mode name.

00000159

AP_RESET_SNA_DRAINS

The SNASVCMG mode does not support the drain parameter values.

0000015A

AP_SINGLE_NOT_SRC_RESP

For a single-session CNOS verb, APPC permits only the local (source) LU to be responsible for deactivating sessions.

0000015B

AP_BAD_PARTNER_LU_ALIAS

APPC did not recognize the supplied partner_lu_alias.

0000015C

AP_EXCEEDS_MAX_ALLOWED

Your program issued a CNOS verb, specifying a partner_lu_mode _session_limit number and set_negotiable (NO).

0000015D

AP_CHANGE_SRC_DRAINS

APPC does not permit mode_name_select (ONE) and drain_source (YES) when drain_source (NO) is currently in effect for the specified mode.

0000015E

AP_LU_DETACHED

A command has reset the definition of the local LU before the CNOS verb tried to specify the LU.

0000015F

AP_CNOS_COMMAND_RACE_REJECT

The local LU is currently processing a CNOS verb issued by the partner LU.

00000167

AP_SNASVCMG_RESET_NOT_ALLOWED

Your local program attempted to issue the CNOS verbs for the mode named SNASVCMG, specifying a session limit of 0.

000001B4

AP_DISPLAY_INFO_EXCEEDS_LENGTH

The returned DISPLAY information did not fit in the buffer.

000001B5

DISPLAY_INVALID_CONSTANT

The value supplied for NUM_SECTIONS or INIT_SEC_LEN is invalid.

00000506

AP_UNDEFINED_TP_NAME

Secondary return code; in the configuration file for your application, APPC could not find an invokable TP name matching the value of tp_name.

00000509

AP_ALLOCATE_NOT_PENDING

APPC did not find an incoming allocate (from the invoking TP) to match the value of tp_name, supplied by RECEIVE_ALLOCATE. RECEIVE_ALLOCATE waited for the incoming allocate and eventually timed out.

00000519

AP_CPSVCMG_MODE_NOT_ALLOWED

The mode named CPSVCMG cannot be specified as the mode_name on the DEACTIVATE_SESSION verb.

00000525

AP_INVALID_PROCESS

The process issuing RECEIVE_ALLOCATE was different from the one started by APPC.

080F6051

AP_SECURITY_NOT_VALID

The user ID or password specified in the allocation request was not accepted by the partner LU.

084B6031

AP_TRANS_PGM_NOT_AVAIL_RETRY

The remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition may be temporary, such as a time-out. The reason for the error may be logged on the remote node. Retry the allocation.

084C0000

AP_TRANS_PGM_NOT_AVAIL_NO_RETRY

The remote LU rejected the allocation request because it was unable to start the requested partner TP. The condition is permanent. The reason for the error may be logged on the remote node. Do not retry the allocation until the error has been corrected.

10086021

AP_TP_NAME_NOT_RECOGNIZED

The partner LU does not recognize the TP name specified in the allocation request.

10086031

AP_PIP_NOT_ALLOWED

The allocation request specified PIP data, but either the partner TP does not require this data, or the partner LU does not support it.

10086032

AP_PIP_NOT_SPECIFIED_CORRECTLY

The partner TP requires PIP data, but the allocation request specified either no PIP data or an incorrect number of parameters.

10086034

AP_CONVERSATION_TYPE_MISMATCH

The partner LU or TP does not support the conversation type (Basic or Mapped) specified in the allocation request.

10086041

AP_SYNC_LEVEL_NOT_SUPPORTED

The partner TP does not support the sync_level (AP_NONE or AP_CONFIRM_SYNC_LEVEL) specified in the allocation request, or the sync_level was not recognized.


Common CSV Return Codes
Appendix B	1 of 3

Common CSV Return Codes

This appendix describes the primary and, if applicable, secondary return codes for CSV. The return codes are listed in hexadecimal order.


Primary Return Codes
Common CSV Return Codes	2 of 3

Primary Return Codes

0000

SV_OK

The verb executed successfully.

0001

SV_PARAMETER_CHECK

The verb did not execute because of a parameter error.

0002

SV_STATE_CHECK

The verb did not execute because it was issued in an invalid state.

0021

SV_CANCELLED

This code is returned for an asynchronous verb when it has been shut down by a WinCSVCleanup call.

0030

SV_FILE_ALREADY_EXISTS

When the SV_NEW file option was used, the filename specified was the name of an existing file.

0031

SV_OUTPUT_DEVICE_FULL

There is insufficient space on the device where the output file resides. Retry the operation after freeing additional disk space.

F006

SV_THREAD_BLOCKING

This verb exceeds the maximum number of simultaneous synchronous verbs allowed.

F008

SV_INVALID_VERB_SEGMENT

The VCB extended beyond the end of the data segment.

F011

SV_UNEXPECTED_DOS_ERROR

One of the following conditions has occurred:

The Windows NT, Windows version 3.x, MS-DOS, or OS/2 system encountered an error while processing the verb. The operating system return code was returned through the secondary return code. If the problem persists, contact the system administrator for corrective action.

A CSV was issued from a message loop that was invoked by another application issuing a Windows environment SendMessage function call, rather than the more common Windows environment PostMessage function call. Verb processing cannot take place.

A CSV was issued when SendMessage invoked your application. You can determine whether your application has been invoked with SendMessage by using the InSendMessage Windows API function call.

F012

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

F024

SV_SERVER_RESOURCE_NOT_FOUND

No communication server was found that could provide the requested function.

F026

SV_SERVER_RESOURCE_LOST

The communications server that was providing the function was lost due to a connection failure.

FFFF

SV_INVALID_VERB

The opcode parameter did not match the operation code of any verb. No verb executed.


Secondary Return Codes
Common CSV Return Codes	3 of 3

Secondary Return Codes

00000006

SV_INVALID_DATA_SEGMENT

The data buffer containing the source or target string did not fit in one segment, or the target segment was not a read/write segment. This applies only to the Windows and OS/2 systems.

00000301

SV_SSCP_PU_SESSION_NOT_ACTIVE

The NMVT was not sent; either the SSCP-PU session was not active, the node configured to receive diagnostic information was not active, or no network management connection was configured.

00000302

SV_DATA_EXCEEDS_RU_SIZE

The data to be sent was too long. The length of the user-supplied data plus headers and added subvectors must fit in a single RU that is not more than 512 bytes long.

00000303

SV_INVALID_DATA_TYPE

The data_type parameter contained an invalid value.

00000401

SV_INVALID_DIRECTION

The direction parameter contained an invalid value.

00000402

SV_INVALID_CHARACTER_SET

The char_set parameter contained an invalid value.

00000404

SV_INVALID_FIRST_CHARACTER

The first character of a type A source string was invalid.

00000405

SV_TABLE_ERROR

One of the following occurred:

The file containing the user-written type G conversion table was not specified by the environment variable CSVTBLG.

The table was not in the correct format.

The file specified by the CSVTBLG variable was not found.

00000406

SV_CONVERSION_ERROR

One or more characters in the source string were not found in the conversion table. These characters were converted to nulls (X'00'). The verb still executed.

00000621

SV_INVALID_MESSAGE_ACTION

The msg_act parameter contained an invalid value.

00000624

SV_INVALID_SET

The dt_set parameter contained an invalid value.

00000629

SV_COPY_TRACE_IN_PROGRESS

A previously issued COPY_TRACE_TO_FILE is still in progress.

0000062A

SV_TRACE_NOT_STOPPED

A trace was in progress when the verb was issued.

0000062B

SV_INVALID_FILE_OPTION

A value other than SV_NEW or SV_OVERWRITE was specified for file_option.

0000062C

SV_TRACE_BUFFER_EMPTY

The trace storage buffer did not contain any data.

0000062F

SV_INVALID_RESET_TRACE

The reset_trc parameter contained an invalid value.

00000630

SV_INVALID_CHAR_NOT_FOUND

The char_not_fnd parameter contained an invalid value.

00000631

SV_INVALID_SOURCE_CODE_PAGE

The code page specified by source_cp is not supported.

00000632

SV_INVALID_TARGET_CODE_PAGE

The code page specified by target_cp is not supported.

030000AB

SV_SERVER_COMM_FAILURE

The connection to the server was lost due to physical path problems; for example, the server may have been powered off.


Sample APPC TPs in the SDK
Appendix C	1 of 6

Sample APPC TPs in the SDK

This appendix describes the APPC TP samples in the SNA Server SDK. The samples are located in the \SDK\SAMPLES directory on the SNA Server CD.

TP		Description
APPC Send and Receive TPs		Simple APPC TPs that illustrate the use of asynchronous verb completion
Multithreaded Send and Receive TPs		More advanced APPC TPs that illustrate the use of multiple threads and multiple conversations per thread
In addition to the TPs, the following supplemental programs are included on the SNA Server CD.

Supplemental program		Description
TPSETUP		Sample installation program, demonstrating an interface that assists in the configuring of autostarted invokable TPs. Located in the \SAMPLES\SDK directory on the CD.
TPSTART		A program required by autostarted invokable TPs that run as applications under Windows NT; installed by SNA Server Setup in the SYSTEM subdirectory of the SNA Server root directory.


Building the TPs
Sample APPC TPs in the SDK	2 of 6

Building the TPs

All the sample TPs are built in a similar way, as described in this section. First, set the following environment variables:

Variable	Specify

ISVLIBS	Directory containing the SNA Server Windows NT .LIB files

ISVINCS	Directory containing the WINSNA header files

SAMPLEROOT	Root directory of the sample code

For example, if the two SDK disks are copied with XCOPY into C:\SNASDK, use the following lines to set the variables:

ISVLIBS=C:\SNASDK\WINSNA\LIB\WINNT

ISVINCS=C:\SNASDK\WINSNA\INC

SAMPLEROOT=C:\SNASDK\SAMPLES

Next, run NMAKE on the .MAK file in each directory. For example, for APING and APINGD, type the following:

nmake -f makeping.mak


TPSETUP
Sample APPC TPs in the SDK	3 of 6

TPSETUP

TPSETUP is a program that simplifies the setting of Registry or environment variables needed by autostarted invokable TPs. Without an interface like that provided by TPSETUP, configuring of such variables can be complicated and error prone. Therefore, it is recommended that you use code like TPSETUP in installation programs for autostarted invokable TPs.

Operation

INSTALL.C, the source code for TPSETUP, can be compiled to work either in the Windows NT environment or in the Windows version 3.x environment. TPSETUP has been constructed so that the program responds correctly in each environment.

For clients running Windows NT, it is recommended that autostarted invokable TPs be written as Windows NT services. For the installation program for such TPs, study the code in INSTALL.C. For example, use the CreateService function or similar code when installing a TP that will run as a service under Windows NT. (For important information about how services work under Windows NT, see the documentation for Windows NT and for Win32 [image].)


TPSTART
Sample APPC TPs in the SDK	4 of 6

TPSTART

An autostarted TP that runs as an application under Windows NT requires the support of the TPSTART program, which is installed with the SNA server software in the SYSTEM subdirectory of the SNA Server root directory. Therefore, the TPSTART program must be started on a Windows NT-based client before an autostarted invokable TP can be started as an application. Starting TPSTART can be accomplished by using standard Windows NT methods, such as including TPSTART in the Startup group on the client.


APPC Send and Receive TPs
Sample APPC TPs in the SDK	5 of 6

APPC Send and Receive TPs

These are simple APPC TPs that illustrate the use of asynchronous verb completion.

Setup

To set up these TPs, create an appropriate APPC LU-LU-mode triplet. The default is SENDLU-RECVLU-#INTER, but this can be configured (see the following sections).

Input and Output

The APPC send and receive TPs each use a configuration file for input. To name the file, use .CFG as the extension, and use the same base filename and directory location as the executable (the TP itself).

For SENDTP, the *.CFG file can contain the following items, one per line, in any order. If a variable is not found in the file, or the file is not present at all, the default is used.

Line		Default		Value to supply
ResultFile =		C:\SENDTP.OUT		Filename to print timings to
LocalLUAlias =		SENDLU		Local LU Alias
RemoteLUAlias =		RECVLU		Remote LU Alias
ModeName =		#INTER		Mode name
LocalTPName =		SENDTP		Name of local TP
RemoteTPName =		RECVTP		Name of remote TP
NumConversations =		1		Number of conversations
NumSends =		2		Number of SEND_DATA verbs per conversation
SendSize =		1024		Size in bytes of data sent each time
ConfirmEvery =		1		Number of SEND_DATA verbs between CONFIRM verbs
SendConversation =		No		Yes or No: Use the SEND_CONVERSATION verb rather than the sequence of ALLOCATE, SEND_DATA, DEALLOCATE
RECVTP uses a *.CFG file in a similar way, but only to read the LocalTPName field.

The output from SENDTP and RECVTP consists of details of the configuration and the time taken for each conversation, and is sent to the result file specified in SENDTP.CFG.

Operation

RECVTP should be started first; it issues RECEIVE_ALLOCATE with the specified TP name. SENDTP is then started; it first issues MC_SEND_CONVERSATION to tell RECVTP how many conversations will be carried out. It then carries out the specified number of conversations.

For SENDTP, each conversation consists of an MC_ALLOCATE verb, followed by a given number of MC_SEND_DATA verbs of a given size, and interspersed with MC_CONFIRM verbs at a given interval, followed by an MC_DEALLOCATE.

RECVTP issues MC_RECEIVE_AND_WAIT when RECEIVE_ALLOCATE completes, and then issues either MC_RECEIVE_AND_WAIT or MC_CONFIRMED according to the return from the previous MC_RECEIVE_AND_WAIT.

At any stage, if the TPs encounter an error, they terminate. Use APPC API tracing to diagnose problems with the configuration.

At the end of the specified number of conversations, SENDTP sends timing information to a file.

Both TPs are built from a single source-code file, SENDRECV.C. SENDTP is compiled only if -DSENDTP is used on the command line.

The TPs run as Windows NT applications with a minimized window, the title bar of which displays the status. When the WndProc of this window, TPWndProc, receives the WM_CREATE message for the window, this triggers the issuing of the first verb. When TPWndProc receives an ASYNC_COMPLETE message from Windows APPC, this triggers the issuing of the next verb, dependent on what the previous verb was. When the window is closed, WinAPPCCleanup is issued to terminate any active conversations.


Multithreaded Send and Receive TPs
Sample APPC TPs in the SDK	6 of 6

Multithreaded Send and Receive TPs

These send and receive TPs are more advanced than the single-threaded equivalents. They all use the asynchronous interface of APPC, with verb completion signaled by events (WinAsyncAPPCEx). These TPs show how to code multithreaded APPC applications with multiple conversations per thread. They are more complex than the single-threaded equivalents, but also more realistic.

If you are unfamiliar with APPC, examine the single-threaded TPs first. If you are unfamiliar with methods in Windows NT of creating threads or processing events, see the Win32 SDK documentation along with the multithreaded TPs.

Setup

There are three multithreaded send and receive routines:

MSEND for sending

MRCV for receiving

MSENDRCV for simultaneous sending and receiving

To set up these TPs, create an appropriate APPC LU-LU-mode triplet. The default is SENDLU-RECVLU-#INTER, but this can be configured (see the sections that follow). To run a large number of simultaneous conversations, increase the session limits for #INTER (or use another mode with large session limits).

One obvious way of configuring these programs is to configure MSEND to run with MRCV; another way is to configure MSENDRCV to run with another copy of MSENDRCV. However, you can also configure MSEND to run with one or more copies of RECVTP (the single-threaded version) and MRCV to run with one or more copies of SENDTP. You can also configure MSENDRCV to run with MSEND, MRCV, SENDTP or RECVTP. For more information, see the sections that follow.

One possible arrangement is to place SENDTP (single-threaded) on multiple client computers, and configure MRCV (multithreaded) on a server so that it interacts with all the TPs on the clients. Many other arrangements are possible.

Input and Output

Each TP uses a configuration file for input. To name the file, use .CFG as the extension, and use the same base filename and directory location as the executable (the TP itself).

The following table shows examples of *.CFG files that could be used with MSEND and MRCV.

Example of MSEND.CFG file		Example of MRCV.CFG file
ResultFile=MSEND.OUT		TraceFile=MRCV.TRC
TraceFile=MSEND.TRC		LocalTPName=MRCVTP
RemoteTPName=MRCVTP		NumRcvConvs=32
LocalLUAlias=LUA		NumRcvThreads=4
RemoteLUAlias=LUB		RcvSize=4096
ModeName=#INTER
NumSendConvs=32
NumSends=128
ConfirmEvery=16
SendSize=256
For MSEND, the *.CFG file can contain the following items, one per line, in any order. If a variable is not found in the file, or the file is not present at all, the default is used.

Line		Default		Value to supply
ResultFile =		MSEND.OUT		Filename to print timings to (located in default directory for MSEND)
TraceFile =		MSEND.TRC		Trace file name (located in default directory for MSEND)
LocalLUAlias =		SENDLU		Local LU Alias
RemoteLUAlias =		RECVLU		Remote LU Alias
ModeName =		#INTER		Mode name
RemoteTPName =		MRCVTP		Name of remote TP (for MC_ALLOCATE)
NumSendConvs =		4		Number of conversations to send
NumSends =		8		Number of MC_SEND_DATA verbs per conversation
SendSize =		256		Size in bytes of data sent each time
ConfirmEvery =		2		Number of MC_SEND_DATA verbs between MC_CONFIRM verbs
The following lines are for MRCV:

Line		Default		Value to supply
TraceFile =		MRCV.TRC		Trace file name (located in default directory for MSEND)
LocalTPName =		MRCVTP		Name of local TP (for RECEIVE_ALLOCATE)
NumRcvConvs =		4		Number of conversations to receive
NumRcvThreads =		2		Number of threads to start for processing receive conversations
RcvSize =		4096		Size in bytes of receive buffer for MC_RECEIVE_AND_WAIT
The following table shows examples of *.CFG files that could be used with MSENDRCV.

Example A of MSENDRCV.CFG (to use on one of a pair of computers; works in conjunction with example of MSENDRCV.CFG shown in other column)		Example B of MSENDRCV.CFG (to use on one of a pair of computers; works in conjunction with example of MSENDRCV.CFG shown in other column)
ResultFile=MSENDRCV.OUT		ResultFile=MSENDRCV.OUT
TraceFile=MSENDRCV.TRC		TraceFile=MSENDRCV.TRC
LocalTPName=TPA		LocalTPName=TPB
RemoteTPName=TPB		RemoteTPName=TPA
LocalLUAlias=LUA		LocalLUAlias=LUB
RemoteLUAlias=LUB		RemoteLUAlias=LUA
ModeName=#INTER		ModeName=#INTER
NumRcvConvs=50		NumRcvConvs=25
NumRcvThreads=4		NumRcvThreads=4
RcvSize=4096		RcvSize=4096
NumSendConvs=25		NumSendConvs=50
NumSends=100		NumSends=100
ConfirmEvery=10		ConfirmEvery=10
SendSize=256		SendSize=256
The following lines are for MSENDRCV:

Line		Default		Value to supply
ResultFile =		MSENDRCV.OUT		Filename to print timings to (located in default directory for MSEND)
TraceFile =		MSENDRCV.TRC		Trace file name (located in default directory for MSEND)
LocalLUAlias =		SENDLU		Local LU Alias
RemoteLUAlias =		RECVLU		Remote LU Alias
ModeName =		#INTER		Mode name
RemoteTPName =		MRCVTP		Name of remote TP (for MC_ALLOCATE)
NumSendConvs =		4		Number of conversations to send
NumSends =		8		Number of MC_SEND_DATA verbs per conversation
SendSize =		256		Size in bytes of data sent each time
ConfirmEvery =		2		Number of MC_SEND_DATA verbs between MC_CONFIRM verbs
LocalTPName =		MRCVTP		Name of local TP (for RECEIVE_ALLOCATE)
NumRcvConvs =		4		Number of conversations to receive
NumRcvThreads =		2		Number of threads to start for processing receive conversations
RcvSize =		4096		Size in bytes of receive buffer for MC_RECEIVE_AND_WAIT
The output from MSEND and MSENDRCV consists of details of the configuration and the time taken for each conversation, and is sent to the result file specified in MSEND.CFG or MSENDRCV.CFG.

Operation

These TPs use Windows NT-based multiple event processing to avoid creating an unnecessary number of threads.

The TPs also use Windows-based processing, but this is incidental. Its only purpose is to display, beneath the icon on the screen, a running count of threads, the number of conversations currently sending or receiving data, and the number of conversations completed. The Windows-based processing could easily be removed to create a completely batch-oriented program. To do this, termination would need to be signaled with an event rather than with WM_CLOSE.

The TP name used in TP_STARTED is the name of the executable (MSEND, MRCV, or MSENDRCV). The TP names used in MC_ALLOCATE and RECEIVE_ALLOCATE can be configured, as shown in the preceding tables.

MSEND reads its configuration file (or uses defaults) to determine the number of send conversations to start. Each conversation reads the value of NumSends (or uses the default), issues that number of MC_SEND_DATA verbs, and then terminates. When all of the conversations for a thread have terminated, the thread itself terminates. When all of the send threads have terminated, the program terminates.

An MC_CONFIRM verb is issued before the first MC_SEND_DATA and then at the intervals specified by ConfirmEvery. The complete data flow for a conversation is as follows:

TP_STARTEDMC_ALLOCATEMC_CONFIRM

MC_SEND_DATA (repeated the number of times specified by ConfirmEvery)MC_CONFIRMMC_SEND_DATA (repeated the number of times specified by ConfirmEvery)MC_CONFIRM (Pattern repeats until the number of MC_SEND_DATA verbs equals NumSends.)

MC_DEALLOCATETP_ENDED

MRCV starts up an initial thread for issuing RECEIVE_ALLOCATE verbs, then reads its configuration file (or uses defaults) to determine the number of receive threads to start and the number of conversations to receive.The initial thread issues a RECEIVE_ALLOCATE and waits. When the RECEIVE_ALLOCATE completes, the initial thread turns the processing of the conversation over to the next available receive thread, and issues another RECEIVE_ALLOCATE. This process continues until the configured number of RECEIVE_ALLOCATE verbs (that is, NumRcvConvs) have completed.

There is a limit to the number of conversations that can be supported on a thread, because of the limit to the number of events that can be waited for with WaitForMultipleObjects (a function in the Win32 API). For send threads, the limit is 64 conversations per thread; for receive threads, the limit is 63 conversations per thread.

MSEND works with this limit by starting enough threads to support the configured number of conversations. For example, if NumSendConvs is set to 200, 4 send threads are started: 3 of them process 64 conversations each and 1 processes the remaining 8 conversations.

MRCV works with this limit by comparing NumRcvConvs to NumRcvThreads. If NumRcvConvs is more than (63 * NumRcvThreads), NumRcvThreads is increased. If NumRcvThreads is greater than NumRcvConvs, NumRcvThreads is reduced to prevent unneeded threads being created.

With MRCV, to ensure that a receive thread correctly picks up the conversation, two special events are used per thread: event1 and event2. The following table illustrates their use.

RECEIVE_ALLOCATE thread		Receive thread
Issue RECEIVE_ALLOCATE and wait		Wait on event1
(RECEIVE_ALLOCATE completes)
Select next receive thread and set event1 for that thread;then wait on event2 for that thread
		(Event1 completes)
		Add conversation to list of conversations being processed
		Set event2
(Event2 completes)
REPEAT		REPEAT
The receive thread waits not only on the event1 set for it, but also on one event for each conversation the thread is processing.

If NumRcvConvs is set to 0, the RECEIVE_ALLOCATE thread will never terminate. If NumSends is set to 0, the conversation will never terminate; this is useful for getting the maximum number of simultaneous conversations.

Tracing

If you want to observe the detailed processing of these TPs, you can enable tracing. To do this, find the following line, commented out, near the top of the file:

#define SRTRC

Enable this line, and trace statements will be written to the trace file(s) specified by the TraceFile variable.

There are also some trace statements that have been commented out. If they are left commented out, while a conversation is running, only MC_CONFIRM and MC_CONFIRMED processing is traced, to maintain a send or receive count without generating a large amount of trace information. You can activate the detailed tracing of events (such as the sending of data) by enabling one or more trace statements.

The snatrace utility provides another useful type of tracing: APPC API tracing (for SNA Applications). For more information about the snatrace utility, see Chapter 13 of the Microsoft SNA Server Administration Guide.