Contents for Windows APPC Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Programming with Windows APPC

  APPC TP Verbs

  APPC Conversation Verbs

  APPC Receive Verbs

  APPC Send Verbs

  Extensions for the Windows Environment

  Return Codes


Contents for Windows APPC Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Windows APPC Overview

  Before Using Windows APPC

  Microsoft Windows Graphical Environment and Windows Specific Extensions

  Programming with Windows APPC

  APPC TP Verbs

  APPC Conversation Verbs

  APPC Receive Verbs

  APPC Send Verbs

  Extensions for the Windows Environment

  Return Codes


Contents for Windows APPC Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Programming with Windows APPC

  Windows APPC Installation Checking

  Windows APPC Programming Considerations

  Overview of the Windows APPC Verbs

  Default LUs

  APPC TP Verbs

  APPC Conversation Verbs

  APPC Receive Verbs

  APPC Send Verbs

  Extensions for the Windows Environment

  Return Codes


Contents for Windows APPC Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Programming with Windows APPC

  APPC TP Verbs

  GET_TP_PROPERTIES: Description and Syntax

  GET_TP_PROPERTIES: Return Codes

  GET_TP_PROPERTIES: Remarks

  TP_ENDED: Description and Syntax

  TP_ENDED: Return Codes

  TP_ENDED: Remarks

  TP_STARTED: Description and Syntax

  TP_STARTED: Return Codes

  TP_STARTED: Remarks

  APPC Conversation Verbs

  APPC Receive Verbs

  APPC Send Verbs

  Extensions for the Windows Environment

  Return Codes


Contents for Windows APPC Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Programming with Windows APPC

  APPC TP Verbs

  APPC Conversation Verbs

  [MC_]ALLOCATE: Description and Syntax

  [MC_]ALLOCATE: Return Codes

  [MC_]ALLOCATE: Remarks

  [MC_]CONFIRM: Description and Syntax

  [MC_]CONFIRM: Return Codes

  [MC_]CONFIRM: Remarks

  [MC_]CONFIRMED: Description and Syntax

  [MC_]CONFIRMED: Return Codes

  [MC_]CONFIRMED: Remarks

  [MC_]DEALLOCATE: Description and Syntax

  [MC_]DEALLOCATE: Return Codes

  [MC_]DEALLOCATE: Remarks

  [MC_]FLUSH: Description and Syntax

  [MC_]FLUSH: Return Codes

  [MC_]FLUSH: Remarks

  [MC_]GET_ATTRIBUTES: Description and Syntax

  [MC_]GET_ATTRIBUTES: Return Codes and Remarks

  GET_TYPE: Description and Syntax

  GET_TYPE: Return Codes and Remarks

  [MC_]TEST_RTS: Description and Syntax

  [MC_]TEST_RTS: Return Codes and Remarks

  APPC Receive Verbs

  APPC Send Verbs

  Extensions for the Windows Environment

  Return Codes


Contents for Windows APPC Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Programming with Windows APPC

  APPC TP Verbs

  APPC Conversation Verbs

  APPC Receive Verbs

  [MC_]PREPARE_TO_RECEIVE: Description and Syntax

  [MC_]PREPARE_TO_RECEIVE: Return Codes

  [MC_]PREPARE_TO_RECEIVE: Remarks

  RECEIVE_ALLOCATE: Description and Syntax

  RECEIVE_ALLOCATE: Return Codes

  RECEIVE_ALLOCATE: Remarks

  [MC_]RECEIVE_AND_POST: Description and Syntax

  [MC_]RECEIVE_AND_POST: Return Codes

  [MC_]RECEIVE_AND_POST: Remarks

  [MC_]RECEIVE_AND_WAIT: Description and Syntax

  [MC_]RECEIVE_AND_WAIT: Return Codes

  [MC_]RECEIVE_AND_WAIT: Remarks

  [MC_]RECEIVE_IMMEDIATE: Description and Syntax

  [MC_]RECEIVE_IMMEDIATE: Return Codes

  [MC_]RECEIVE_IMMEDIATE: Remarks

  APPC Send Verbs

  Extensions for the Windows Environment

  Return Codes


Contents for Windows APPC Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Programming with Windows APPC

  APPC TP Verbs

  APPC Conversation Verbs

  APPC Receive Verbs

  APPC Send Verbs

  [MC_]REQUEST_TO_SEND: Description and Syntax

  [MC_]REQUEST_TO_SEND: Return Codes

  [MC_]REQUEST_TO_SEND: Remarks

  [MC_]SEND_CONVERSATION: Description and Syntax

  [MC_]SEND_CONVERSATION: Return Codes

  [MC_]SEND_CONVERSATION: Remarks

  [MC_]SEND_DATA: Description and Syntax

  [MC_]SEND_DATA: Return Codes

  [MC_]SEND_DATA: Remarks

  [MC_]SEND_ERROR: Description and Syntax

  [MC_]SEND_ERROR: Return Codes

  [MC_]SEND_ERROR: Remarks

  Extensions for the Windows Environment

  Return Codes


Contents for Windows APPC Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Programming with Windows APPC

  APPC TP Verbs

  APPC Conversation Verbs

  APPC Receive Verbs

  APPC Send Verbs

  Extensions for the Windows Environment

  Overview

  GetAppcConfig(): Description and Syntax

  GetAppcConfig(): Return Codes

  GetAppcConfig(): Remarks

  GetAppcReturnCode()

  WinAsyncAPPC()

  WinAsyncAPPCEx()

  WinAPPCCancelAsyncRequest()

  WinAPPCCancelBlockingCall()

  WinAPPCCleanup()

  WinAPPCIsBlocking()

  WinAPPCStartup()

  WinAPPCSetBlockingHook()

  WinAPPCUnhookBlockingHook()

  Return Codes


Contents for Windows APPC Specification Help

  Using Help

  Microsoft Support Services

  Introduction

  Programming with Windows APPC

  APPC TP Verbs

  APPC Conversation Verbs

  APPC Receive Verbs

  APPC Send Verbs

  Extensions for the Windows Environment

  Return Codes

  Primary Return Codes

  Secondary Return Codes


Using Help

You can find information in Help by choosing a Help topic or by using the Search feature. To return to the Help contents screen after you read the following instructions, click Back or press B.

For complete instructions on how to use Help, press F1 while Help is active.

To expand a topic list

Click a button showing a closed file folder  [image].

Or press TAB until the intended heading is highlighted, and press ENTER.

To collapse a topic list

Click a button showing an open file folder  [image].

Or press TAB until the intended heading is highlighted, and press ENTER.

To choose a Help topic

Click an underlined topic or a topic with a button  [image].

Or press TAB until the intended topic is highlighted, and then press ENTER.

To return to the previous topic

Click Back or press B.

To use the Search feature

Click Search or press S.

To close Help

From the File menu for Help, choose Exit (ALT, F, X).


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.

This specification defines the standards for source code for Windows APPC applications. These applications can reside on the server, or on a client running Windows NT, Windows, or MS-DOS.

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

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.

Windows APPC 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, see:

[MC_]RECEIVE_AND_POST: Description and Syntax

[MC_]RECEIVE_AND_POST: Remarks

[MC_]RECEIVE_AND_WAIT: Description and Syntax

[MC_]RECEIVE_AND_WAIT: Remarks


Before Using Windows APPC

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

Verbs Containing Important Features

The following Windows 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 Windows APPC that the TP is starting. For a user or group who will be using TPs, 5250 emulators, and/or Windows 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 a Windows APPC program (a TP, 5250 emulator, or APPC application) and the program does not specify LU aliases.

[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, Windows APPC generates a conversation identifier (conv_id). The conv_id is a required parameter for all other Windows APPC conversation verbs.

For a user or group using TPs, 5250 emulators, and/or Windows 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 a Windows APPC program.

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

Extensions for Asynchronous Communication

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

Number of Outstanding Calls Permitted

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

void ProcessVerbCompletion (WPARAM wParam, LPARAM lParam)

{ for (i = 0   i < nPendingVerbs; itt)

if (pPendingVerbs [i].hAsync = = wParam)

ProcessVCB ( (LPVCB) lParam);

}	. . .

LRESULT CALLBACK SampleWndProc ( ... )

{

if (msg = = uAsyncAPPC) {

ProcessVerbCompletion (wParam; lParam);

}

else switch (msg) {

case WM_USER:

if (hAsync = WinAsyncAPPC (hwnd, &vcb) )

pPendingVerbs [nPendingVerbs tt].hAsync = .hAsync;

break;

}

}

WinMain ( ... )

{

if ( ( WinAPPCStartup ( ...) = = FALSE ) {

return FALSE ;

}

uAsyncAPPC = RegisterWindowsMessage ("WinAsyncAPPC") ;

while (GetMessage ( ...)  )  {

...

WinAPPCCleanup ( ... )

}

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:

[MC_]RECEIVE_AND_POST: Description and Syntax

[MC_]RECEIVE_AND_POST: Remarks

[MC_]RECEIVE_AND_WAIT: Description and Syntax

[MC_]RECEIVE_AND_WAIT: Remarks

Management Verbs

Windows APPC supports the following Windows APPC management verbs:

CNOS

Establishes APPC LU 6.2 session limits.

DISPLAY

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


Microsoft Windows Graphical Environment and Windows-Specific Extensions

This API has been designed for all implementations and versions of the Windows environment from and including version 3.0. It thus provides for Windows APPC implementations and Windows APPC applications in both 16-bit and 32-bit operating environments.

Windows APPC makes provisions for multithreaded Windows-based processes. A process contains one or more threads of execution. In the Win16 nonmultithreaded world, 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. In nonmultithreaded environments (such as version 3.0), use of the term thread refers to a Windows process.

The extensions to the Windows environment included in Windows APPC are provided for maximum programming compatibility between Windows version 3.x and Windows NT and optimum application performance in both environments.


Windows APPC Installation Checking

To detect the presence of any Windows APPC implementations on a system, an application that has been linked with the Windows APPC import library can attempt to call the WinAPPCStartup( ) routine. If you want your application to be a little more sophisticated, have it examine the $PATH environment variable to search for instances of Windows APPC API implementations (WINAPPC.DLL). For each instance, it can issue a LoadLibrary( ) call and use the WinAPPCStartup( ) routine to discover implementation specific data.

This version of the Windows APPC API specification does not attempt to address explicitly the issue of multiple library/multiple concurrent Windows APPC implementations. Nothing in the specification should be interpreted as restricting multiple Windows APPC DLLs from being present and from being used concurrently by one or more Windows APPC application.


Windows APPC Programming Considerations

Byte Ordering

The Intel byte ordering is like that of the DEC VAX, and so differs from the Internet and 68000-type processor byte ordering. Take care in your programming to ensure the correct orientation.

Pointers

All pointers used by applications with Windows APPC should be FAR.

Blocking Routines

Although blocking functions are supported with Windows APPC, you should not use them if your application will run in Windows version 3.x. Instead you should use the WinAsyncAPPC( ) function in conjunction with a WinAsyncAPPC Windows message. Applications targeted exclusively for Windows NT and that make use of additional threads to call the blocking routines need not use the asynchronous calls.


Overview of the Windows APPC Verbs

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 Windows 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 Windows 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: Description and Syntax

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 extensions, see 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. 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 Codes" 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 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 documented in "Returns Codes" 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_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 on-demand 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.
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. • 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.
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').
See Also

[MC_]ALLOCATE: Return Codes

[MC_]ALLOCATE: Remarks


[MC_]ALLOCATE: 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

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

AP_BAD_PARTNER_LU_ALIAS

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

See Also

[MC_]ALLOCATE: Description and Syntax

[MC_]ALLOCATE: Remarks


[MC_]ALLOCATE: 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.

See Also

[MC_]ALLOCATE: Description and Syntax

[MC_]ALLOCATE: Return Codes


[MC_]CONFIRM: Description and Syntax

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 extensions, see 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.
See Also

[MC_]CONFIRM: Return Codes

[MC_]CONFIRM: Remarks


[MC_]CONFIRM: 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 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 only), CONFIRM, CONFIRM_SEND, or CONFIRM _DEALLOCATE state. Data sent to the partner TP may have been purged.

See Also

[MC_]CONFIRM: Description and Syntax

[MC_]CONFIRM: Remarks


[MC_]CONFIRM: 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 AP_COMM_SUBSYSTEM_NOT_LOADED	RESET RESET
AP_CONV_FAILURE_RETRY AP_CONV_FAILURE_NO_RETRY	RESET RESET
AP_DEALLOC_ABEND AP_DEALLOC_ABEND_PROG AP_DEALLOC_ABEND_SVC AP_DEALLOC_ABEND_TIMER	RESET RESET RESET RESET
AP_PROG_ERROR_PURGING AP_SVC_ERROR_PURGING	RECEIVE 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

See Also

[MC_]CONFIRM: Description and Syntax

[MC_]CONFIRM: Return Codes


[MC_]CONFIRMED: Description and Syntax

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 extensions, see 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.
See Also

[MC_]CONFIRMED: Return Codes

[MC_]CONFIRMED: Remarks


[MC_]CONFIRMED: 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.

See Also

[MC_]CONFIRMED: Description and Syntax

[MC_]CONFIRMED: Remarks


[MC_]CONFIRMED: 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

[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

See Also

[MC_]CONFIRMED: Description and Syntax

[MC_]CONFIRMED: Return Codes


[MC_]DEALLOCATE: Description and Syntax

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 extensions, see 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. 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. The TP must format the error data as a GDS error log variable. For more information, see your IBM SNA manual(s).
See Also

[MC_]DEALLOCATE: Return Codes

[MC_]DEALLOCATE: Remarks


[MC_]DEALLOCATE: 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 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 only), CONFIRM, CONFIRM_SEND, or CONFIRM _DEALLOCATE state. Data sent to the partner TP may have been purged.

See Also

[MC_]DEALLOCATE: Description and Syntax

[MC_]DEALLOCATE: Remarks


[MC_]DEALLOCATE: 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 AP_ABEND_PROG AP_ABEND_SVC AP_ABEND_TIMER	Any except RESET Any except RESET Any except RESET 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 AP_CONV_FAILURE_NO_RETRY	RESET RESET
AP_DEALLOC_ABEND AP_DEALLOC_ABEND_PROG AP_DEALLOC_ABEND_SVC AP_DEALLOC_ABEND_TIMER	RESET RESET RESET RESET
AP_PROG_ERROR_PURGING AP_SVC_ERROR_PURGING	RECEIVE 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.

See Also

[MC_]DEALLOCATE: Description and Syntax

[MC_]DEALLOCATE: Return Codes


[MC_]FLUSH: Description and Syntax

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 extensions, see 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.
See Also

[MC_]FLUSH: Return Codes

[MC_]FLUSH: Remarks


[MC_]FLUSH: 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.

See Also

[MC_]FLUSH: Description and Syntax

[MC_]FLUSH: Remarks


[MC_]FLUSH: 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.

See Also

[MC_]FLUSH: Description and Syntax

[MC_]FLUSH: Return Codes


[MC_]GET_ATTRIBUTES: Description and Syntax

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

[MC_]GET_ATTRIBUTES: Return Codes and Remarks


[MC_]GET_ATTRIBUTES: Return Codes and Remarks

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.

See Also

[MC_]GET_ATTRIBUTES: Description and Syntax


GET_TP_PROPERTIES: Description and Syntax

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.
	• 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.
See Also

GET_TP_PROPERTIES: Return Codes

GET_TP_PROPERTIES: Remarks


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

See Also

GET_TP_PROPERTIES: Description and Syntax

GET_TP_PROPERTIES: Remarks


GET_TP_PROPERTIES: 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).

See Also

GET_TP_PROPERTIES: Description and Syntax

GET_TP_PROPERTIES: Return Codes


GET_TYPE: Description and Syntax

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

GET_TYPE: Return Codes and Remarks


GET_TYPE: Return Codes and Remarks

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.

See Also

GET_TYPE: Description and Syntax


[MC_]PREPARE_TO_RECEIVE: Description and Syntax

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 extensions, see 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.
	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 [MC_]PREPARE_TO_RECEIVE: Remarks.
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.
See Also

[MC_]PREPARE_TO_RECEIVE: Return Codes

[MC_]PREPARE_TO_RECEIVE: Remarks


[MC_]PREPARE_TO_RECEIVE: 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 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 only), CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE state. Data sent to the partner TP may have been purged.

See Also

[MC_]PREPARE_TO_RECEIVE: Description and Syntax

[MC_]PREPARE_TO_RECEIVE: Remarks


[MC_]PREPARE_TO_RECEIVE: 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 AP_CONV_FAILURE_NO_RETRY	RESET RESET
AP_DEALLOC_ABEND AP_DEALLOC_ABEND_PROG AP_DEALLOC_ABEND_SVC AP_DEALLOC_ABEND_TIMER	RESET RESET RESET RESET
AP_PROG_ERROR_PURGING AP_SVC_ERROR_PURGING	RECEIVE 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 operating system), [MC_]RECEIVE_IMMEDIATE, and [MC_]RECEIVE_AND_WAIT.

See Also

[MC_]PREPARE_TO_RECEIVE: Description and Syntax

[MC_]PREPARE_TO_RECEIVE: Return Codes


RECEIVE_ALLOCATE: Description and Syntax

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 extensions, see 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 an invocable TP name in the SNA Server configuration file. It must also match the tp_name parameter of [MC_]ALLOCATE in the invoking TP. 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.
	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.
See Also

RECEIVE_ALLOCATE: Return Codes

RECEIVE_ALLOCATE: Remarks


RECEIVE_ALLOCATE: 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; in the configuration file for your application, APPC could not find an invokable TP name matching the value of tp_name.

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.

See Also

RECEIVE_ALLOCATE: Description and Syntax

RECEIVE_ALLOCATE: Remarks


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

See Also

RECEIVE_ALLOCATE: Description and Syntax

RECEIVE_ALLOCATE: Return Codes


[MC_]RECEIVE_AND_POST: Description and Syntax

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 operating system. 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 Extensions for the Windows Environment. For information on how a TP receives data and how to use this verb, see [MC_]RECEIVE_AND_POST: Remarks.

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.
	• 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 [MC_]RECEIVE_AND_POST: Remarks.
	• 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.
	• 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: Remarks.
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. 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.
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.
See Also

[MC_]RECEIVE_AND_POST: Return Codes

[MC_]RECEIVE_AND_POST: Remarks


[MC_]RECEIVE_AND_POST: 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; indicates, for Windows NT only, that the address of the RAM semaphore or system semaphore handle was invalid.

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

See Also

[MC_]RECEIVE_AND_POST: Description and Syntax

[MC_]RECEIVE_AND_POST: Remarks


[MC_]RECEIVE_AND_POST: 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, [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 clears 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.
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
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. This is because APPC will not issue the Windows message or clear the semaphore.

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.

See Also

[MC_]RECEIVE_AND_POST: Description and Syntax

[MC_]RECEIVE_AND_POST: Return Codes


[MC_]RECEIVE_AND_WAIT: Description and Syntax

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 extensions, see 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 [MC_]RECEIVE_AND_WAIT: Remarks.
	• 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 [MC_]RECEIVE_AND_WAIT: Return Codes 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: Remarks.
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. This value must not exceed the length of the buffer to contain the received data.
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. 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.
See Also

[MC_]RECEIVE_AND_WAIT: Return Codes

[MC_]RECEIVE_AND_WAIT: Remarks


[MC_]RECEIVE_AND_WAIT: 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 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 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.

See Also

[MC_]RECEIVE_AND_WAIT: Description and Syntax

[MC_]RECEIVE_AND_WAIT: Remarks


[MC_]RECEIVE_AND_WAIT: 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 operating system), [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 AP_DATA_CONFIRM_DEALLOCATE AP_CONFIRM_SEND	CONFIRM_DEALLOCATE CONFIRM_DEALLOCATE CONFIRM_SEND
AP_DATA_COMPLETE_CONFIRM_SEND AP_DATA_CONFIRM_SEND AP_CONFIRM_WHAT_RECEIVED	CONFIRM_SEND CONFIRM_SEND CONFIRM
AP_DATA_COMPLETE_CONFIRM AP_DATA_CONFIRM AP_DATA	CONFIRM CONFIRM RECEIVE
AP_DATA_COMPLETE AP_DATA_INCOMPLETE AP_SEND	RECEIVE RECEIVE 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 AP_CONV_FAILURE_NO_RETRY	RESET RESET
AP_DEALLOC_ABEND AP_DEALLOC_ABEND_PROG AP_DEALLOC_ABEND_SVC AP_DEALLOC_ABEND_TIMER	RESET RESET RESET RESET
AP_DEALLOC_NORMAL	RESET
AP_PROG_ERROR_PURGING AP_PROG_ERROR_NO_TRUNC AP_SVC_ERROR_PURGING AP_SVC_ERROR_NO_TRUNC	RECEIVE RECEIVE RECEIVE 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 AP_DATA_COMPLETE_CONFIRM_DEALL AP_DATA_CONFIRM_DEALLOCATE	CONFIRM_DEALLOCATE CONFIRM_DEALLOCATE CONFIRM_DEALLOCATE
AP_CONFIRM_SEND AP_DATA_COMPLETE_CONFIRM_SEND AP_DATA_CONFIRM_SEND	CONFIRM_SEND CONFIRM_SEND CONFIRM_SEND
AP_CONFIRM_WHAT_RECEIVED AP_DATA_COMPLETE_CONFIRM AP_DATA_CONFIRM	CONFIRM CONFIRM CONFIRM
AP_DATA AP_DATA_COMPLETE AP_DATA_INCOMPLETE	NO CHANGE NO CHANGE 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 AP_DEALLOC_ABEND	RESET RESET
AP_DEALLOC_ABEND_PROG AP_DEALLOC_ABEND_SVC AP_DEALLOC_ABEND_TIMER	RESET RESET RESET
AP_DEALLOC_NORMAL	RESET
AP_PROG_ERROR_PURGING AP_PROG_ERROR_NO_TRUNC AN_SVC_ERROR_PURGING AN_SVC_ERROR_NO_TRUNC	NO CHANGE NO CHANGE NO CHANGE NO CHANGE
AP_PROG_ERROR_TRUNC AP_SVC_ERROR_TRUNC	NO CHANGE 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.

See Also

[MC_]RECEIVE_AND_WAIT: Description and Syntax

[MC_]RECEIVE_AND_WAIT: Return Codes


[MC_]RECEIVE_IMMEDIATE: Description and Syntax

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.

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 [MC_]RECEIVE_IMMEDIATE: Remarks.
	• 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 [MC_]RECEIVE_IMMEDIATE: Return Codes 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: Remarks.
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. This value must not exceed the length of the buffer to contain the received data.
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. 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.
See Also

[MC_]RECEIVE_IMMEDIATE: Return Codes

[MC_]RECEIVE_IMMEDIATE: Remarks


[MC_]RECEIVE_IMMEDIATE: 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 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 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.

See Also

[MC_]RECEIVE_IMMEDIATE: Description and Syntax

[MC_]RECEIVE_IMMEDIATE: Remarks


[MC_]RECEIVE_IMMEDIATE: 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 operating system), [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 AP_DATA_COMPLETE_CONFIRM_DEALL AP_DATA_CONFIRM_DEALLOCATE	CONFIRM_DEALLOCATE CONFIRM_DEALLOCATE CONFIRM_DEALLOCATE
AP_CONFIRM_SEND AP_DATA_COMPLETE_CONFIRM_SEND AP_DATA_CONFIRM_SEND	CONFIRM_SEND CONFIRM_SEND CONFIRM_SEND
AP_CONFIRM_WHAT_RECEIVED AP_DATA_COMPLETE_CONFIRM AP_DATA_CONFIRM	CONFIRM CONFIRM CONFIRM
AP_DATA AP_DATA_COMPLETE AP_DATA_INCOMPLETE	NO CHANGE NO CHANGE 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 AP_CONV_FAILURE_NO_RETRY	RESET RESET
AP_DEALLOC_ABEND AP_DEALLOC_ABEND_PROG AP_DEALLOC_ABEND_SVC AP_DEALLOC_ABEND_TIMER	RESET RESET RESET RESET
AP_DEALLOC_NORMAL	RESET
AP_PROG_ERROR_PURGING AP_PROG_ERROR_NO_TRUNC AN_SVC_ERROR_PURGING AN_SVC_ERROR_NO_TRUNC	NO CHANGE NO CHANGE NO CHANGE NO CHANGE
AP_PROG_ERROR_TRUNC AP_SVC_ERROR_TRUNC	NO CHANGE 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.

See Also

[MC_]RECEIVE_IMMEDIATE: Description and Syntax

[MC_]RECEIVE_IMMEDIATE: Return Codes


[MC_]REQUEST_TO_SEND: Description and Syntax

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 extensions, see 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.
See Also

[MC_]REQUEST_TO_SEND: Return Codes

[MC_]REQUEST_TO_SEND: Remarks


[MC_]REQUEST_TO_SEND: 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.

See Also

[MC_]REQUEST_TO_SEND: Description and Syntax

[MC_]REQUEST_TO_SEND: Remarks


[MC_]REQUEST_TO_SEND: Remarks

The conversation can be in any of the following states when the TP issues this verb:

•	CONFIRM

•	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 operating system)

•	[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 operating system), [MC_]RECEIVE_IMMEDIATE, and [MC_]RECEIVE_AND_WAIT.

See Also

[MC_]REQUEST_TO_SEND: Description and Syntax

[MC_]REQUEST_TO_SEND: Return Codes


[MC_]SEND_CONVERSATION: Description and Syntax

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 extensions, see 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. If you want to use the fqplu_name parameter, instead of plu_alias, to specify the partner LU alias, fill plu_alias with binary zeroes. 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). The data buffer can reside in a static data area or in a globally allocated area.
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. 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.
See Also

[MC_]SEND_CONVERSATION: Return Codes

[MC_]SEND_CONVERSATION: Remarks


[MC_]SEND_CONVERSATION: 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

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

AP_BAD_PARTNER_LU_ALIAS

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

See Also

[MC_]SEND_CONVERSATION: Description and Syntax

[MC_]SEND_CONVERSATION: Remarks


[MC_]SEND_CONVERSATION: 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 on CSVs, see the Windows CSV Specification.

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.

See Also

[MC_]SEND_CONVERSATION: Description and Syntax

[MC_]SEND_CONVERSATION: Return Codes


[MC_]SEND_DATA: Description and Syntax

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 extensions, see 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 operating system). • 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. 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.
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.
See Also

[MC_]SEND_DATA: Return Codes

[MC_]SEND_DATA: Remarks


[MC_]SEND_DATA: 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'.

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 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 only), CONFIRM, CONFIRM_SEND, or CONFIRM _DEALLOCATE state. Data sent to the partner TP may have been purged.

See Also

[MC_]SEND_DATA: Description and Syntax

[MC_]SEND_DATA: Remarks


[MC_]SEND_DATA: 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 AP_CONV_FAILURE_NO_RETRY AP_DEALLOC_ABEND	RESET RESET RESET
AP_DEALLOC_ABEND_PROG AP_DEALLOC_ABEND_SVC AP_DEALLOC_ABEND_TIMER AP_PROG_ERROR_PURGING AP_SVC_ERROR_PURGING	RESET RESET RESET RECEIVE 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).

See Also

[MC_]SEND_DATA: Description and Syntax

[MC_]SEND_DATA: Return Codes


[MC_]SEND_ERROR: Description and Syntax

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 extensions, see 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. The TP must format the error data as a GDS error log variable. For more information, see your IBM SNA manual(s).
See Also

[MC_]SEND_ERROR: Return Codes

[MC_]SEND_ERROR: Remarks


[MC_]SEND_ERROR: 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 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 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

See Also

[MC_]SEND_ERROR: Description and Syntax

[MC_]SEND_ERROR: Remarks


[MC_]SEND_ERROR: 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 AP_DEALLOC_ABEND	RESET RESET
AP_DEALLOC_ABEND_PROG AP_DEALLOC_ABEND_SVC AP_DEALLOC_ABEND_TIMER AP_DEALLOC_NORMAL	RESET RESET RESET 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.

See Also

[MC_]SEND_ERROR: Description and Syntax

[MC_]SEND_ERROR: Return Codes


[MC_]TEST_RTS: Description and Syntax

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

[MC_]TEST_RTS: Return Codes and Remarks


[MC_]TEST_RTS: Return Codes and Remarks

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.

See Also

[MC_]TEST_RTS: Description and Syntax


TP_ENDED: Description and Syntax

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 extensions, see 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.
See Also

TP_ENDED: Return Codes

TP_ENDED: Remarks


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

See Also

TP_ENDED: Description and Syntax

TP_ENDED: Remarks


TP_ENDED: 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 performs 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.

See Also

TP_ENDED: Description and Syntax

TP_ENDED: Return Codes


TP_STARTED: Description and Syntax

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 extensions, see 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: Description and Syntax  and [MC_]ALLOCATE: Return Codes 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.
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.
	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'.
See Also

TP_STARTED: Return Codes

TP_STARTED: Remarks


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

See Also

TP_STARTED: Description and Syntax

TP_STARTED: Remarks


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

See Also

TP_STARTED: Description and Syntax

TP_STARTED: Return Codes


Default LUs

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

If an 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 an 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, both a default local APPC LU and a default remote APPC LU should be assigned. 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.


Extensions for the Windows Environment: Overview

The API extensions described in this Help allow asynchronous communication with the Windows APPC. Asynchronous communication occurs when a function returns before the request completes. The application is notified when the request completes.

These API extensions 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 16-bit and 32-bit operating environments.

Windows APPC allows multithreaded Windows-based processes. A process contains one or more threads of execution. The 16-bit 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 help provides, for each extension, a definition of the function, syntax, returns, and remarks for using the extension. Corresponding prototypes for each extension are located in the WINAPPC.H header file.


GetAppcConfig( ): Description and Syntax

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.


GetAppcConfig( ): Return Codes

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.


GetAppcConfig( ): 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( )

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

This function either returns the length of the returned string (not including terminating zero) or, for failure, returns 0. In the Windows NT (Win32) environment, when 0 is returned, the Win32 function GetLastError can be called, to obtain one of the following secondary return codes:

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; the buffer contains a truncated version of the error string.

0x20000003

The APPC string library APPCST32.DLL 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.


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.

The Windows APPC supplier must ensure that messages are successfully posted to the application. If a PostMessage( ) operation fails, the Windows APPC implementation must repost the message.

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( )

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);

Return Codes

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( )

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( )

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.

See Also

WinAPPCCancelAsyncRequest( )


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( )

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( )

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. For this release of Windows APPC, 1.0 is the correct 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

For this release of Windows APPC, 1.0 is the correct version number.

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 WinAPPC- Startup( )	From WinAPPC- Startup( )	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( )

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 WinAPPCUnhookBlockingHook 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( )

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( )


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

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

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

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.


Microsoft Support Services Contents
Microsoft Support Services

  When You Have a Question

  Product Support Within the United States and Canada


When You Have a Question

If you have a question about SNA Server, first look in the product documentation or consult online Help. You can also find late-breaking updates and technical information in the README file that came with your SNA Server disks. If you cannot find the answer, contact the Microsoft Support Network.

Outside the United States, contact Microsoft Product Support Services at the Microsoft subsidiary office that serves your area.

The Microsoft Support Network

The Microsoft Support Network offers you a wide range of choices and access to high-quality, responsive technical support. Microsoft recognizes that support needs vary from user to user; the Microsoft Support Network allows you to choose the type of support that best meets your needs, with options ranging from electronic bulletin boards to annual support programs. For information about support services in the United States and Canada, see Product Support Within the United States and Canada.

Services vary outside the United States and Canada. In other locations, contact a local Microsoft subsidiary for information. The Microsoft Support Network is subject to Microsoft's then-current prices, terms, and conditions, and is subject to change without notice.


Product Support Within the United States and Canada

In the United States and Canada, the following support services are available through the Microsoft Support Network:

Electronic Services

Priority Support

Text Telephone

Other Support Options

Other Microsoft Services


Electronic Services

These services are available 24 hours a day, 7 days a week, including holidays.

Microsoft FastTips

(800) 936-4400 on a touch-tone telephone. Receive automated answers to common questions, and access a library of technical notes, all delivered by recording or fax. You can use the following keys on your touch-tone telephone after you reach FastTips:

To	Press
Advance to the next message	*
Repeat the current message	7
Return to the beginning of FastTips	#
CompuServe

Interact with other users and Microsoft support engineers, or access the Microsoft Knowledge Base to get product information. At any ! prompt, type go microsoft to access Microsoft forums, type go mskb to access the Microsoft Knowledge Base, or type go mssna to access the Microsoft SNA forum. For an introductory CompuServe membership kit, call (800) 848-8199, operator 524.

Microsoft Download Service

Access, via modem, the Driver Library and the most current technical notes (1200, 2400, or 9600 baud; no parity; 8 data bits; 1 stop bit). In the United States, call (206) 936-6735. In Canada, call (905) 507-3022.

Internet

Access the Driver Library and the Microsoft Knowledge Base. The Microsoft Internet FTP archive host, ftp.microsoft.com, supports anonymous login. When logging in as anonymous, you should type your complete electronic mail name as your password.

See also

Priority Support

Text Telephone

Other Support Options

Other Microsoft Services


Priority Support

The Microsoft Support Network offers priority telephone access to Microsoft support engineers 24 hours a day, 7 days a week, except holidays.

In the United States, call (900) 555-2100; $150 (U.S.) per incident. Charges appear on your telephone bill.

In the United States, call (800) 936-5900; $150 (U.S.) per incident, billed to your VISA card, MasterCard, or American Express card.

In Canada, call (800) 668-7975 for more information.

See also

Electronic Services

Text Telephone

Other Support Options

Other Microsoft Services


Text Telephone

Microsoft text telephone (TT/TDD) services are available for the deaf or hard-of-hearing. In the United States, using a TT/TDD modem, dial (206) 635-4948 between 6:00 A.M. and 6:00 P.M. Pacific time, Monday through Friday, excluding holidays. In Canada, using a TT/TDD modem, dial (905) 568-9641 between 8:00 A.M. and 8:00 P.M. Eastern time, Monday through Friday, excluding holidays.

See also

Electronic Services

Priority Support

Other Support Options

Other Microsoft Services


Other Support Options

The Microsoft Support Network offers annual and multiple incident support plans. For information, in the United States, contact the Microsoft Support Network Sales and Information group at (800) 936-3500 between 6:00 A.M. and 6:00 P.M. Pacific time, Monday through Friday, excluding holidays. In Canada, call (800) 668-7975 between 8:00 A.M. and 8:00 P.M. Eastern time, Monday through Friday, excluding holidays.

Electronic Services

Priority Support

Text Telephone

Other Microsoft Services


Other Microsoft Services

Microsoft Solution Providers Program

Microsoft Solution Providers are independent organizations that provide consulting, integration, customization, development, technical support and training, and other services for Microsoft products. These companies are called Solution Providers because they apply technology and provide services to help solve real-world problems.

In the United States, for more information about the Microsoft Solution Providers program or the Microsoft Solution Provider nearest to you, please call (800) 426-9400 between 6:30 A.M. and 5:30 P.M. Pacific time, Monday through Friday, excluding holidays. In Canada, call (800) 563-9048 between 8:00 A.M. and 8:00 P.M. Eastern time, Monday through Friday, excluding holidays.

Microsoft TechNet

Microsoft TechNet is an annual information service created for those who support or educate end users, administer networks or databases, create automated solutions and recommend or evaluate information technology solutions.  Microsoft TechNet gives you the answers you need, when you need them by providing timely, comprehensive and in-depth information on Microsoft products and on supporting and administering Microsoft-based solutions via the monthly Microsoft TechNet CD and monthly TechNet Supplemental (Drivers & Patches) CD.

For more information about Microsoft TechNet, in the United States and Canada, call (800) 344-2121, dept. 3013, between 7:00 A.M. and 7:00 P.M. Central time, Monday through Friday.

See also

Electronic Services

Priority Support

Text Telephone

Other Support Options