HP-UX SNAplus2 R7 APPC Programmer’s Guide HP-UX 11i v1, 11i v2 and 11i v3 Edition: 4 Manufacturing Part Number: 5991–2744 April 2007 © 2007 Hewlett-Packard Development Company, L.P. All rights reserved.
Contents Legal Notices.............................................................................................................................................13 Warranty............................................................................................................................................13 U.S. Government License.. .............................................................................................................. 13 Copyright Notices.. ...................................
1.3 Confirmation Processing (half-duplex)....................................................................................25 1.3.1 Establishing the Synchronization Level.......................................................................26 1.3.2 Sending a Confirmation Request ...............................................................................26 1.3.3 Receiving Data and a Confirmation Request.. ........................................................... 27 1.3.
iv 2.2.5 2.2.6 2.2.7 Getting Information .....................................................................................................47 Ending a Conversation................................................................................................48 Starting a Transaction Program (TP).. ........................................................................ 48 2.3 APPC 2.3.1 2.3.2 2.3.3 Entry Points: HP-UX Systems..........................................................................
2.11.3 2.11.4 Error Log....................................................................................................................74 Timeouts Versus Critical Errors.................................................................................75 2.12 Writing TP Servers................................................................................................................75 2.12.1 TP Server Responsibilities.................................................................................
3.6 SET_TP_PROPERTIES..........................................................................................................97 3.6.1 VCB Structure: SET_TP_PROPERTIES.. .................................................................. 98 3.6.2 Supplied Parameters.. .................................................................................................98 3.6.3 Returned Parameters.. .............................................................................................. 100 3.6.
4.4.7 Supplied Parameters.. ...............................................................................................127 4.4.8 Returned Parameters.. .............................................................................................. 127 4.4.9 State When Issued....................................................................................................129 4.4.10 State Change...........................................................................................................
4.9.1 4.9.2 4.9.3 4.9.4 viii How a TP Receives Data..........................................................................................158 The what_rcvd Parameter......................................................................................... 158 End of Data.. ............................................................................................................. 159 Testing the what_rcvd Parameter..............................................................................160 4.
4.14.3 4.14.4 4.14.5 4.14.6 4.14.7 4.14.8 4.14.9 4.14.10 4.14.11 VCB Structure: MC_REQUEST_TO_SEND.. ......................................................... 201 VCB Structure: REQUEST_TO_SEND...................................................................202 VCB Structure: MC_REQUEST_TO_SEND (Windows).........................................202 VCB Structure: REQUEST_TO_SEND (Windows).................................................202 Supplied Parameters...............................................
4.18.5 4.18.6 4.18.7 State When Issued..................................................................................................237 State Change...........................................................................................................237 Waiting for Partner TP.. ........................................................................................... 238 4.19 MC_TEST_RTS and TEST_RTS........................................................................................238 4.
5.5.3 Returned Parameters.. .............................................................................................. 259 5.6 ACCEPT_ATTACH.. .............................................................................................................. 260 5.6.1 VCB Structure: ACCEPT_ATTACH...........................................................................260 5.6.2 Supplied Parameters.. ...............................................................................................260 5.6.
B.15 AP_INVALID_VERB............................................................................................................285 B.16 AP_INVALID_VERB_SEGMENT.. ...................................................................................... 285 B.17 AP_PROG_ERROR_NO_TRUNC......................................................................................285 B.18 AP_PROG_ERROR_PURGING.........................................................................................286 B.
Legal Notices Trademark Notices Legal Notices The information in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this manual, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Hewlett-Packard shall not be held liable for errors contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance, or use of this material.
Publishing History New and Changed Information in This Edition Publishing History The manual publishing date and part number indicate its current edition. The publishing date will change when a new edition is printed. Minor changes may be made without changing the publishing date. The manual part number will change when extensive changes are made. Manual updates may be issued between editions to correct errors or document product changes.
Before You Begin About This Book Before You Begin This book is a guide for developing C programming language application programs that use Advanced Program-toProgram Communications (APPC) to exchange data in a Systems Network Architecture (SNA) environment. The SNAplus2 implementation of APPC is based on IBM’s implementation of APPC in its OS/2 products (such as Communications Server for OS/2), with modifications for the HP-UX environment.
Before You Begin About This Book Organization of This Book This book is organized as follows: • Chapter 1, Concepts, introduces the fundamental concepts of APPC. It is intended for programmers who are not familiar with APPC. • Chapter 2, Writing Transaction Programs, contains general information an APPC programmer needs when writing transaction programs (TPs). • Chapter 3, APPC Control Verbs, describes each APPC control verb in detail.
Before You Begin SNAplus2 Publications Special Element Sample of Typography Option or flag -I Parameter or Motif field primary_rc; what_rcvd Literal value or selection that the user can enter (including default values) 0; 32,767 Constant or signal AP_DATA_COMPLETE_CONFIRM Return value AP_OK; AP_SYNC_LEVEL_NOT_SUPPORTED; TRUE Variable representing a supplied value lParam; ReturnedHandle Environment variable LD_RUN_PATH Programming verb RECEIVE_ALLOCATE User input cc -I Function, call, or
Before You Begin SNAplus2 Publications Publications for Users SNAplus2 provides the following user guides: HP-UX SNAplus2 General Information Provides a general overview of the SNAplus2 product.
Before You Begin Related Publications Publications for Programmers SNAplus2 provides the following programmer guides. Each guide includes conceptual and detailed reference information. HP-UX SNAplus2 APPC Programmer’s Guide Contains the information you need to write application programs using Advanced Program-to-Program Communication (APPC). HP-UX SNAplus2 CPI-C Programmer’s Guide Contains the information you need to write application programs using Common Programming Interface for Communications (CPI-C).
Concepts What Is APPC? 1 Concepts This chapter introduces the fundamental concepts of advanced program-to-program communication (APPC) in a distributed processing environment: • What is APPC? • A simple mapped conversation • Confirmation processing • Sending and receiving status with data • Conversation states • Changing conversation states • Synchronous and asynchronous APPC calls • Receiving data asynchronously UNIX • Syncpoint support • APPC and CPI-C (Common Programming Interface for
Concepts What Is APPC? 1.1.2 Communication between TPs Many hardware and software elements in the SNA environment are required for two TPs to communicate with each other. Figure 1–1, Elements for Writing TPs illustrates the elements that pertain directly to programmers writing TPs. Figure 1–1 Elements for Writing TPs TP A TP B LU 1 LU 2 Conversation Session 1.1.3 Logical Unit 6.
Concepts What Is APPC? 1.1.7 The Conversation Process A conversation begins when both of the following happen: 1. One TP (the invoking TP) instructs APPC to start another TP (the invoked TP) and allocate a conversation between the two TPs. 2. The invoked TP notifies APPC that it is ready to communicate with the invoking TP. During the conversation, the two TPs exchange status information and application data. A conversation ends when a TP instructs APPC to deallocate the conversation. 1.1.
Concepts A Simple Mapped Conversation (half-duplex) TP can receive data but cannot send it; however, it can send an error indication to the controlling TP, or can request control of the conversation.
Concepts A Simple Mapped Conversation (half-duplex) Invoking TP Flow Invoked TP MC_RECEIVE_AND_WAIT (what_rcvd = AP_DATA_COMPLETE) MC_RECEIVE_AND_WAIT (primary_rc = AP_DEALLOC_NORMAL) TP_ENDED The characters MC_ at the beginning of many of the verbs stand for mapped conversation. Parameters and results of APPC verbs are in parentheses. 1.2.
Concepts Confirmation Processing (half-duplex) 1.2.4 Ending a Conversation To end a conversation, one of the TPs issues the MC_DEALLOCATE verb, which causes APPC to deallocate the conversation between the two TPs. After this conversation is deallocated, each TP either issues another [MC_]ALLOCATE or RECEIVE_ALLOCATE verb to start another conversation (with this or another partner TP), or issues the TP_ENDED verb. A TP can participate in multiple conversations simultaneously.
Concepts Confirmation Processing (half-duplex) Invoking TP Flow Invoked TP MC_RECEIVE_AND_WAIT (primary_rc= AP_OK) (what_rcvd = AP_SEND) MC_SEND_DATA MC_CONFIRM —> MC_RECEIVE_AND_WAIT (primary_rc= AP_OK) (what_rcvd = AP_DATA_COMPLETE) MC_RECEIVE_AND_WAIT (primary_rc= (what_rcvd = AP_CONFIRM) AP_OK) MC_CONFIRMED <— MC_DEALLOCATE (dealloc_type = AP_SYNC_LEVEL) —> MC_RECEIVE_AND_WAIT (primary_rc = AP_OK) (what_rcvd = AP_CONFIRM_DEALLOCATE) MC_CONFIRMED <— TP_ENDED TP_ENDED 1.3.
Concepts Sending and Receiving Status with Data (half-duplex) 1.3.
Concepts Sending and Receiving Status with Data (half-duplex) Table 1–3 Receiving Status Information with Data Invoking TP Flow Invoked TP TP_STARTED MC_ALLOCATE MC_SEND_DATA (type = AP_SEND_DATA_CONFIRM) —> RECEIVE_ALLOCATE MC_RECEIVE_AND_WAIT (rtn_status = NO) (what_rcvd= AP_DATA_COMPLETE) MC_RECEIVE_AND_WAIT (rtn_status = NO) (what_rcvd = AP_CONFIRM_WHAT_RECEIVED) MC_CONFIRMED <— MC_SEND_DATA (type = AP_NONE) MC_CONFIRM —> MC_RECEIVE_AND_WAIT (rtn_status = YES) (what_rcvd = AP_DATA_COMPLETE_CONFIRM
Concepts Conversation States (half-duplex) available, APPC can return the status information about this verb in addition to the data. The verb returns with a what_rcvd parameter of AP_DATA_COMPLETE_CONFIRM, which indicates that the invoking TP sent data and then requested confirmation. The first two MC_RECEIVE_AND_WAIT verbs have the rtn_status parameter set to AP_NO, so APPC does not return status information with the data; the first verb receives the data, and the second receives the status information.
Concepts Changing Conversation States (half-duplex) 1.5.1 The TP’s View of the Conversation It is the conversation rather than the TP that is in a particular state. A TP may be conducting several conversations, each of which is in a different state. If a conversation is said to be in Send state, this always means that from the viewpoint of the local TP, the conversation is in Send state. To the partner TP, the conversation is in another state (such as Receive). 1.5.
Concepts Changing Conversation States (half-duplex) State Invoking TP Flow Invoked TP State —> Reset RECEIVE_ALLOCATE Receive MC_RECEIVE_AND_WAIT (primary_rc = AP_OK) (what_rcvd = AP_DATA_COMPLETE) MC_RECEIVE_AND_WAIT (primary_rc = AP_OK) (what_rcvd= AP_CONFIRM_SEND) ConfirmSend MC_CONFIRMED Send <— (MC_PREPARE_TO_RECEIVE returns, primary_rc = AP_OK) Receive MC_SEND_DATA MC_CONFIRM <— MC_RECEIVE_AND_WAIT (primary_rc = AP_OK) (what_rcvd= AP_DATA_COMPLETE) MC_RECEIVE_AND_WAIT (primary_rc = AP_OK) (what_
Concepts Changing Conversation States (half-duplex) State Invoking TP Flow Invoked TP State MC_PREPARE_TO_RECEIVE (ptr_type = AP_SYNC_LEVEL) <— MC_RECEIVE_AND_WAIT (primary_rc= AP_OK) (what_rcvd = AP_CONFIRM_SEND) ConfirmSend MC_CONFIRMED —> (MC_PREPARE_TO_RECEIVE returns, primary_rc = AP_OK) Receive Send MC_SEND_DATA MC_DEALLOCATE (dealloc_type = AP_SYNC_LEVEL) —> MC_RECEIVE_AND_WAIT (primary_rc = AP_OK) (what_rcvd= AP_DATA_COMPLETE) MC_RECEIVE_AND_WAIT (primary_rc= AP_OK) (what_rcvd =AP_CONFIRM_DEAL
Concepts Full-Duplex Conversations 1.6.2 Changing to Receive State The MC_PREPARE_TO_RECEIVE verb enables a TP to change the conversation from Send to Receive state. This verb does the following: • Flushes the local LU’s send buffer. • Sends the AP_CONFIRM_SEND indicator to the partner TP through the what_rcvd parameter of a receive verb. This indicator tells the partner TP that an MC_CONFIRMED response is expected before the partner TP can begin to send data.
Concepts Full-Duplex Conversations Invoking TP Flow Invoked TP MC_RECEIVE_AND_WAIT (what_rcvd = AP_DATA_COMPLETE) MC_RECEIVE_AND_WAIT (primary_rc = AP_DEALLOC_NORMAL) <— MC_SEND_DATA MC_DEALLOCATE TP_ENDED MC_RECEIVE_AND_WAIT (what_rcvd = AP_DATA_COMPLETE) MC_RECEIVE_AND_WAIT (what_rcvd = AP_DEALLOC_NORMAL) TP_ENDED The characters MC_ at the beginning of many of the verbs stand for mapped conversation. Parameters and results of APPC verbs are in parentheses. 1.7.
Concepts Full-Duplex Conversations 1.7.3 Receiving Data The MC_RECEIVE_AND_WAIT verb receives data from the partner TP. If no data is currently available, the local TP waits for it to arrive. As well as receiving data, the verb may receive a status indicator from the partner TP (such as an indication that the conversation is ending). For more information about how the TP handles these indicators, see Section 1.7.4, Ending a Conversation.
Concepts Synchronous and Asynchronous APPC Calls Reset The conversation has not started or has been terminated. 1.7.6 Half-Duplex Verbs Not Permitted in Full-Duplex Conversations The following verbs apply only in half-duplex conversations, and are not required in full-duplex conversations. Any of these verbs issued in a full-duplex conversation will receive an error return code.
Concepts Receiving Data Asynchronously • Synchronous entry point, APPC. If the application uses this entry point, SNAplus2 does not return control to the application until verb processing has finished. • Asynchronous entry point, WinAsyncAPPC. If the application uses this entry point, SNAplus2 returns control to the application immediately. When verb processing has finished, SNAplus2 indicates this by posting a message to the application’s window procedure. • Asynchronous entry point, WinAsyncAPPCEx.
Concepts Receiving Data Asynchronously • [MC_]DEALLOCATE with a deallocate type of AP_ABEND, AP_ABEND_PROG, AP_ABEND_SVC, or AP_ABEND_TIMER • [MC_]GET_ATTRIBUTES • [MC_]RECEIVE_EXPEDITED_DATA • [MC_]REQUEST_TO_SEND • [MC_]SEND_ERROR • [MC_]SEND_EXPEDITED_DATA • [MC_]TEST_RTS • TP_ENDED If the application issues [MC_]RECEIVE_AND_WAIT (or any other APPC verb) using the asynchronous entry point, it must not issue any other APPC verbs on this conversation until the callback routine has been cal
Concepts Non-Blocking Operation State Invoking TP Flow Invoked TP State MC_RECEIVE_AND_POST returns primary_rc=AP_OK, what_rcvd=AP_DATA_COMPLETE Receive (TP checks that the callback routine has been called.) MC_RECEIVE_AND_WAIT (primary_rc=AP_DEALLOC_NORMAL) Reset TP_ENDED In Table 1–6, Receiving Data Asynchronously, the invoked TP follows these steps to receive data asynchronously: 1. Issues the MC_RECEIVE_AND_POST verb.
Concepts Non-Blocking Operation a multi-threaded TP that issues APPC verbs from more than one thread. To issue a verb in non-blocking mode, the TP sets an option in the opext parameter of the verb, as described in Chapter 4, APPC Conversation Verbs. For each TP and conversation, APPC provides a number of queues on which verbs can be held while waiting to be processed. Each queue handles a different subset of the valid APPC verbs, so that each verb is associated with a different queue.
Concepts Syncpoint Support • [MC_]RECEIVE_IMMEDIATE Send-Expedited queue For each active conversation (either full-duplex or half-duplex), there is a single queue that handles the following verbs: • [MC_]REQUEST_TO_SEND (half-duplex conversations only) • [MC_]SEND_EXPEDITED_DATA Receive-Expedited queue For each active conversation (either full-duplex or half-duplex), there is a single queue that handles the following verbs: • [MC_]RECEIVE_EXPEDITED_DATA The following conversation verbs are not asso
Concepts TP Server API 1.13 APPC and CPI-C The Common Programming Interface for Communications (CPI-C) application programming interface, another SNAplus2 API, provides many of the functions of APPC but with a different style of interface. Where an APPC application sets parameters in a verb control block and then calls a single entry point to APPC with the address of the block, a CPI-C program calls a different entry point for each verb and passes the required information as parameters on the call.
Writing Transaction Programs Categories of APPC Verbs 2 Writing Transaction Programs This chapter contains information about the following topics and will help you write transaction programs (TPs): • Categories of APPC verbs • APPC verb summary • APPC entry points UNIX • HP-UX system considerations WINDOWS • Windows system considerations • Configuration information • Conversation security • Starting TPs • LU-to-LU sessions • Basic conversations UNIX • Writing TP servers • Writing por
Writing Transaction Programs Categories of APPC Verbs • SET_TP_PROPERTIES • GET_LU_STATUS 2.1.2 Conversation Verbs Conversation verbs enable TPs to allocate a conversation, send and receive data, change conversation states, and deallocate a conversation.
Writing Transaction Programs APPC Verb Summary 2.1.3 TP Server Verbs UNIX TP server verbs allow applications to start TPs in response to requests from SNAplus2: REGISTER_TP_SERVER UNREGISTER_TP_SERVER REGISTER_TP UNREGISTER_TP QUERY_ATTACH ACCEPT_ATTACH REJECT_ATTACH ABORT_ATTACH Note TP server verbs, as described in Chapter 5, TP Server Verbs, must be issued using the asynchronous entry point APPC_Async, and not the synchronous entry point APPC. 2.
Writing Transaction Programs APPC Verb Summary The ALLOCATE verb can establish either a basic or mapped conversation. The MC_ALLOCATE verb can start only a mapped conversation. Either verb can start either a full-duplex or a half-duplex conversation. Once the conversation is allocated, APPC returns a conversation identifier (conv_id) through this verb. MC_SEND_CONVERSATION or SEND_CONVERSATION This verb is issued by the invoking TP.
Writing Transaction Programs APPC Verb Summary 2.2.3 Receiving Data The following verbs enable a TP to receive data from its partner TP: MC_RECEIVE_AND_WAIT or RECEIVE_AND_WAIT Issuing this verb while the conversation is in Receive state causes the local TP to receive any data that is currently available from the partner TP. If no data is available, the local TP waits for data to arrive.
Writing Transaction Programs APPC Verb Summary was last issued. This enables the TP to check whether it has lost connectivity to its partner TP (in which case it may need to resynchronize). GET_TP_PROPERTIES This verb is used by a TP to obtain information about the attributes of the local TP and of the Logical Unit of Work (a transaction between APPC TPs to accomplish a particular task) in which the TP is participating.
Writing Transaction Programs APPC Entry Points: HP-UX Systems REJECT_ATTACH This verb is used to notify SNAplus2 that the application does not intend to start the TP that corresponds to this Attach. ABORT_ATTACH This verb is used to end the processing of the Attach by this TP server after the Attach has been accepted using an ACCEPT_ATTACH verb because the TP server or TP has encountered an error during further processing.
Writing Transaction Programs APPC Entry Points: HP-UX Systems 2.3.1 APPC Entry Point An application uses APPC to issue an APPC verb synchronously. SNAplus2 does not return control to the application until verb processing has finished. Function Call void APPC ( void * vcb ); For compatibility with earlier APPC implementations, SNAplus2 also provides the entry points APPC_C and APPC_P, which can be used in the same way as APPC.
Writing Transaction Programs APPC Entry Points: HP-UX Systems AP_CORR ); corr typedef void (*AP_CALLBACK) ( void * unsigned char AP_UINT32 AP_CORR corr ); typedef union ap_corr vcb, tp_id[8], conv_id, { void * AP_UINT32 AP_INT32 } AP_CORR; corr_p; corr_l; corr_i; Parameter types such as AP_UINT32, used in these entry points and in the APPC VCBs, are defined in the common header file /usr/include/sna/values_c.h, which is included by the APPC header file /usr/include/ sna/appc_c.h.
Writing Transaction Programs APPC Entry Points: HP-UX Systems Returned Values The asynchronous entry point returns one of the following values: AP_COMPLETED The verb has already completed. The application can examine the parameters in the VCB to determine whether the verb completed successfully. SNAplus2 does not call the supplied callback routine for this verb. AP_IN_PROGRESS The verb has not yet completed.
Writing Transaction Programs APPC Entry Points: Windows Systems Supplied Parameters SNAplus2 calls the callback routine with the following parameters: vcb Pointer to the VCB supplied by the application. The VCB now includes the returned parameters set by SNAplus2. tp_id The 8-byte TP identifier of the TP in which the verb was issued. conv_id The conversation identifier of the conversation in which the verb was issued. corr The correlator value supplied by the application.
Writing Transaction Programs APPC Entry Points: Windows Systems Cancels an outstanding asynchronous verb (one issued using the WinAsyncAPPC entry point). Depending on which verb is outstanding, this may also end the conversation or the TP or deactivate the session being used by a conversation. WinAPPCCleanup Unregisters the application when it has finished using APPC. APPC Issues an APPC verb.
Writing Transaction Programs APPC Entry Points: Windows Systems When the application has finished issuing APPC verbs, it must call WinAPPCCleanup before terminating. After calling WinAPPCCleanup, the application must not attempt to issue any more APPC verbs (unless it first calls WinAPPCStartup to reinitialize). The following sections describe these Windows entry points. 2.4.
Writing Transaction Programs APPC Entry Points: Windows Systems If the return value from WinAPPCStartup is 0 (zero), the WAPPCDATA structure contains information about the support provided by the Windows APPC software. If the return value is nonzero, the contents of this structure are undefined and the application should not check them. The parameters in this structure are as follows: wVersion The Windows APPC version number that the software supports, in the same format as the wVersionRequired parameter.
Writing Transaction Programs APPC Entry Points: Windows Systems Note The APPC VCBs contain many parameters marked as “reserved”; some of these are used internally by the SNAplus2 software, and others are not used in this version but may be used in future versions. Your application must not attempt to access any of these reserved parameters; instead, it must set the entire contents of the VCB to zero to ensure that all of these parameters are zero, before it sets other parameters that are used by the verb.
Writing Transaction Programs APPC Entry Points: Windows Systems long vcbptr ); Supplied Parameters The supplied parameters are: eventhandle An event handle that APPC will signal to indicate asynchronous verb completion. vcbptr A pointer to the VCB structure for the verb. This parameter is defined as a long integer, and so needs to be cast from a pointer to a long integer.
Writing Transaction Programs APPC Entry Points: Windows Systems Supplied Parameters The supplied parameter is: Handle The handle that was returned on the original WinAsyncAPPC call for the verb. Returned Values The return value from the function is one of the following: 0 (zero) The outstanding verb was canceled successfully. WAPPCINVALID The supplied parameter did not match the handle of any outstanding APPC verb. WAPPCALREADY The APPC verb identified by the supplied handle has already completed.
Writing Transaction Programs APPC Entry Points: Windows Systems Although a verb issued to the APPC entry point appears to suspend the application until verb processing is completed, the APPC library has to yield control of the system while waiting for SNAplus2 to complete the processing, in order to allow other processes to run. To do this, the application uses a blocking function, which is called repeatedly while the library is waiting; the function enables Windows messages to be sent to other processes.
Writing Transaction Programs APPC Entry Points: Windows Systems ) Supplied Parameters The supplied parameter is: vcbptr A pointer to the VCB structure for the verb. This parameter is defined as a long integer, and so needs to be cast from a pointer to a long integer. For the definition of the VCB structure for each APPC verb, see Chapter 3, APPC Control Verbs and Chapter 4, APPC Conversation Verbs.
Writing Transaction Programs APPC Entry Points: Windows Systems Usage In addition to canceling the outstanding verb, APPC also ends the conversation on which the verb was issued and brings down the session. If the verb is one that relates to a TP rather than to a conversation (such as RECEIVE_ALLOCATE or TP_STARTED), APPC ends the TP. 2.4.
Writing Transaction Programs APPC Entry Points: Windows Systems • WinAPPCSetBlockingHook (with a different procedure instance address) to specify a new blocking function or to restore a previous one • WinAPPCUnhookBlockingHook (see Section 2.4.11, WinAPPCUnhookBlockingHook), to stop using the current blocking function and return to the default blocking function 2.4.
Writing Transaction Programs APPC Entry Points: Windows Systems int far *AsyncRetCode ); Supplied Parameters The supplied parameters are: hWnd A Windows handle that APPC will use to post a message indicating asynchronous completion of this call. If this parameter is used, the pointer to the AsyncRetCode parameter must be a null pointer. LocalLU A pointer to the alias of the local LU for which configuration information is required.
Writing Transaction Programs APPC Entry Points: Windows Systems APPC_CFG_ERROR_NO_APPC_INIT The application has not issued the WinAPPCStartup call. This call must be issued before GetAppcConfig is used. APPC_CFG_ERROR_INVALID_HWND The application supplied a Windows handle that was not valid.
Writing Transaction Programs APPC Entry Points: Windows Systems A system error occurred. • If the application is using the alternative method to indicate completion, APPC sets the asynchronous return code to one of the return codes in the list for the lParam argument (in the Windows message) when the call completes.
Writing Transaction Programs HP-UX Considerations The address of the buffer supplied by the application to hold the returned data string. Returned Values The return value from the function is one of the following: 0 (zero) The function completed successfully. The returned character string is in the buffer identified by the buffer_addr parameter. This string is terminated by a null character (binary zero), but does not include a trailing new-line (\n) character.
Writing Transaction Programs Windows Considerations 2.6 Windows Considerations WINDOWS This section summarizes the processing considerations that you need to be aware of when developing applications on a Windows client. Windows processing considerations are: • Compiling and linking APPC programs • Terminating applications 2.6.
Writing Transaction Programs Configuration Information 2.7 Configuration Information The SNAplus2 configuration file, which is set up and maintained by the System Administrator, contains information that is required for TPs to communicate. For additional information about configuration, refer to the HP-UX SNAplus2 Administration Guide. 2.7.1 Invoked TP Before writing an invoked TP, you must coordinate the local TP name with the System Administrator. The name can contain up to 64 characters.
Writing Transaction Programs Starting TPs 2.8 Overview of Conversation Security You can use conversation security to require that the invoking TP provide a user ID and password before APPC allocates a conversation with the invoked TP. In configuring the invoked TP, the System Administrator indicates whether to use conversation security. If so, the invoking TP must supply a combination of user_id and password as parameters of the [MC_]ALLOCATE verb.
Writing Transaction Programs Starting TPs 2.9.3 Invoked TPs: User-Started If an invoked TP is configured to be started by a user, the user can start the invoked TP either before or after the invoking TP. A TP started in this manner is called a queued, operator-started TP: • If the user starts the invoking TP first, and does not start the invoked TP before the timeout value for starting the TP (see Section 2.9.6, Timeout Values for Invoked TPs) is reached, the incoming Allocate fails.
Writing Transaction Programs Starting TPs • Partial network name • Whole network name • Partial network name followed by CP name • Fully qualified partner LU name Only a single TP server application can register for a given TP and LU combination, including wildcards. For example, one TP server application can register TPNAME1 and *, while the same TP or another TP server application registers TPNAME1 and LUNAME1.
Writing Transaction Programs Basic Conversations This timeout is defined for the invoked TP in the SNAplus2 invokable TP data file. For more information about the configuration of invoked TPs, refer to the HP-UX SNAplus2 Administration Guide. 2.10 LU-to-LU Sessions An LU-to-LU session is a logical connection between two LUs. Conversations between TPs occur within sessions. One conversation can use a session at a time; many conversations can reuse the same session serially. SNAplus2 enables an LU type 6.
Writing Transaction Programs Basic Conversations • A 2-byte GDS identifier (ID) field (for example, 0x12FF identifies the data as application data) • A data field that can range in length from 0–32,763 bytes The first four bytes are called the LLID.
Writing Transaction Programs Writing TP Servers 2.11.4 Timeouts Versus Critical Errors In a basic conversation, a TP can indicate whether an abend was caused by a timeout or by a critical error. 2.12 Writing TP Servers UNIX Use the following operational guidelines for writing TP servers: 1. Use REGISTER_TP_SERVER to register the application as a TP server. The REGISTER_TP_SERVER verb provides the address of a callback function used in later Attach notifications. 2.
Writing Transaction Programs Writing Portable TPs 2.13 Writing Portable TPs The following guidelines are provided for writing TPs that they will are portable to other operating system environments: • Include the APPC header file without any pathname prefix. Use include options on the compiler to locate the file (see the appropriate section for your operating system, earlier in this chapter). This enables the TP to be used in an environment with a different file system.
APPC Control Verbs 3 APPC Control Verbs This chapter contains a description of each APPC control verb. The following information is provided for each verb: • Definition of the verb. • Structure defining the verb control block (VCB) used by the verb. The structure is defined in the APPC header file /usr/include/sna/appc_c.h(HP-UX) or sdk/winappc.h (Windows). Parameters beginning with reserv are reserved. • Parameters (VCB fields) supplied to and returned by APPC.
APPC Control Verbs TP_STARTED The control verbs are described in the following order: TP_STARTED TP_ENDED RECEIVE_ALLOCATE UNIX GET_LU_STATUS GET_TP_PROPERTIES UNIX SET_TP_PROPERTIES 3.1 TP_STARTED The TP_STARTED verb is issued by the invoking TP. It notifies APPC that the TP is starting, and specifies the local LU that it will use.
APPC Control Verbs TP_STARTED unsigned short unsigned char unsigned char unsigned short unsigned long unsigned char unsigned char unsigned char } TP_STARTED; opcode; opext; reserv2; primary_rc; secondary_rc; lu_alias[8]; tp_id[8]; tp_name[64]; 3.1.3 Supplied Parameters The TP supplies the following parameters to APPC: opcode AP_TP_STARTED lu_alias Alias by which the local LU is known to the local TP. This name must match an LU alias established during configuration.
APPC Control Verbs TP_STARTED 3.1.4 Returned Parameters After the verb executes, APPC returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was not successful. Successful Execution If the verb executes successfully, APPC returns the following parameters: primary_rc AP_OK tp_id Identifier for the local TP.
APPC Control Verbs TP_ENDED APPC does not return secondary return codes with these primary return codes. 3.1.5 State When Issued TP_STARTED must be the first APPC verb issued by the invoking TP. Consequently, no conversations are active and no conversation state exists. A single APPC program can issue more than one TP_STARTED verb. Each verb creates a logically different APPC TP, although they are all executing in the same process. 3.1.
APPC Control Verbs TP_ENDED unsigned char unsigned char unsigned short unsigned long unsigned char unsigned char } TP_ENDED; opext; reserv2; primary_rc; secondary_rc; tp_id[8]; type; 3.2.3 Supplied Parameters The TP supplies the following parameters to APPC: opcode AP_TP_ENDED tp_id Identifier for the local TP. The value of this parameter was returned by the TP_STARTED verb for the invoking TP or by the RECEIVE_ALLOCATE verb for the invoked TP. type Specifies how to end the TP.
APPC Control Verbs TP_ENDED AP_PARAMETER_CHECK secondary_rc Possible values are: AP_BAD_TP_ID APPC did not recognize the tp_id as an assigned TP identifier. AP_BAD_TYPE The value of the type parameter was not valid. UNIX AP_INVALID_FORMAT The reserved parameter format was set to a nonzero value. AP_SYNC_NOT_ALLOWED The application issued this verb within a callback routine, using the synchronous APPC entry point. Any verb issued from a callback routine must use the asynchronous entry point.
APPC Control Verbs RECEIVE_ALLOCATE 3.3 RECEIVE_ALLOCATE The RECEIVE_ALLOCATE verb is issued by the invoked TP. It confirms that the invoked TP is ready to begin a conversation with the invoking TP, which issued the [MC_]ALLOCATE verb. In response to this verb, APPC establishes a conversation between the two TPs, generates a TP identifier for the invoked TP, and generates a conversation identifier. These identifiers are required parameters for subsequent APPC verbs.
APPC Control Verbs RECEIVE_ALLOCATE 3.3.
APPC Control Verbs RECEIVE_ALLOCATE UNIX The TP can specify that it will accept incoming Attaches for any TP name, by setting this parameter to 64 EBCDIC spaces. For more information about how SNAplus2 routes incoming Attaches to TPs, see Section 3.3.8, Routing for Incoming Attaches. lu_alias For the standard form of RECEIVE_ALLOCATE, this parameter is reserved; set it to a null string.
APPC Control Verbs RECEIVE_ALLOCATE This parameter determines whether the TPs can request confirmation of receipt of data and confirm receipt of data. Possible values are: AP_CONFIRM_SYNC_LEVEL The partner TPs can use confirmation processing in this conversation. AP_SYNCPT The TPs can use LU 6.2 Syncpoint functions in this conversation. For more information, see Section 1.12, Syncpoint Support. AP_NONE Confirmation processing is not used in this conversation.
APPC Control Verbs RECEIVE_ALLOCATE AP_NO The partner TP did not supply PIP data. duplex_type Duplex type of the new conversation. Possible values are: AP_HALF_DUPLEX AP_FULL_DUPLEX password If the partner TP set [MC_]ALLOCATE’s security parameter to AP_PGM, this parameter contains the password specified by the partner TP on the [MC_]ALLOCATE verb. The password is a type-AE EBCDIC character string, padded on the right with EBCDIC spaces to 10 characters if necessary.
APPC Control Verbs RECEIVE_ALLOCATE State Check If the conversation is in the wrong state when the TP issues this verb, APPC returns the following parameters: primary_rc AP_STATE_CHECK secondary_rc AP_ALLOCATE_NOT_PENDING APPC did not find an incoming Allocate (from the invoking TP) to match the combination of TP name, LU alias, or both supplied by the RECEIVE_ALLOCATE verb. The RECEIVE_ALLOCATE verb waited for the incoming Allocate and eventually timed out. For more information, see Section 3.3.
APPC Control Verbs GET_LU_STATUS Allocate is already waiting), or a finite value (RECEIVE_ALLOCATE fails unless an incoming Allocate arrives within the specified time). For more information, refer to the HP-UX SNAplus2 Administration Guide. 3.3.8 Routing for Incoming Attaches UNIX If the application does not specify a dload_id on the RECEIVE_ALLOCATE, it can use the tp_name and lu_alias parameters of RECEIVE_ALLOCATE to specify the range of incoming Attaches that it will accept.
APPC Control Verbs GET_LU_STATUS Note If two or more TPs are using the same combination of local LU and partner LU, it is important that only one of them issues this verb. SNAplus2 maintains the zero sessions indicator for each pair of LUs independently of the TPs using them, and resets it each time this verb is issued.
APPC Control Verbs GET_LU_STATUS AP_OK active_sess Specifies the number of sessions currently active between the local LU and the specified partner LU. zero_sess Specifies whether the number of active sessions between the two LUs has dropped to 0 (zero) at any time since the last GET_LU_STATUS verb was issued. Possible values are: AP_YES The session count has dropped to 0 (zero). AP_NO At least one session has been active at all times since the verb was last issued.
APPC Control Verbs GET_TP_PROPERTIES 3.4.5 State Change The conversation state does not change for this verb. 3.5 GET_TP_PROPERTIES The GET_TP_PROPERTIES verb returns information about the attributes of the local TP and of the Logical Unit of Work (LUW) in which the TP is participating. A Logical Unit of Work is a transaction between APPC TPs to accomplish a particular task; it may involve two communicating TPs or a sequence of conversations between several TPs. 3.5.
APPC Control Verbs GET_TP_PROPERTIES unsigned short opcode; unsigned char reserv2[2]; unsigned short primary_rc; unsigned long secondary_rc; unsigned char tp_id[8]; unsigned char tp_name[64]; unsigned char lu_alias[8]; unsigned char luw_id[26]; unsigned char fqlu_name[17]; unsigned char reserv3[10]; unsigned char user_id[10]; } GET_TP_PROPERTIES; 3.5.3 Supplied Parameters The TP supplies the following parameters to APPC: opcode AP_GET_TP_PROPERTIES tp_id Identifier for the local TP.
APPC Control Verbs GET_TP_PROPERTIES The LUWID consists of the following parameters: luw_id.fq_length The length (1–17 bytes) of the fully qualified LU name associated with the Logical Unit of Work (the LU name itself is specified by the luw_id.fq_luw_name parameter). luw_id.fq_luw_name The fully qualified LU name associated with the Logical Unit of Work. This name is a 17-byte EBCDIC string, padded on the right with EBCDIC spaces.
APPC Control Verbs GET_TP_PROPERTIES verified Specifies whether conversation security has been verified for this conversation. Possible values are: AP_YES Conversation security has been verified. The invoking TP supplied a user ID (returned as the user_id parameter on this verb), and either supplied a valid password or indicated that conversation security had already been verified. AP_NO Conversation security has not been verified. The invoked TP does not require a user ID and password.
APPC Control Verbs SET_TP_PROPERTIES The value of tp_id did not match a TP identifier assigned by APPC. UNIX AP_INVALID_FORMAT The format byte is not a valid value. AP_SYNC_NOT_ALLOWED The application issued this verb within a callback routine, using the synchronous APPC entry point. Any verb issued from a callback routine must use the asynchronous entry point. State Check No state check errors occur for this verb.
APPC Control Verbs SET_TP_PROPERTIES password, and is now invoking a third TP as part of the same transaction; in this case, APPC sends the user ID from the original TP without requiring a password. Alternatively, if the TP was not invoked by another TP, APPC uses the HP-UX user name with which the application is running as the user ID for conversation security.
APPC Control Verbs SET_TP_PROPERTIES The value of this parameter was returned by the TP_STARTED verb in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP. set_prot_id Specifies whether APPC is to modify the protected Logical Unit of Work identifier. Possible values are: AP_YES Modify the protected LUWID for this TP. AP_NO Leave the protected LUWID unchanged. new_prot_id Specifies whether APPC should generate a new protected Logical Unit of Work identifier, or to use the one specified on this verb.
APPC Control Verbs SET_TP_PROPERTIES Generate a new unprotected LUWID. AP_NO Set the TP’s unprotected LUWID to the one supplied on this verb. unprot_id If set_unprot_id is set to AP_YES and new_unprot_id is set to AP_NO, this structure specifies the new unprotected LUWID for the TP; otherwise this structure is reserved. The structure contains the following parameters: unprot_id.
APPC Control Verbs SET_TP_PROPERTIES Successful Execution If the verb executes successfully, APPC returns the following parameters: primary_rc AP_OK prot_id If set_prot_id and new_prot_id are both set to AP_YES, this structure specifies the new protected LUWID for the TP, as generated by APPC. The structure contains the following parameters: prot_id.fq_length The length (1–17 bytes) of the fully qualified LU name associated with the Logical Unit of Work (the LU name itself is specified by the prot_id.
APPC Control Verbs SET_TP_PROPERTIES Possible values are: AP_BAD_TP_ID The value of tp_id did not match a TP identifier assigned by APPC. AP_INVALID_FORMAT The reserved parameter format was set to a nonzero value. AP_SYNC_NOT_ALLOWED The application issued this verb within a callback routine, using the synchronous APPC entry point. Any verb issued from a callback routine must use the asynchronous entry point. State Check No state check errors occur for this verb.
APPC Conversation Verbs 4 APPC Conversation Verbs This chapter contains a description of each APPC conversation verb. The following information is provided for each verb: • Definition of the verb. • Structure defining the verb control block (VCB) used by the verb. The structure is defined in the APPC header file /usr/include/sna/appc_c.h(HP-UX) or sdk/winappc.h (Windows). Parameters beginning with reserv are reserved. • Parameters (VCB fields) supplied to and returned by APPC.
APPC Conversation Verbs GET_TYPE The conversation verbs are described in the following order: GET_TYPE [MC_]ALLOCATE [MC_]CONFIRM [MC_]CONFIRMED [MC_]DEALLOCATE [MC_]FLUSH [MC_]GET_ATTRIBUTES [MC_]PREPARE_TO_RECEIVE [MC_]RECEIVE_AND_POST [MC_]RECEIVE_AND_WAIT [MC_]RECEIVE_IMMEDIATE [MC_]RECEIVE_EXPEDITED_DATA [MC_]REQUEST_TO_SEND [MC_]SEND_CONVERSATION [MC_]SEND_DATA [MC_]SEND_ERROR [MC_]SEND_EXPEDITED_DATA [MC_]TEST_RTS [MC_]TEST_RTS_AND_POST 4.
APPC Conversation Verbs GET_TYPE unsigned char } GET_TYPE; duplex_type; 4.1.2 VCB Structure: GET_TYPE (Windows) WINDOWS The definition of the VCB structure for the GET_TYPE verb is as follows: typedef struct get_type { unsigned short opcode; unsigned char opext; unsigned char reserv2; unsigned short primary_rc; unsigned long secondary_rc; unsigned char tp_id[8]; unsigned long conv_id; unsigned char conv_type; } GET_TYPE; 4.1.
APPC Conversation Verbs GET_TYPE primary_rc AP_OK conv_type Conversation type of the conversation identified by conv_id. Possible values are: AP_BASIC_CONVERSATION AP_MAPPED_CONVERSATION duplex_type Duplex type of the conversation identified by conv_id.
APPC Conversation Verbs MC_ALLOCATE and ALLOCATE AP_INVALID_VERB AP_TP_BUSY AP_UNEXPECTED_SYSTEM_ERROR WINDOWS AP_COMM_SUBSYSTEM_NOT_LOADED AP_STACK_TOO_SMALL AP_INVALID_VERB_SEGMENT APPC does not return secondary return codes with these primary return codes. 4.1.5 State When Issued The conversation can be in any state except Reset when the TP issues this verb. 4.1.6 State Change The conversation state does not change for this verb. 4.
APPC Conversation Verbs MC_ALLOCATE and ALLOCATE unsigned char unsigned char unsigned char unsigned char AP_UINT32 AP_UINT32 unsigned char unsigned char unsigned char unsigned char unsigned char unsigned char unsigned char AP_UINT16 unsigned char unsigned char unsigned char unsigned char } MC_ALLOCATE; sync_level; reserv4[2]; rtn_ctl; duplex_type; conv_group_id; sense_data; plu_alias[8]; mode_name[8]; tp_name[64]; security; reserv6[11]; pwd[10]; user_id[10]; pip_dlen; *pip_dptr; reserv6a; fqplu_name[17];
APPC Conversation Verbs MC_ALLOCATE and ALLOCATE The definition of the VCB structure for the MC_ALLOCATE verb is as follows: typedef struct mc_allocate { unsigned short opcode; unsigned char opext; unsigned char reserv2; unsigned short primary_rc; unsigned long secondary_rc; unsigned char tp_id[8]; unsigned long conv_id; unsigned char reserv3; unsigned char sync_level; unsigned char reserv4[2]; unsigned char rtn_ctl; unsigned char reserv5; unsigned long conv_group_id; unsigned long sense_data; unsigned cha
APPC Conversation Verbs MC_ALLOCATE and ALLOCATE unsigned short unsigned char far unsigned char unsigned char unsigned char } ALLOCATE; pip_dlen; *pip_dptr; reserv7; fqplu_name[17]; reserv8[8]; 4.2.5 Supplied Parameters The TP supplies the following parameters to APPC: opcode Possible values are: AP_M_ALLOCATE For the MC_ALLOCATE verb. AP_B_ALLOCATE For the ALLOCATE verb. opext Possible values are: AP_MAPPED_CONVERSATION For the MC_ALLOCATE verb. AP_BASIC_CONVERSATION For the ALLOCATE verb.
APPC Conversation Verbs MC_ALLOCATE and ALLOCATE This parameter determines whether the TPs can request confirmation of receipt of data and confirm receipt of data. Possible values are: AP_NONE Confirmation processing will not be used in this conversation. AP_CONFIRM_SYNC_LEVEL The TPs can use confirmation processing in this conversation. This value can be used only in a halfduplex conversation; confirmation processing is not supported in a full-duplex conversation. UNIX AP_SYNCPT The TPs can use LU 6.
APPC Conversation Verbs MC_ALLOCATE and ALLOCATE As for AP_WHEN_SESSION_ALLOCATED, except that the LU always allocates the conversation to a contention-winner session; it will not use a contention-loser session. AP_WHEN_CONLOSER_ALLOC As for AP_WHEN_SESSION_ALLOCATED, except that the LU always allocates the conversation to a contention-loser session; it will not use a contention-winner session.
APPC Conversation Verbs MC_ALLOCATE and ALLOCATE • Special characters $, #, and @ The first character in the string must be an uppercase letter, or can be # for one of the SNA-defined modes such as #INTER. For information about SNA-defined modes, see the HP-UX SNAplus2 Administration Guide. If the mode name is fewer than eight characters long, pad it on the right with EBCDIC blanks (0x40). A mode name can also be all EBCDIC blanks (0x40).
APPC Conversation Verbs MC_ALLOCATE and ALLOCATE If you use this value, the tp_id supplied on this [MC_]ALLOCATE verb must be the same as the one that was returned on the RECEIVE_ALLOCATE verb when this TP was invoked. UNIX This value can also be used if your TP was not invoked by another TP, but has obtained and verified the appropriate security information by another means (for example from the HP-UX user name and password supplied during logon).
APPC Conversation Verbs MC_ALLOCATE and ALLOCATE Address of buffer containing PIP data. Use this parameter only if pip_dlen is greater than 0 (zero). PIP data can consist of initialization parameters or environment setup information required by a partner TP or remote operating system. The PIP data must follow the General Data Stream format. For further information, refer to the IBM publication Systems Network Architecture Format and Protocol Reference Manual: Architecture Logic for LU Type 6.2.
APPC Conversation Verbs MC_ALLOCATE and ALLOCATE (Returned for basic-conversation ALLOCATE only) The value specified for conv_type was not valid. AP_BAD_DUPLEX_TYPE The value specified for duplex_type was not valid. AP_BAD_PARTNER_LU_ALIAS One of the following has occurred: • The plu_alias parameter did not match any defined partner LU alias. • The value specified for fqplu_name was not valid. AP_BAD_RETURN_CONTROL The value specified for rtn_ctl was not valid.
APPC Conversation Verbs MC_ALLOCATE and ALLOCATE Session Not Available Depending on the value specified for rtn_ctl, APPC may return the following parameter: primary_rc AP_UNSUCCESSFUL 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.
APPC Conversation Verbs MC_CONFIRM and CONFIRM AP_COMM_SUBSYSTEM_ABENDED AP_INVALID_VERB AP_TP_BUSY AP_UNEXPECTED_SYSTEM_ERROR WINDOWS AP_COMM_SUBSYSTEM_NOT_LOADED AP_STACK_TOO_SMALL AP_INVALID_VERB_SEGMENT APPC does not return secondary return codes with these primary return codes. 4.2.7 State When Issued The conversation state is Reset when the TP issues this verb.
APPC Conversation Verbs MC_CONFIRM and CONFIRM Note This verb can be used only in a half-duplex conversation; it is not valid in a full-duplex conversation. In response to the [MC_]CONFIRM verb, the partner TP normally issues the [MC_]CONFIRMED verb to confirm that it has received the data without error. (If the partner TP encounters an error, it issues the [MC_]SEND_ERROR verb or abnormally deallocates the conversation.
APPC Conversation Verbs MC_CONFIRM and CONFIRM unsigned short unsigned char unsigned char unsigned short unsigned long unsigned char unsigned long unsigned char } MC_CONFIRM; opcode; opext; reserv2; primary_rc; secondary_rc; tp_id[8]; conv_id; rts_rcvd; 4.3.
APPC Conversation Verbs MC_CONFIRM and CONFIRM versions of the header file, in which this parameter was reserved, will still operate unchanged with SNAplus2 and there is no need to rebuild them.) tp_id Identifier for the local TP. The value of this parameter was returned by the TP_STARTED verb in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP. conv_id Conversation identifier.
APPC Conversation Verbs MC_CONFIRM and CONFIRM Parameter Check If the verb does not execute because of a parameter error, APPC returns the following parameters: primary_rc AP_PARAMETER_CHECK secondary_rc Possible values are: AP_BAD_CONV_ID The value of conv_id did not match a conversation identifier assigned by APPC. AP_BAD_TP_ID The value of tp_id did not match a TP identifier assigned by APPC.
APPC Conversation Verbs MC_CONFIRM and CONFIRM AP_ALLOCATION_ERROR secondary_rc 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_SEC_BAD_PROTOCOL_VIOLATION AP_SEC_BAD_PASSWORD_EXPIRED AP_SEC_BAD_PASSWORD_INVALID AP_SEC_BAD_USERID_REVOKED AP_SEC_BAD_USERID_INVALID AP_SEC_BAD_USERI
APPC Conversation Verbs MC_CONFIRM and CONFIRM primary_rc AP_DEALLOC_ABEND_PROG AP_DEALLOC_ABEND_SVC AP_DEALLOC_ABEND_TIMER AP_SVC_ERROR_PURGING APPC does not return secondary return codes with these primary return codes. 4.3.7 State When Issued The conversation must be in Send or Send_Pending state when the TP issues this verb. 4.3.8 State Change State changes, summarized in the following table, are based on the value of the primary_rc parameter.
APPC Conversation Verbs MC_CONFIRMED and CONFIRMED 4.4 MC_CONFIRMED and CONFIRMED The MC_CONFIRMED or CONFIRMED verb replies 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. Note This verb can be used only in a half-duplex conversation; it is not valid in a full-duplex conversation.
APPC Conversation Verbs MC_CONFIRMED and CONFIRMED AP_UINT16 unsigned char unsigned char AP_UINT16 AP_UINT32 unsigned char AP_UINT32 } MC_CONFIRMED; opcode; opext; format; primary_rc; secondary_rc; tp_id[8]; conv_id; /* Reserved 4.4.
APPC Conversation Verbs MC_CONFIRMED and CONFIRMED 4.4.7 Supplied Parameters The TP supplies the following parameters to APPC: opcode Possible values are: AP_M_CONFIRMED For the MC_CONFIRMED verb. AP_B_CONFIRMED For the CONFIRMED verb. opext Possible values are: AP_MAPPED_CONVERSATION For the MC_CONFIRMED verb. AP_BASIC_CONVERSATION For the CONFIRMED verb. If the verb is being issued as a non-blocking verb, combine the value above (using a logical OR) with the value AP_NON_BLOCKING.
APPC Conversation Verbs MC_CONFIRMED and CONFIRMED AP_PARAMETER_CHECK secondary_rc Possible values are: AP_BAD_CONV_ID The value of conv_id did not match a conversation identifier assigned by APPC. AP_BAD_TP_ID The value of tp_id did not match a TP identifier assigned by APPC. UNIX AP_INVALID_FORMAT The reserved field format was set to a nonzero value. AP_SYNC_NOT_ALLOWED The application issued this verb within a callback routine, using the synchronous APPC entry point.
APPC Conversation Verbs MC_DEALLOCATE and DEALLOCATE 4.4.9 State When Issued The conversation must be in one of the following states when the TP issues this verb: • Confirm • Confirm_Send • Confirm_Deallocate 4.4.10 State Change The new state is determined by the old state—the state of the conversation when the local TP issued the [MC_]CONFIRMED verb. The old state is indicated by the value of the what_rcvd parameter of the preceding receive verb.
APPC Conversation Verbs MC_DEALLOCATE and DEALLOCATE void * unsigned char } MC_DEALLOCATE; correlator; reserv6[4]; 4.5.
APPC Conversation Verbs MC_DEALLOCATE and DEALLOCATE unsigned char unsigned short unsigned long unsigned char unsigned long unsigned char unsigned char unsigned short unsigned char far } DEALLOCATE; reserv2; primary_rc; secondary_rc; tp_id[8]; conv_id; reserv3; dealloc_type; log_dlen; *log_dptr; 4.5.5 Supplied Parameters The TP supplies the following parameters to APPC: opcode Possible values are: AP_M_DEALLOCATE For the MC_DEALLOCATE verb. AP_B_DEALLOCATE For the DEALLOCATE verb.
APPC Conversation Verbs MC_DEALLOCATE and DEALLOCATE Specifies how to perform the deallocation. The possible values are listed below. Using AP_ABEND or any of the AP_ABEND_* values deallocates the conversation abnormally. If conversation is in Send state when the local TP issues the [MC_]DEALLOCATE verb, APPC sends contents of the local LU’s send buffer to the partner TP before deallocating the conversation.
APPC Conversation Verbs MC_DEALLOCATE and DEALLOCATE • Passing the original [MC_]DEALLOCATE verb through to SNAplus2 when syncpoint processing has completed When SNAplus2 receives the [MC_]DEALLOCATE verb with a dealloc_type of AP_SYNC_LEVEL on a conversation with sync_level of AP_SYNCPT, it assumes that the Syncpoint Manager has already performed all the necessary syncpoint processing, and processes the verb as for a sync_level of AP_NONE.
APPC Conversation Verbs MC_DEALLOCATE and DEALLOCATE This value indicates that the local TP is deallocating the conversation because it did not accept the security parameters specified by the partner TP on [MC_]ALLOCATE. The error will be reported to the partner TP with the return codes AP_ALLOCATION_FAILURE and AP_SECURITY_NOT_VALID. log_dlen Number of bytes of data to be sent to the error log file. The range for this value is 0–32,767.
APPC Conversation Verbs MC_DEALLOCATE and DEALLOCATE AP_OK expd_rcvd Expedited data indicator. This parameter is used only in full-duplex conversations, where the TP can continue to receive expedited data after successfully issuing [MC_]DEALLOCATE. Possible values are: AP_YES The partner TP has sent expedited data that the local TP has not yet received. To receive this data, the local TP can use the [MC_]RECEIVE_EXPEDITED_DATA verb. This indicator can be set on a number of APPC verbs.
APPC Conversation Verbs MC_DEALLOCATE and DEALLOCATE (Returned for basic-conversation DEALLOCATE only) The log data was longer than the allocated data segment, or the address of the log data buffer was incorrect.
APPC Conversation Verbs MC_DEALLOCATE and DEALLOCATE AP_SEC_BAD_UNAUTHRZD_TO_TP AP_SEC_BAD_INSTALL_EXIT_FAILED AP_SEC_BAD_PROCESSING_FAILURE UNIX primary_rc AP_BACKED_OUT secondary_rc AP_BO_NO_RESYNC AP_BO_RESYNC primary_rc AP_COMM_SUBSYSTEM_ABENDED AP_CONV_FAILURE_NO_RETRY AP_CONV_FAILURE_RETRY AP_CONVERSATION_TYPE_MIXED AP_DUPLEX_TYPE_MIXED AP_PROG_ERROR_PURGING AP_INVALID_VERB AP_TP_BUSY AP_UNEXPECTED_SYSTEM_ERROR WINDOWS AP_COMM_SUBSYSTEM_NOT_LOADED AP_STACK_TOO_SMALL AP_INVALID_VERB_SEGMENT APPC
APPC Conversation Verbs MC_DEALLOCATE and DEALLOCATE dealloc_type Allowed state AP_FLUSH Send_Receive (full-duplex conversation only), Send or Send_Pending AP_SYNC_LEVEL Send_Receive (full-duplex conversation only), Send or Send_Pending AP_ABEND AP_ABEND_PROG AP_ABEND_SVC AP_ABEND_TIMER Any except Reset 4.5.8 State Change State changes, summarized in the following table, are based on the value of the primary_rc parameter.
APPC Conversation Verbs MC_DEALLOCATE and DEALLOCATE The callback routine is defined as follows: void (*AP_CALLBACK) ( void * unsigned char AP_UINT32 AP_UINT16 AP_CORR vcb, tp_id[8], conv_id, type, corr ); typedef union ap_corr { void * AP_UINT32 AP_INT32 } AP_CORR; corr_p; corr_l; corr_i; SNAplus2 calls the routine with the following parameters: vcb Pointer to the original [MC_]DEALLOCATE VCB supplied by the application.
APPC Conversation Verbs MC_FLUSH and FLUSH 4.6 MC_FLUSH and FLUSH The MC_FLUSH or FLUSH verb 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. 4.6.
APPC Conversation Verbs MC_FLUSH and FLUSH unsigned char unsigned char unsigned short unsigned long unsigned char unsigned long } MC_FLUSH; opext; reserv2; primary_rc; secondary_rc; tp_id[8]; conv_id; 4.6.
APPC Conversation Verbs MC_FLUSH and FLUSH tp_id Identifier for the local TP. The value of this parameter was returned by the TP_STARTED verb in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP. conv_id Conversation identifier. The value of this parameter was returned by the [MC_]ALLOCATE verb in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP. 4.6.
APPC Conversation Verbs MC_GET_ATTRIBUTES and GET_ATTRIBUTES primary_rc AP_STATE_CHECK secondary_rc AP_FLUSH_NOT_SEND_STATE The conversation was not in Send or Send_Pending state. Other Conditions If the verb does not execute because other conditions exist, APPC returns primary return codes (and, if applicable, secondary return codes). For information about these return codes, see Appendix B, Common Return Codes.
APPC Conversation Verbs MC_GET_ATTRIBUTES and GET_ATTRIBUTES unsigned char opext; unsigned char format; AP_UINT16 primary_rc; AP_UINT32 secondary_rc; unsigned char tp_id[8]; AP_UINT32 conv_id; unsigned char reserv3; unsigned char sync_level; unsigned char mode_name[8]; unsigned char net_name[8]; unsigned char lu_name[8]; unsigned char lu_alias[8]; unsigned char plu_alias[8]; unsigned char plu_un_name[8]; unsigned char reserv4[2]; unsigned char fqplu_name[17]; unsigned char reserv5; unsigned char user_id[10
APPC Conversation Verbs MC_GET_ATTRIBUTES and GET_ATTRIBUTES AP_UINT32 unsigned char unsigned char unsigned char LUWID_OVERLAY unsigned char } GET_ATTRIBUTES; conv_group_id; conv_corr_len; conv_corr[8]; reserv6[13]; luw_id; sess_id[8]; typedef struct luwid_overlay { unsigned char fq_length; unsigned char fq_luw_name[17]; unsigned char instance[6]; unsigned char sequence[2]; } LUWID_OVERLAY; 4.7.
APPC Conversation Verbs MC_GET_ATTRIBUTES and GET_ATTRIBUTES unsigned short unsigned long unsigned char unsigned long unsigned char unsigned char unsigned char unsigned char unsigned char unsigned char unsigned char unsigned char unsigned char unsigned char unsigned char unsigned char unsigned long unsigned char unsigned char unsigned char } GET_ATTRIBUTES; primary_rc; secondary_rc; tp_id[8]; conv_id; reserv3; sync_level; mode_name[8]; net_name[8]; lu_name[8]; lu_alias[8]; plu_alias[8]; plu_un_name[8]; re
APPC Conversation Verbs MC_GET_ATTRIBUTES and GET_ATTRIBUTES The value of this parameter was returned by the [MC_]ALLOCATE verb in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP. 4.7.6 Returned Parameters After the verb executes, APPC returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was not successful. Successful Execution If the verb executes successfully, APPC returns the following parameters.
APPC Conversation Verbs MC_GET_ATTRIBUTES and GET_ATTRIBUTES • Uppercase letters • Numerals 0–9 • Special characters $, #, and @ lu_alias Alias by which the local LU is known to the local TP. This is an 8-byte ASCII character string. plu_alias Alias by which the partner LU is known to the local TP. This is an 8-byte ASCII character string. plu_un_name Uninterpreted name of partner LU—the name of the partner LU as defined at the System Services Control Point (SSCP).
APPC Conversation Verbs MC_GET_ATTRIBUTES and GET_ATTRIBUTES The length (0–8 bytes) of the conversation correlator (see the description of the conv_corr parameter for more information). conv_corr The conversation correlator assigned by the invoking TP’s node when the conversation was allocated. UNIX For TPs that use Syncpoint processing, the Syncpoint Manager uses this parameter to identify the conversation during resynchronization processing.
APPC Conversation Verbs MC_GET_ATTRIBUTES and GET_ATTRIBUTES AP_BAD_CONV_ID The value of conv_id did not match a conversation identifier assigned by APPC. AP_BAD_TP_ID The value of tp_id did not match a TP identifier assigned by APPC. UNIX AP_INVALID_FORMAT The format byte was set to a value that was not valid. AP_SYNC_NOT_ALLOWED The application issued this verb within a callback routine, using the synchronous APPC entry point.
APPC Conversation Verbs MC_PREPARE_TO_RECEIVE and PREPARE_TO_RECEIVE 4.8 MC_PREPARE_TO_RECEIVE and PREPARE_TO_RECEIVE The MC_PREPARE_TO_RECEIVE or PREPARE_TO_RECEIVE verb changes the state of the conversation for the local TP from Send or Send_Pending to Receive. Note This verb can be used only in a half-duplex conversation; it is not valid in a full-duplex conversation.
APPC Conversation Verbs MC_PREPARE_TO_RECEIVE and PREPARE_TO_RECEIVE } PREPARE_TO_RECEIVE; 4.8.
APPC Conversation Verbs MC_PREPARE_TO_RECEIVE and PREPARE_TO_RECEIVE AP_MAPPED_CONVERSATION For the MC_PREPARE_TO_RECEIVE verb. AP_BASIC_CONVERSATION For the PREPARE_TO_RECEIVE verb. If the verb is being issued as a non-blocking verb, combine the value above (using a logical OR) with the value AP_NON_BLOCKING. tp_id Identifier for the local TP. The value of this parameter was returned by the TP_STARTED verb in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP. conv_id Conversation identifier.
APPC Conversation Verbs MC_PREPARE_TO_RECEIVE and PREPARE_TO_RECEIVE • Intercepting the [MC_]PREPARE_TO_RECEIVE verb when a ptr_type of AP_SYNC_LEVEL is specified • Performing the required syncpoint processing • Passing the original [MC_]PREPARE_TO_RECEIVE verb through to SNAplus2 when syncpoint processing has completed When SNAplus2 receives the [MC_]PREPARE_TO_RECEIVE verb with a ptr_type of AP_SYNC_LEVEL on a conversation with sync_level of AP_SYNCPT, it assumes that the Syncpoint Manager has alre
APPC Conversation Verbs MC_PREPARE_TO_RECEIVE and PREPARE_TO_RECEIVE The value of conv_id did not match a conversation identifier assigned by APPC. AP_BAD_TP_ID The value of tp_id did not match a TP identifier assigned by APPC. AP_P_TO_R_INVALID_FOR_FDX The local TP attempted to use the [MC_]PREPARE_TO_RECEIVE verb in a full-duplex conversation. This verb can be used only in a half-duplex conversation. AP_P_TO_R_INVALID_TYPE The ptr_type parameter was not set to a valid value.
APPC Conversation Verbs MC_PREPARE_TO_RECEIVE and PREPARE_TO_RECEIVE AP_SEC_BAD_PASSWORD_EXPIRED AP_SEC_BAD_PASSWORD_INVALID AP_SEC_BAD_USERID_REVOKED AP_SEC_BAD_USERID_INVALID AP_SEC_BAD_USERID_MISSING AP_SEC_BAD_PASSWORD_MISSING AP_SEC_BAD_UID_NOT_DEFD_TO_GRP AP_SEC_BAD_UNAUTHRZD_AT_RLU AP_SEC_BAD_UNAUTHRZD_FROM_LLU AP_SEC_BAD_UNAUTHRZD_TO_TP AP_SEC_BAD_INSTALL_EXIT_FAILED AP_SEC_BAD_PROCESSING_FAILURE UNIX primary_rc AP_BACKED_OUT secondary_rc AP_BO_NO_RESYNC AP_BO_RESYNC primary_rc AP_COMM_SUBSYSTEM
APPC Conversation Verbs MC_RECEIVE and RECEIVE Verbs 4.8.8 State Change State changes, summarized in the following table, are based on the value of the primary_rc parameter.
APPC Conversation Verbs MC_RECEIVE and RECEIVE Verbs Note The [MC_]RECEIVE_EXPEDITED_DATA verb also receives data from the partner TP, but it receives data that was sent as expedited flow data rather than normal flow data. This verb is described separately after the other RECEIVE verbs. 4.9.1 How a TP Receives Data The process through which the local TP receives data is as follows: 1. The local TP issues a receive verb until it finishes receiving a complete unit of data.
APPC Conversation Verbs MC_RECEIVE and RECEIVE Verbs The local TP is now in Confirm_Deallocate state, so it will normally issue the [MC_]CONFIRMED verb to confirm deallocation of the conversation. AP_CONFIRM_SEND (half-duplex conversation only) The partner TP issued the [MC_]PREPARE_TO_RECEIVE verb with ptr_type and dealloc_type parameters indicating that confirmation was required, or issued the [MC_]SEND_DATA verb with a send type of PREPARE_TO_RECEIVE_CONFIRM.
APPC Conversation Verbs MC_RECEIVE_AND_POST and RECEIVE_AND_POST • A primary_rc parameter with a value other than AP_OK (for example, AP_DEALLOC_NORMAL) • A what_rcvd parameter that includes SEND, CONFIRM, CONFIRM_SEND, or CONFIRM_DEALLOCATE To determine if end of data has been reached, the local TP reissues one of the RECEIVE verbs. If the new primary_rc parameter contains AP_OK and what_rcvd contains AP_DATA or AP_DATA_INCOMPLETE, end of data has not been reached.
APPC Conversation Verbs MC_RECEIVE_AND_POST and RECEIVE_AND_POST unsigned char expd_rcvd; AP_UINT16 max_len; AP_UINT16 dlen; unsigned char *dptr; void (*callback)(); unsigned char reserv6; } MC_RECEIVE_AND_POST; 4.10.
APPC Conversation Verbs MC_RECEIVE_AND_POST and RECEIVE_AND_POST } MC_RECEIVE_AND_POST; 4.10.
APPC Conversation Verbs MC_RECEIVE_AND_POST and RECEIVE_AND_POST conv_id Conversation identifier. The value of this parameter was returned by the [MC_]ALLOCATE verb in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP. rtn_status Indicates whether status information and data can be returned on the same verb. Possible values are: AP_YES Status information, if available, is returned with the last part of a data record. AP_NO Status information is not returned with data.
APPC Conversation Verbs MC_RECEIVE_AND_POST and RECEIVE_AND_POST 4.10.6 Returned Parameters After the verb executes, APPC returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was not successful. When this verb is issued, it returns immediately with a primary_rc which indicates whether or not the verb was issued successfully.
APPC Conversation Verbs MC_RECEIVE_AND_POST and RECEIVE_AND_POST For MC_RECEIVE_AND_POST, this value indicates 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 the fill parameter set to AP_LL, this value indicates that the local TP has received an incomplete logical record.
APPC Conversation Verbs MC_RECEIVE_AND_POST and RECEIVE_AND_POST As for AP_DATA_INCOMPLETE, except that the received data was in User Control Data format. AP_USER_CONTROL_DATA_COMPLETE As for AP_DATA_COMPLETE, except that the received data was in User Control Data format. AP_UC_DATA_COMPLETE_SEND As for AP_DATA_COMPLETE_SEND, except that the received data was in User Control Data format.
APPC Conversation Verbs MC_RECEIVE_AND_POST and RECEIVE_AND_POST AP_YES The partner TP has sent expedited data that the local TP has not yet received. To receive this data, the local TP can use the [MC_]RECEIVE_EXPEDITED_DATA verb. This indicator can be set on a number of APPC verbs. It continues to be set on subsequent verbs until the local TP issues the [MC_]RECEIVE_EXPEDITED_DATA verb to receive the data. AP_NO There is no expedited data waiting to be received.
APPC Conversation Verbs MC_RECEIVE_AND_POST and RECEIVE_AND_POST The application issued this verb within a callback routine, using the synchronous APPC entry point. Any verb issued from a callback routine must use the asynchronous entry point. AP_INVALID_CALLBACK_HANDLE The callback parameter was set to a null pointer, and the verb was issued using the synchronous entry point (or using the asynchronous entry point with a null pointer to a callback routine). For more information, see Section 4.10.
APPC Conversation Verbs MC_RECEIVE_AND_POST and RECEIVE_AND_POST secondary_rc 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_SEC_BAD_PROTOCOL_VIOLATION AP_SEC_BAD_PASSWORD_EXPIRED AP_SEC_BAD_PASSWORD_INVALID AP_SEC_BAD_USERID_REVOKED AP_SEC_BAD_USERID_INVALID AP_SEC_BAD_USERID_M
APPC Conversation Verbs MC_RECEIVE_AND_POST and RECEIVE_AND_POST 4.10.7 State When Issued The TP can issue [MC_]RECEIVE_AND_POST when the conversation is in Receive, Send, or Send_Pending state. Issuing the Verb in Send State Issuing the [MC_]RECEIVE_AND_POST verb 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.
APPC Conversation Verbs MC_RECEIVE_AND_POST and RECEIVE_AND_POST primary_rc New state AP_CONV_FAILURE_RETRY AP_CONV_FAILURE_NO_RETRY AP_DEALLOC_ABEND AP_DEALLOC_ABEND_PROG AP_DEALLOC_ABEND_SVC AP_DEALLOC_ABEND_TIMER AP_DEALLOC_NORMAL Reset AP_PROG_ERROR_PURGING AP_PROG_ERROR_NO_TRUNC AP_SVC_ERROR_PURGING AP_SVC_ERROR_NO_TRUNC AP_PROG_ERROR_TRUNC AP_SVC_ERROR_TRUNC Receive AP_CANCELLED The conversation returns to the state (Send or Receive) in which the [MC_]RECEIVE_AND_POST verb was issued.
APPC Conversation Verbs MC_RECEIVE_AND_POST and RECEIVE_AND_POST vcb Pointer to the VCB supplied by the application, including the returned parameters set by SNAplus2. tp_id The 8-byte TP identifier of the TP in which the verb was issued. conv_id The conversation identifier of the conversation in which the verb was issued. The callback routine need not use all of these parameters.
APPC Conversation Verbs MC_RECEIVE_AND_WAIT and RECEIVE_AND_WAIT • • GET_TYPE • [MC_]GET_ATTRIBUTES • [MC_]TEST_RTS Prematurely cancel the [MC_]RECEIVE_AND_POST verb by issuing one of the following verbs: • 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 • SEND_ERROR • TP_ENDED 3. Checks that the callback routine (supplied as a parameter on this verb) has been called by APPC.
APPC Conversation Verbs MC_RECEIVE_AND_WAIT and RECEIVE_AND_WAIT • [MC_]SEND_ERROR • [MC_]TEST_RTS • TP_ENDED 4.11.
APPC Conversation Verbs MC_RECEIVE_AND_WAIT and RECEIVE_AND_WAIT 4.11.
APPC Conversation Verbs MC_RECEIVE_AND_WAIT and RECEIVE_AND_WAIT AP_M_RECEIVE_AND_WAIT For the MC_RECEIVE_AND_WAIT verb. AP_B_RECEIVE_AND_WAIT For the RECEIVE_AND_WAIT verb. opext Possible values are: AP_MAPPED_CONVERSATION For the MC_RECEIVE_AND_WAIT verb. AP_BASIC_CONVERSATION For the RECEIVE_AND_WAIT verb.
APPC Conversation Verbs MC_RECEIVE_AND_WAIT and RECEIVE_AND_WAIT Data is received in logical-record format. The data received can be any of the following: • A complete logical record • A max_len-byte portion of a logical record • The end of a logical record max_len Maximum number of bytes of data the local TP can receive. The range for this value is 0–65,535. This value must not exceed the length of the buffer to contain the received data.
APPC Conversation Verbs MC_RECEIVE_AND_WAIT and RECEIVE_AND_WAIT AP_DATA This value can be returned by the basic-conversation RECEIVE_AND_WAIT verb if the fill parameter is set to AP_BUFFER; it is not applicable to MC_RECEIVE_AND_WAIT. The local TP received data until max_len or end of data was reached. AP_DATA_COMPLETE For the mapped-conversation MC_RECEIVE_AND_WAIT verb, this value indicates that the local TP has received a complete data record or the last part of a data record.
APPC Conversation Verbs MC_RECEIVE_AND_WAIT and RECEIVE_AND_WAIT This is a combination of AP_DATA_COMPLETE and AP_CONFIRM_SEND. The partner TP sent a complete data record (or the end of a data record) and then issued the [MC_]PREPARE_TO_RECEIVE verb with ptr_type set to AP_SYNC_LEVEL, or issued the [MC_]SEND_DATA verb with a send type of P_TO_R_SYNC_LEVEL. The conversation’s synchronization level, established by the [MC_]ALLOCATE verb, is AP_CONFIRM_SYNC_LEVEL.
APPC Conversation Verbs MC_RECEIVE_AND_WAIT and RECEIVE_AND_WAIT rts_rcvd Request-to-send-received indicator. This parameter applies only in a half-duplex conversation; it is not used in a full-duplex conversation. Possible values are: AP_YES The partner TP has issued the [MC_]REQUEST_TO_SEND verb, which requests that the local TP change the conversation to Receive state. AP_NO The partner TP has not issued the [MC_]REQUEST_TO_SEND verb.
APPC Conversation Verbs MC_RECEIVE_AND_WAIT and RECEIVE_AND_WAIT primary_rc AP_PARAMETER_CHECK secondary_rc Possible values are: AP_BAD_CONV_ID The value of conv_id did not match a conversation identifier assigned by APPC. AP_BAD_RETURN_STATUS_WITH_DATA The rtn_status parameter was set to a value that was not valid. AP_BAD_TP_ID The value of tp_id did not match a TP identifier assigned by APPC. UNIX AP_INVALID_FORMAT The reserved field format was set to a nonzero value.
APPC Conversation Verbs MC_RECEIVE_AND_WAIT and RECEIVE_AND_WAIT AP_ALLOCATION_ERROR secondary_rc 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_SEC_BAD_PROTOCOL_VIOLATION AP_SEC_BAD_PASSWORD_EXPIRED AP_SEC_BAD_PASSWORD_INVALID AP_SEC_BAD_USERID_REVOKED AP_SEC_BAD_USERID_INVALI
APPC Conversation Verbs MC_RECEIVE_AND_WAIT and RECEIVE_AND_WAIT The following primary return codes are returned by the RECEIVE_AND_WAIT verb: primary_rc AP_DEALLOC_ABEND_PROG AP_DEALLOC_ABEND_SVC AP_DEALLOC_ABEND_TIMER AP_SVC_ERROR_NO_TRUNC AP_SVC_ERROR_PURGING AP_SVC_ERROR_TRUNC APPC does not return secondary return codes with these primary return codes. 4.11.7 State When Issued The TP can issue the [MC_]RECEIVE_AND_WAIT verb when the conversation is in Receive, Send, or Send_Pending state.
APPC Conversation Verbs MC_RECEIVE_AND_WAIT and RECEIVE_AND_WAIT what_rcvd parameter New state AP_SEND Send AP_DATA_SEND AP_DATA_COMPLETE_SEND Send_Pending primary_rc New state AP_PARAMETER_CHECK AP_STATE_CHECK AP_CONVERSATION_TYPE_MIXED AP_INVALID_VERB AP_INVALID_VERB_SEGMENT AP_STACK_TOO_SMALL AP_TP_BUSY AP_UNEXPECTED_DOS_ERROR No change AP_CONV_FAILURE_RETRY AP_CONV_FAILURE_NO_RETRY Reset AP_DEALLOC_ABEND AP_DEALLOC_ABEND_PROG AP_DEALLOC_ABEND_SVC AP_DEALLOC_ABEND_TIMER Reset AP_DEALLOC_NO
APPC Conversation Verbs MC_RECEIVE_IMMEDIATE and RECEIVE_IMMEDIATE 4.12 MC_RECEIVE_IMMEDIATE and RECEIVE_IMMEDIATE The MC_RECEIVE_IMMEDIATE or RECEIVE_IMMEDIATE verb receives any data and/or status information which is currently available from the partner TP. If none is currently available, the local TP returns immediately and does not wait. WINDOWS Although this verb does not wait to receive information, it is still possible that the Windows APPC library will yield to allow other processing to continue.
APPC Conversation Verbs MC_RECEIVE_IMMEDIATE and RECEIVE_IMMEDIATE unsigned char expd_rcvd; AP_UINT16 max_len; AP_UINT16 dlen; unsigned char *dptr; unsigned char reserv5[5]; } RECEIVE_IMMEDIATE; 4.12.
APPC Conversation Verbs MC_RECEIVE_IMMEDIATE and RECEIVE_IMMEDIATE 4.12.5 Supplied Parameters The TP supplies the following parameters to APPC: opcode Possible values are: AP_M_RECEIVE_IMMEDIATE For the MC_RECEIVE_IMMEDIATE verb. AP_B_RECEIVE_IMMEDIATE For the RECEIVE_IMMEDIATE verb. opext Possible values are: AP_MAPPED_CONVERSATION For the MC_RECEIVE_IMMEDIATE verb. AP_BASIC_CONVERSATION For the RECEIVE_IMMEDIATE verb.
APPC Conversation Verbs MC_RECEIVE_IMMEDIATE and RECEIVE_IMMEDIATE AP_BUFFER The local TP receives data until the number of bytes specified by the max_len parameter is reached or until end of data. Data is received without regard for the logical-record format. AP_LL Data is received in logical-record format.
APPC Conversation Verbs MC_RECEIVE_IMMEDIATE and RECEIVE_IMMEDIATE The partner TP has issued the [MC_]CONFIRM verb. AP_DATA This value can be returned by the basic-conversation RECEIVE_IMMEDIATE verb if the fill parameter is set to AP_BUFFER; it is not applicable to MC_RECEIVE_IMMEDIATE. The local TP received data until max_len or end of data was reached.
APPC Conversation Verbs MC_RECEIVE_IMMEDIATE and RECEIVE_IMMEDIATE This is a combination of AP_DATA_COMPLETE and AP_CONFIRM_SEND. The partner TP sent a complete data record (or the end of a data record) and then issued the [MC_]PREPARE_TO_RECEIVE verb with ptr_type set to AP_SYNC_LEVEL, or issued the [MC_]SEND_DATA verb with a send type of P_TO_R_SYNC_LEVEL. The conversation’s synchronization level, established by the [MC_]ALLOCATE verb, is AP_CONFIRM_SYNC_LEVEL.
APPC Conversation Verbs MC_RECEIVE_IMMEDIATE and RECEIVE_IMMEDIATE rts_rcvd Request-to-send-received indicator. This parameter applies only in a half-duplex conversation; it is not used in a full-duplex conversation. Possible values are: AP_YES The partner TP has issued the [MC_]REQUEST_TO_SEND verb, which requests that the local TP change the conversation to Receive state. AP_NO The partner TP has not issued the [MC_]REQUEST_TO_SEND verb.
APPC Conversation Verbs MC_RECEIVE_IMMEDIATE and RECEIVE_IMMEDIATE primary_rc AP_PARAMETER_CHECK secondary_rc Possible values are: AP_BAD_CONV_ID The value of conv_id did not match a conversation identifier assigned by APPC. AP_BAD_RETURN_STATUS_WITH_DATA The rtn_status parameter was set to a value that was not valid. AP_BAD_TP_ID The value of tp_id did not match a TP identifier assigned by APPC. UNIX AP_INVALID_FORMAT The reserved field format was set to a nonzero value.
APPC Conversation Verbs MC_RECEIVE_IMMEDIATE and RECEIVE_IMMEDIATE primary_rc AP_ALLOCATION_ERROR secondary_rc 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_SEC_BAD_PROTOCOL_VIOLATION AP_SEC_BAD_PASSWORD_EXPIRED AP_SEC_BAD_PASSWORD_INVALID AP_SEC_BAD_USERID_REVOKED AP_SEC_BAD_
APPC Conversation Verbs MC_RECEIVE_IMMEDIATE and RECEIVE_IMMEDIATE APPC does not return a secondary return code with this primary return code. The following primary return codes are returned by the RECEIVE_IMMEDIATE verb: primary_rc AP_DEALLOC_ABEND_PROG AP_DEALLOC_ABEND_SVC AP_DEALLOC_ABEND_TIMER AP_SVC_ERROR_NO_TRUNC AP_SVC_ERROR_PURGING AP_SVC_ERROR_TRUNC APPC does not return secondary return codes with these primary return codes. 4.12.
APPC Conversation Verbs MC_RECEIVE_EXPEDITED_DATA and RECEIVE_EXPEDITED_DATA primary_rc New state AP_DEALLOC_ABEND AP_DEALLOC_ABEND_PROG AP_DEALLOC_ABEND_SVC AP_DEALLOC_ABEND_TIMER AP_DEALLOC_NORMAL Reset (half-duplex conversation) or Send_Only (full-duplex conversation) AP_PROG_ERROR_PURGING AP_PROG_ERROR_NO_TRUNC AP_SVC_ERROR_PURGING AP_SVC_ERROR_NO_TRUNC AP_PROG_ERROR_TRUNC AP_SVC_ERROR_TRUNC Receive (half-duplex conversation) or no change (full-duplex conversation) 4.12.
APPC Conversation Verbs MC_RECEIVE_EXPEDITED_DATA and RECEIVE_EXPEDITED_DATA 4.13.
APPC Conversation Verbs MC_RECEIVE_EXPEDITED_DATA and RECEIVE_EXPEDITED_DATA The value of this parameter was returned by the TP_STARTED verb in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP. conv_id Conversation identifier. The value of this parameter was returned by the [MC_]ALLOCATE verb in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP. rtn_ctl Indicates when the verb should return control to the TP if no expedited data is available at the time it is issued.
APPC Conversation Verbs MC_RECEIVE_EXPEDITED_DATA and RECEIVE_EXPEDITED_DATA Number of bytes of data received (the data is stored in the buffer specified by the dptr parameter). A length of 0 (zero) indicates that no data was received. Any data received is unformatted, and does not contain a two-byte length field (LL).
APPC Conversation Verbs MC_RECEIVE_EXPEDITED_DATA and RECEIVE_EXPEDITED_DATA AP_PARAMETER_CHECK secondary_rc Possible values are: AP_BAD_CONV_ID The value of conv_id did not match a conversation identifier assigned by APPC. AP_BAD_TP_ID The value of tp_id did not match a TP identifier assigned by APPC. AP_INVALID_FORMAT The reserved field format was set to a nonzero value. AP_EXPD_BAD_RETURN_CONTROL The rtn_ctl parameter was set to a value that was not valid.
APPC Conversation Verbs MC_RECEIVE_EXPEDITED_DATA and RECEIVE_EXPEDITED_DATA secondary_rc AP_BO_NO_RESYNC AP_BO_RESYNC primary_rc AP_COMM_SUBSYSTEM_ABENDED AP_UNEXPECTED_SYSTEM_ERROR AP_CONV_FAILURE_NO_RETRY AP_CONV_FAILURE_RETRY AP_CONVERSATION_TYPE_MIXED AP_PROG_ERROR_NO_TRUNC AP_PROG_ERROR_PURGING AP_PROG_ERROR_TRUNC AP_INVALID_VERB AP_TP_BUSY APPC does not return secondary return codes with these primary return codes.
APPC Conversation Verbs MC_REQUEST_TO_SEND and REQUEST_TO_SEND primary_rc New state AP_CONV_FAILURE_RETRY AP_CONV_FAILURE_NO_RETRY AP_CONVERSATION_ENDED Reset AP_DEALLOC_ABEND AP_DEALLOC_ABEND_PROG AP_DEALLOC_ABEND_SVC AP_DEALLOC_ABEND_TIMER Reset AP_DEALLOC_NORMAL Reset 4.14 MC_REQUEST_TO_SEND and REQUEST_TO_SEND The MC_REQUEST_TO_SEND or REQUEST_TO_SEND verb notifies the partner TP that the local TP wants to send data.
APPC Conversation Verbs MC_REQUEST_TO_SEND and REQUEST_TO_SEND The definition of the VCB structure for the MC_REQUEST_TO_SEND verb is as follows: typedef struct mc_request_to_send { AP_UINT16 opcode; unsigned char opext; unsigned char format; AP_UINT16 primary_rc; AP_UINT32 secondary_rc; unsigned char tp_id[8]; AP_UINT32 conv_id; } MC_REQUEST_TO_SEND; /* Reserved */ 4.14.
APPC Conversation Verbs MC_REQUEST_TO_SEND and REQUEST_TO_SEND } REQUEST_TO_SEND; 4.14.7 Supplied Parameters The TP supplies the following parameters to APPC: opcode Possible values are: AP_M_REQUEST_TO_SEND For the MC_REQUEST_TO_SEND verb. AP_B_REQUEST_TO_SEND For the REQUEST_TO_SEND verb. opext Possible values are: AP_MAPPED_CONVERSATION For the MC_REQUEST_TO_SEND verb. AP_BASIC_CONVERSATION For the REQUEST_TO_SEND verb.
APPC Conversation Verbs MC_REQUEST_TO_SEND and REQUEST_TO_SEND Conversation Deallocated If the partner TP has deallocated the conversation, APPC returns the following value: primary_rc AP_CONVERSATION_ENDED This verb was issued as a non-blocking verb and was queued behind an earlier verb. The partner TP issued the [MC_]DEALLOCATE verb as for AP_DEALLOC_NORMAL above, and the first verb in the queue returned with primary_rc set to AP_DEALLOC_NORMAL, indicating the end of the conversation.
APPC Conversation Verbs MC_REQUEST_TO_SEND and REQUEST_TO_SEND primary_rc AP_COMM_SUBSYSTEM_ABENDED AP_CONVERSATION_TYPE_MIXED AP_INVALID_VERB AP_TP_BUSY AP_UNEXPECTED_SYSTEM_ERROR WINDOWS AP_COMM_SUBSYSTEM_NOT_LOADED AP_STACK_TOO_SMALL AP_INVALID_VERB_SEGMENT APPC does not return secondary return codes with these primary return codes. 4.14.9 State When Issued The conversation can be in any of the following states when the TP issues this verb: • Receive • Confirm • Pending_Post 4.14.
APPC Conversation Verbs MC_SEND_CONVERSATION and SEND_CONVERSATION 4.15 MC_SEND_CONVERSATION and SEND_CONVERSATION The MC_SEND_CONVERSATION or SEND_CONVERSATION verb establishes a conversation with the partner TP, sends a single data record on this conversation, and deallocates the conversation. It is equivalent to issuing the three verbs [MC_]ALLOCATE, [MC_]SEND_DATA, [MC_]DEALLOCATE(FLUSH). 4.15.
APPC Conversation Verbs MC_SEND_CONVERSATION and SEND_CONVERSATION unsigned char rtn_ctl; unsigned char reserv4; AP_UINT32 conv_group_id; AP_UINT32 sense_data; unsigned char plu_alias[8]; unsigned char mode_name[8]; unsigned char tp_name[64]; unsigned char security; unsigned char reserv5[11]; unsigned char pwd[10]; unsigned char user_id[10]; AP_UINT16 pip_dlen; unsigned char *pip_dptr; unsigned char reserv5a; unsigned char fqplu_name[17]; unsigned char reserv6[8]; AP_UINT16 dlen; unsigned char *dptr; } SEN
APPC Conversation Verbs MC_SEND_CONVERSATION and SEND_CONVERSATION typedef struct send_conversation { unsigned short opcode; unsigned char opext; unsigned char reserv2; unsigned short primary_rc; unsigned long secondary_rc; unsigned char tp_id[8]; unsigned char reserv3[8]; unsigned char rtn_ctl; unsigned char reserv4; unsigned long conv_group_id; unsigned long sense_data; unsigned char plu_alias[8]; unsigned char mode_name[8]; unsigned char tp_name[64]; unsigned char security; unsigned char reserv5[11]; un
APPC Conversation Verbs MC_SEND_CONVERSATION and SEND_CONVERSATION Identifier for the local TP. The value of this parameter was returned by the TP_STARTED verb in the invoking TP or by RECEIVE_ALLOCATE in the invoked TP. rtn_ctl Specifies when the local LU acting on a session request from the local TP is to return control to the local TP. For information about sessions, see Section 2.10, LU-to-LU Sessions.
APPC Conversation Verbs MC_SEND_CONVERSATION and SEND_CONVERSATION This parameter is an 8-byte ASCII character string, padded on the right with ASCII blanks (0x20) if the alias is shorter than eight characters. It can consist of any of the following characters: • Uppercase letters • Numerals 0–9 • Blanks • Special characters $, #, %, and @ The first character of this string cannot be a blank.
APPC Conversation Verbs MC_SEND_CONVERSATION and SEND_CONVERSATION The invoked TP does not use conversation security. (If you use this value, the invoked TP must be configured not to use conversation security.) AP_PGM The invoked TP uses conversation security and thus requires a user ID and password. Supply this information through the user_id and pwd parameters. AP_PGM_STRONG The invoked TP uses conversation security and thus requires a user ID and password.
APPC Conversation Verbs MC_SEND_CONVERSATION and SEND_CONVERSATION This parameter is required only if the security parameter is set to AP_PGM or AP_PGM_STRONG; otherwise it is reserved. The pwd and user_id parameters must match a user ID/password pair configured on the computer where the invoked TP is located. This parameter is a 10-byte EBCDIC character string; it is case-sensitive. The user_id parameter can consist of characters from the type-AE EBCDIC character set.
APPC Conversation Verbs MC_SEND_CONVERSATION and SEND_CONVERSATION Successful Execution If the verb executes successfully, APPC returns the following parameters: primary_rc AP_OK conv_group_id The conversation group identifier of the session used by the conversation.
APPC Conversation Verbs MC_SEND_CONVERSATION and SEND_CONVERSATION Session Not Available Depending on the value specified for rtn_ctl, APPC may return the following parameter: primary_rc AP_UNSUCCESSFUL 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.
APPC Conversation Verbs MC_SEND_DATA and SEND_DATA 4.15.7 State When Issued The conversation state is Reset when the TP issues this verb. It can be issued during an existing conversation that is in any state, because it always implies the start of a new conversation that is in Reset state. 4.15.8 State Change The conversation state does not change for this verb. 4.16 MC_SEND_DATA and SEND_DATA The MC_SEND_DATA or SEND_DATA verb puts data in the local LU’s send buffer for transmission to the partner TP.
APPC Conversation Verbs MC_SEND_DATA and SEND_DATA typedef struct send_data { AP_UINT16 opcode; unsigned char opext; unsigned char format; AP_UINT16 primary_rc; AP_UINT32 secondary_rc; unsigned char tp_id[8]; AP_UINT32 conv_id; unsigned char rts_rcvd; unsigned char expd_rcvd; AP_UINT16 dlen; unsigned char *dptr; unsigned char type; unsigned char reserv4; } SEND_DATA; /* Reserved 4.16.
APPC Conversation Verbs MC_SEND_DATA and SEND_DATA unsigned char } SEND_DATA; reserv4; 4.16.5 Supplied Parameters The TP supplies the following parameters to APPC: opcode Possible values are: AP_M_SEND_DATA For the MC_SEND_DATA verb. AP_B_SEND_DATA For the SEND_DATA verb. opext Possible values are: AP_MAPPED_CONVERSATION For the MC_SEND_DATA verb. AP_BASIC_CONVERSATION For the SEND_DATA verb.
APPC Conversation Verbs MC_SEND_DATA and SEND_DATA Number of bytes of data to be put in the local LU’s send buffer. The range for this value is 0–65,535. dptr Address of the buffer containing the data to be put in the local LU’s send buffer. 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. type Specifies whether to perform the function of another APPC verb in addition to [MC_]SEND_DATA.
APPC Conversation Verbs MC_SEND_DATA and SEND_DATA [MC_]PREPARE_TO_RECEIVE. For the basic-conversation SEND_DATA verb, the data sent on this verb must be a complete logical record or the end of a logical record; this value cannot be used if an incomplete logical record is being sent. AP_SEND_DATA_DEALLOC_FLUSH Perform the function of the [MC_]DEALLOCATE verb with dealloc_type set to AP_FLUSH. This is equivalent to issuing [MC_]SEND_DATA followed by [MC_]DEALLOCATE.
APPC Conversation Verbs MC_SEND_DATA and SEND_DATA PS Header data. This data format is used only by Syncpoint TPs; do not set it unless the synchronization level of the conversation is AP_SYNCPT. The Syncpoint Manager is responsible for converting Syncpoint commands into the appropriate PS Headers. 4.16.6 Returned Parameters After the verb executes, APPC returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was not successful.
APPC Conversation Verbs MC_SEND_DATA and SEND_DATA Possible values are: AP_BAD_CONV_ID The value of conv_id did not match a conversation identifier assigned by APPC. AP_BAD_LL This return code applies only to the SEND_DATA verb. The logical record length field of a logical record contained a value that was not valid—0x0000, 0x0001, 0x8000, or 0x8001. For more information, see Section 2.11.1, Logical Records. AP_BAD_TP_ID The value of tp_id did not match a TP identifier assigned by APPC.
APPC Conversation Verbs MC_SEND_DATA and SEND_DATA (Returned for basic-conversation SEND_DATA verb only) The local TP issued the SEND_DATA verb to send an incomplete logical record, and used a type parameter other than AP_NONE or AP_SEND_DATA_DEALLOC_ABEND. Other Conditions If the verb does not execute because other conditions exist, APPC returns primary return codes (and, if applicable, secondary return codes). For information about these return codes, see Appendix B, Common Return Codes.
APPC Conversation Verbs MC_SEND_DATA and SEND_DATA AP_INVALID_VERB_SEGMENT APPC does not return secondary return codes with these primary return codes. The following primary return code is returned by the MC_SEND_DATA verb: primary_rc AP_DEALLOC_ABEND APPC does not return a secondary return code with this primary return code.
APPC Conversation Verbs MC_SEND_ERROR and SEND_ERROR 4.16.9 Waiting for Partner TP The [MC_]SEND_DATA verb may wait indefinitely because the partner TP has not issued a receive verb. This is because the send buffer may fill up and APPC cannot transmit its contents to the partner LU because the partner LU has no buffers to receive the data. 4.16.
APPC Conversation Verbs MC_SEND_ERROR and SEND_ERROR 4.17.
APPC Conversation Verbs MC_SEND_ERROR and SEND_ERROR unsigned char unsigned char unsigned short unsigned char far } SEND_ERROR; err_dir; reserv3; log_dlen; *log_dptr; 4.17.5 Supplied Parameters The TP supplies the following parameters to APPC: opcode Possible values are: AP_M_SEND_ERROR For the MC_SEND_ERROR verb. AP_B_SEND_ERROR For the SEND_ERROR verb. opext Possible values are: AP_MAPPED_CONVERSATION For the MC_SEND_ERROR verb. AP_BASIC_CONVERSATION For the SEND_ERROR verb.
APPC Conversation Verbs MC_SEND_ERROR and SEND_ERROR This parameter is used only by the basic-conversation SEND_ERROR verb. Possible values are: AP_PROG The error is to be reported to an application program that does not use Syncpoint.
APPC Conversation Verbs MC_SEND_ERROR and SEND_ERROR The local TP detected an error in the data it received from the remote TP. AP_SEND_DIR_ERROR The local TP detected an error in its own data (for example, it could not read data from disk) or in its own processing. log_dlen Number of bytes of data to be sent to the error log file. This parameter is used only by the SEND_ERROR verb. The range for this value is 0–32,767. A length of 0 (zero) indicates that there is no error log data.
APPC Conversation Verbs MC_SEND_ERROR and SEND_ERROR The partner TP has sent expedited data that the local TP has not yet received. To receive this data, the local TP can use the [MC_]RECEIVE_EXPEDITED_DATA verb. This indicator can be set on a number of APPC verbs. It continues to be set on subsequent verbs until the local TP issues the [MC_]RECEIVE_EXPEDITED_DATA verb to receive the data. AP_NO There is no expedited data waiting to be received.
APPC Conversation Verbs MC_SEND_ERROR and SEND_ERROR Other Conditions If the verb does not execute because other conditions exist, APPC returns primary return codes (and, if applicable, secondary return codes). For information about these return codes, see Appendix B, Common Return Codes. 4.17.6.2.3.
APPC Conversation Verbs MC_SEND_ERROR and SEND_ERROR secondary_rc AP_BO_NO_RESYNC AP_BO_RESYNC primary_rc AP_PROG_ERROR_PURGING APPC does not return a secondary return code with this primary return code. The following return code can be generated only if the MC_SEND_ERROR verb is issued in Send state: primary_rc AP_DEALLOC_ABEND APPC does not return a secondary return code with this primary return code.
APPC Conversation Verbs MC_SEND_ERROR and SEND_ERROR primary_rc New state AP_DEALLOC_ABEND AP_DEALLOC_ABEND_PROG AP_DEALLOC_ABEND_SVC AP_DEALLOC_ABEND_TIMER AP_DEALLOC_NORMAL Reset AP_PROG_ERROR_PURGING AP_SVC_ERROR_PURGING Receive (half-duplex conversation), Send_Receive (full-duplex conversation, verb issued in Send_Receive state), or Reset (full-duplex conversation, verb issued in Send_Only state) 4.17.
APPC Conversation Verbs MC_SEND_EXPEDITED_DATA and SEND_EXPEDITED_DATA AP_SEC_BAD_PASSWORD_MISSING AP_SEC_BAD_UID_NOT_DEFD_TO_GRP AP_SEC_BAD_UNAUTHRZD_AT_RLU AP_SEC_BAD_UNAUTHRZD_FROM_LLU AP_SEC_BAD_UNAUTHRZD_TO_TP AP_SEC_BAD_INSTALL_EXIT_FAILED AP_SEC_BAD_PROCESSING_FAILURE primary_rc AP_DEALLOC_ABEND AP_DEALLOC_ABEND_PROG AP_DEALLOC_ABEND_SVC AP_DEALLOC_ABEND_TIMER 4.
APPC Conversation Verbs MC_SEND_EXPEDITED_DATA and SEND_EXPEDITED_DATA unsigned char tp_id[8]; AP_UINT32 conv_id; unsigned char rts_rcvd; unsigned char expd_rcvd; AP_UINT16 dlen; unsigned char *dptr; unsigned char reserv4[2]; } SEND_EXPEDITED_DATA; 4.18.3 Supplied Parameters The TP supplies the following parameters to APPC: opcode Possible values are: AP_M_SEND_EXPEDITED_DATA For the MC_SEND_EXPEDITED_DATA verb. AP_B_SEND_EXPEDITED_DATA For the SEND_EXPEDITED_DATA verb.
APPC Conversation Verbs MC_SEND_EXPEDITED_DATA and SEND_EXPEDITED_DATA Address of the buffer containing the data to be put in the local LU’s send buffer. 4.18.4 Returned Parameters After the verb executes, APPC returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was not successful. Successful Execution If the verb executes successfully, APPC returns the following parameters: primary_rc AP_OK rts_rcvd Request-to-send-received indicator.
APPC Conversation Verbs MC_SEND_EXPEDITED_DATA and SEND_EXPEDITED_DATA primary_rc AP_CONVERSATION_ENDED This verb was issued as a non-blocking verb and was queued behind an earlier verb. The partner TP issued the [MC_]DEALLOCATE verb as for AP_DEALLOC_NORMAL above, and the first verb in the queue returned with primary_rc set to AP_DEALLOC_NORMAL, indicating the end of the conversation.
APPC Conversation Verbs MC_SEND_EXPEDITED_DATA and SEND_EXPEDITED_DATA 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 primary_rc AP_BACKED_OUT secondary_rc AP_BO_NO_RESYNC AP_BO_RESYNC primary_rc AP_COMM_SUBSYSTEM_ABENDED AP_CONV_FAILURE_NO_RETRY AP_CONV_FAILURE_RETRY AP_CONVERSATION_TYPE_MIXED AP_DUPLEX_TYPE_MIXED AP_PROG_ERROR_PURGING AP_INVALID_VERB AP_TP_BUSY AP_UNEXPECTED_SYSTEM_
APPC Conversation Verbs MC_TEST_RTS and TEST_RTS primary_rc New state AP_ALLOCATION_ERROR Reset AP_CONV_FAILURE_RETRY AP_CONV_FAILURE_NO_RETRY AP_CONVERSATION_ENDED Reset AP_DEALLOC_ABEND AP_DEALLOC_ABEND_PROG AP_DEALLOC_ABEND_SVC AP_DEALLOC_ABEND_TIMER Reset 4.18.7 Waiting for Partner TP In the same way as for [MC_]SEND_DATA, the [MC_]SEND_EXPEDITED_DATA verb may wait indefinitely because the partner TP has not issued an [MC_]RECEIVE_EXPEDITED_DATA verb.
APPC Conversation Verbs MC_TEST_RTS and TEST_RTS typedef struct mc_test_rts { AP_UINT16 opcode; unsigned char opext; unsigned char format; AP_UINT16 primary_rc; AP_UINT32 secondary_rc; unsigned char tp_id[8]; AP_UINT32 conv_id; unsigned char reserv3; } MC_TEST_RTS; /* Reserved */ 4.19.
APPC Conversation Verbs MC_TEST_RTS and TEST_RTS unsigned char unsigned long unsigned char } TEST_RTS; tp_id[8]; conv_id; reserv3; 4.19.5 Supplied Parameters The TP supplies the following parameters to APPC: opcode Possible values are: AP_M_TEST_RTS For the MC_TEST_RTS verb. AP_B_TEST_RTS For the TEST_RTS verb. opext Possible values are: AP_MAPPED_CONVERSATION For the MC_TEST_RTS verb. AP_BASIC_CONVERSATION For the TEST_RTS verb. tp_id Identifier for the local TP.
APPC Conversation Verbs MC_TEST_RTS and TEST_RTS AP_UNSUCCESSFUL REQUEST_TO_SEND notification has not been received. Unsuccessful Execution If the verb does not execute successfully, APPC returns a primary return code parameter to indicate the type of error and a secondary return code parameter to provide specific details about the reason for unsuccessful execution.
APPC Conversation Verbs MC_TEST_RTS_AND_POST and TEST_RTS_AND_POST APPC does not return secondary return codes with these primary return codes. 4.19.7 State When Issued The conversation can be in any state except Reset when the TP issues this verb. 4.19.8 State Change The conversation state does not change for this verb. 4.
APPC Conversation Verbs MC_TEST_RTS_AND_POST and TEST_RTS_AND_POST } MC_TEST_RTS_AND_POST; 4.20.2 VCB Structure: TEST_RTS_AND_POST The definition of the VCB structure for the TEST_RTS_AND_POST verb is as follows: typedef struct test_rts_and_post { AP_UINT16 opcode; unsigned char opext; unsigned char format; AP_UINT16 primary_rc; AP_UINT32 secondary_rc; unsigned char tp_id[8]; AP_UINT32 conv_id; void (*callback)(); unsigned char reserv3; } TEST_RTS_AND_POST; /* Reserved */ 4.20.
APPC Conversation Verbs MC_TEST_RTS_AND_POST and TEST_RTS_AND_POST 4.20.5 Supplied Parameters The TP supplies the following parameters to APPC: opcode Possible values are: AP_M_TEST_RTS_AND_POST For the MC_TEST_RTS_AND_POST verb. AP_B_TEST_RTS_AND_POST For the TEST_RTS_AND_POST verb. opext Possible values are: AP_MAPPED_CONVERSATION For the MC_TEST_RTS_AND_POST verb. AP_BASIC_CONVERSATION For the TEST_RTS_AND_POST verb. tp_id Identifier for the local TP.
APPC Conversation Verbs MC_TEST_RTS_AND_POST and TEST_RTS_AND_POST Note When this verb is issued, it returns immediately with a primary_rc which indicates whether or not the verb was issued successfully. The only returned parameters which are valid at this stage are primary_rc and secondary_rc (if the primary_rc is not AP_OK). The possible primary_rc and secondary_rc values are as described later in this section.
APPC Conversation Verbs MC_TEST_RTS_AND_POST and TEST_RTS_AND_POST State Check No state check errors occur for this verb. Verb Canceled This return code cannot be returned as the initial return code, but only as the subsequent return code if the initial return code is AP_OK.
APPC Conversation Verbs MC_TEST_RTS_AND_POST and TEST_RTS_AND_POST • Callback routine • Processing while the verb is pending • How the TP uses the verb • Avoiding indefinite waits Callback Routine UNIX The application supplies a pointer to a callback routine as one of the parameters to the VCB. This section describes how SNAplus2 uses this routine, and the functions that it must perform.
APPC Conversation Verbs MC_TEST_RTS_AND_POST and TEST_RTS_AND_POST • Only one [MC_]TEST_RTS_AND_POST verb per conversation can be active at any time. How the TP Uses the Verb To use the [MC_]TEST_RTS_AND_POST verb, the local TP performs the following steps: Using [MC_]TEST_RTS_AND_POST 1. Issues the [MC_]TEST_RTS_AND_POST verb. 2. Checks the value of the primary return code primary_rc: • • If the primary return code is AP_OK, the verb is waiting for a REQUEST_TO_SEND notification from the partner TP.
TP Server Verbs REGISTER_TP_SERVER 5 TP Server Verbs UNIX This chapter contains a description of each APPC TP server verb. The following information is provided for each verb: • Definition of the verb. • Structure defining the verb control block (VCB) used by the verb. The structure is defined in the TP Server header file /usr/include/sna/tpsrv_c.h. (Parameters beginning with rsrvd are reserved.) • Parameters (VCB fields) supplied to and returned by APPC.
TP Server Verbs REGISTER_TP_SERVER 5.1.
TP Server Verbs REGISTER_TP_SERVER 5.1.3 Returned Parameters After the verb executes, APPC returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was not successful. Successful Execution If the verb executes successfully, APPC returns the following parameter: primary_rc AP_OK tps_id A unique identifier for this TP server. After an application registers itself as a TP server, the value of the tps_id parameter is valid for that process only.
TP Server Verbs UNREGISTER_TP_SERVER typedef void (*AP_NOTIFY_CB) ( unsigned char unsigned char AP_CORR ); reason, attach_id[8], app_corr typedef union ap_corr { void * AP_UINT32 AP_INT32 } AP_CORR; corr_p; corr_l; corr_i; SNAplus2 calls the routine with the following parameters: reason Type of notification. Possible values are: AP_ATTACH An Attach has arrived for a TP registered by this TP server.
TP Server Verbs UNREGISTER_TP_SERVER typedef struct unregister_tp_server { AP_UINT16 opcode; unsigned char rsrvd1; unsigned char rsrvd2; AP_UINT16 primary_rc; AP_UINT32 secondary_rc; AP_UINT32 tps_id; } UNREGISTER_TP_SERVER; /* Reserved /* Reserved */ */ 5.2.2 Supplied Parameters The TP supplies the following parameters to APPC: opcode AP_UNREGISTER_TP_SERVER tps_id The ID of the TP server to be unregistered, as returned on a previous REGISTER_TP_SERVER verb. 5.2.
TP Server Verbs REGISTER_TP 5.3 REGISTER_TP The REGISTER_TP verb is used to tell Service Manager the name of a TP whose attaches are to be handled by the TP server. It can also be used to change the TP type or receive allocate timeout for a TP that has already been registered. 5.3.
TP Server Verbs REGISTER_TP The local LU alias. Specify this name in ASCII padded with ASCII spaces, if necessary, to a length of eight characters. Specify a value of eight ASCII spaces (0x20) for an LU for which all attaches will be handled. fqplu_name The fully qualified name of the partner LU.
TP Server Verbs REGISTER_TP • The rcv_alloc_timeout parameter, the type parameter, or both of these parameters can be changed from the original REGISTER_TP verb, but all other supplied parameters must match the value used on the original REGISTER_TP verb. AP_NO This verb is being used to register a new TP. app_corr An application provided correlator passed into the attach notification callback. For more information, see Section 5.1.4, Usage Notes. 5.3.
TP Server Verbs UNREGISTER_TP primary_rc AP_UNEXPECTED_SYSTEM_ERROR 5.4 UNREGISTER_TP The UNREGISTER_TP verb is used to notify the Service Manager that the application does not want to receive Attach notifications for the specified TP. 5.4.
TP Server Verbs QUERY_ATTACH Parameter Check If the verb does not execute because of a parameter error, APPC returns the following parameters: primary_rc AP_PARAMETER_CHECK secondary_rc Possible values are: AP_BAD_TPS_ID The value specified for the tps_id parameter was not recognized. AP_BAD_RES_ID The value specified for the res_id parameter was not recognized. Other Conditions If the verb does not execute because other conditions exist, APPC returns the following primary return code.
TP Server Verbs QUERY_ATTACH AP_UINT16 unsigned char AP_UINT16 AP_UINT16 unsigned char } QUERY_ATTACH; pip_dlen; *pip_dptr; max_fmh5_len; fmh5_dlen; *fmh5_dptr; 5.5.2 Supplied Parameters The TP supplies the following parameters to APPC: opcode AP_QUERY_ATTACH tps_id The ID of the TP server, as returned on a previous REGISTER_TP_SERVER verb. attach_id The ID of the attach, as returned by the attach notification callback. max_pip_len The maximum buffer space available for PIP data.
TP Server Verbs ACCEPT_ATTACH pip_dlen The actual number of bytes of PIP data returned. fmh5_dlen The actual number of bytes of FMH5 data returned. Unsuccessful Execution If the verb does not execute successfully, APPC returns a primary return code parameter to indicate the type of error and a secondary return code parameter to provide specific details about the reason for unsuccessful execution.
TP Server Verbs REJECT_ATTACH opcode AP_ACCEPT_ATTACH tps_id The ID of the TP server, as returned on a previous REGISTER_TP_SERVER verb. attach_id The ID of the attach, as returned by the attach notification callback. 5.6.3 Returned Parameters After the verb executes, APPC returns parameters to indicate whether the execution was successful and, if not, to indicate the reason the execution was not successful.
TP Server Verbs REJECT_ATTACH 5.7.1 VCB Structure: REJECT_ATTACH The definition of the VCB structure for the REJECT_ATTACH verb is as follows: typedef struct reject_attach { AP_UINT16 opcode; unsigned char rsrvd1; unsigned char rsrvd2; AP_UINT16 primary_rc; AP_UINT32 secondary_rc; AP_UINT32 tps_id; unsigned char attach_id[8]; AP_UINT32 reason; } REJECT_ATTACH; /* Reserved /* Reserved */ */ 5.7.
TP Server Verbs REJECT_ATTACH Possible values are: AP_BAD_ATTACH_ID The value specified for the attach_id parameter was not recognized. AP_BAD_TPS_ID The value specified for the tps_id parameter was not recognized. Other Conditions If the verb does not execute because other conditions exist, APPC returns the following primary return code. For a list of return codes common to all verbs, see Appendix B, Common Return Codes.
TP Server Verbs REJECT_ATTACH Symbol Value Meaning AP_SEC_BAD_PROCESSING_FAILURE 080FFF0D processing failed between the local and remote LUs, but the condition is temporary AP_SEC_BAD_PROTOCOL_VIOLATION 080F6058 a protocol violation resulted in a security validation failure AP_TRANS_PGM_NOT_AVAIL_RETRY 084B6031 TP not available— retry AP_TRANS_PGM_NOT_AVAIL_NO_RETRY 084C0000 TP not available—no retry AP_PIP_INVALID 1008201D PIP data not valid AP_ATTACH_LEN_INVALID 10086000 attach length
TP Server Verbs ABORT_ATTACH 5.8 ABORT_ATTACH The ABORT_ATTACH verb is used to end the processing of the attach by this TP server after the attach has been accepted using an ACCEPT_ATTACH verb because the TP server or TP has encountered an error during further processing. For example, the TP server was unable to fork to the TP. The ABORT_ATTACH verb can be issued by both the TP server and the TP processes. 5.8.
TP Server Verbs ABORT_ATTACH Parameter Check If the verb does not execute because of a parameter error, APPC returns the following parameters: primary_rc AP_PARAMETER_CHECK secondary_rc Possible values are: AP_BAD_ATTACH_ID The value specified for the attach_id parameter was not recognized. AP_BAD_TPS_ID The value specified for the tps_id parameter was not recognized. Other Conditions If the verb does not execute because other conditions exist, APPC returns the following primary return code.
Sample Transaction Programs Pseudocode 6 Sample Transaction Programs The SNAplus2 APPC sample transaction programs (TPs) illustrate the use of APPC verbs in a mapped conversation. The programs are provided with SNAplus2 as asample1.c and asample2.c, in the directory /opt/sna/ samples. The following information is provided in this chapter: • Processing overview of the sample TPs • Pseudocode for each TP • Instructions for compiling, linking, and running the TPs 6.
Sample Transaction Programs Testing the TPs get user prompt (F, B, or Q) if prompt = F or B /* Not Q */ mc_send_data (data = prompt), send type p_to_r_flush endif endif end do mc_deallocate TP_ended 6.2.
Sample Transaction Programs Testing the TPs To run the TPs, perform the following steps. Note that some of these steps involve updating the SNAplus2 configuration, which is usually performed by the System Administrator. The TPs can run on the same computer, or on separate computers. In the following steps, the “source computer” is the computer where the invoking TP asample1 runs, and the “target computer” is the computer where the invoked TP asample2 runs. 1.
Appendix AReturn Code Values AppendixA Return Code Values This appendix lists all the possible return codes in the APPC interface in numerical order. The values are defined in the header file values_c.h(for HP-UX) or winappc.h (for Windows). You can use this appendix as a reference to check the meaning of a return code received by your application. A.1 Primary Return Codes The following primary return codes are used in APPC applications.
Appendix AReturn Code Values AP_OPERATION_INCOMPLETE AP_OPERATION_NOT_ACCEPTED AP_CONVERSATION_ENDED AP_ERROR_INDICATION AP_EXPD_NOT_SUPPORTED_BY_LU AP_BUFFER_TOO_SMALL AP_MEMORY_ALLOCATION_FAILURE AP_INVALID_VERB 0x4000 0x4100 0x4200 0x4300 0x4400 0x4500 0x4600 0xFFFF A.2 Secondary Return Codes The following secondary return codes are used in APPC applications.
Appendix AReturn Code Values AP_BAD_ERROR_DIRECTION AP_INVALID_DATA_TYPE AP_TG_ROW_WGT_LESS_THAN_LAST AP_DUPLICATE_PORT_NUMBER AP_PU_ALREADY_ACTIVE AP_BAD_TP_TYPE AP_SEC_BAD_PASSWORD_MISSING AP_INVALID_STATS_TYPE AP_DUPLICATE_PORT_NAME AP_PU_NOT_ACTIVE AP_ALREADY_REGISTERED AP_SEC_BAD_GROUP_INVALID AP_AS_NEGOTIATED AP_INVALID_TABLE_TYPE AP_INVALID_DLC_NAME AP_DLUS_REJECTED AP_SEC_BAD_UID_REVOKED_IN_GRP AP_PORT_DEACTIVATED AP_INVALID_DLC_TYPE AP_DLUS_CAPS_MISMATCH AP_SEC_BAD_UID_NOT_DEFD_TO_GRP AP_ALLOCATE_
Appendix AReturn Code Values AP_BAD_SECURITY AP_INVALID_NN_SESSION_TYPE AP_LINK_DEACTIVATED AP_PARTNER_NOT_FOUND AP_PARTNER_NOT_RESPONDING AP_ERROR AP_DSPU_ALREADY_DEFINED AP_BAD_RETURN_CONTROL AP_INVALID_MAX_NEGOT_SESS_LIM AP_INVALID_SET_COLLECT_STATS AP_LINK_ACT_BY_REMOTE AP_INVALID_SOLICIT_SSCP_SESS AP_INVALID_BACK_LEVEL_SUPPORT AP_INVALID_MODE_NAME AP_INVALID_SET_COLLECT_NAMES AP_LINK_ACT_BY_LOCAL AP_INVALID_TG_NUMBER AP_MISSING_CP_NAME AP_MISSING_CP_TYPE AP_INVALID_CP_TYPE AP_DUPLICATE_TG_NUMBER AP_TG
Appendix AReturn Code Values AP_CPSVCMG_ALREADY_DEFD AP_INVALID_CN_NAME AP_INVALID_DRAIN_TARGET AP_TP_NAME_NOT_RECOGNIZED AP_INVALID_MIN_CONLOSERS AP_BAD_DUPLEX_TYPE AP_INVALID_BYPASS_SECURITY AP_DEF_LINK_INVALID_SECURITY AP_INVALID_FORCE AP_SYSTEM_TP_CANT_BE_CHANGED AP_INVALID_MAX_RU_SIZE_LOW AP_FDX_NOT_SUPPORTED_BY_LU AP_TEST_INVALID_FOR_FDX AP_INVALID_IMPLICIT_PLU_FORBID AP_INVALID_PROPAGATION_DELAY AP_SYSTEM_TP_CANT_BE_DELETED AP_INVALID_MAX_RECV_PACING_WIN AP_SEND_EXPD_INVALID_LENGTH AP_INVALID_SPECIF
Appendix AReturn Code Values AP_CONFIRM_NOT_LL_BDY AP_NO_PROFILES AP_INVALID_HPR_SUPPORT AP_CONFIRM_INVALID_FOR_FDX AP_CONVERSATION_TYPE_MISMATCH AP_INVALID_LU_MODEL AP_INVALID_MODEL_NAME AP_TOO_MANY_PROFILES AP_INVALID_CRYPTOGRAPHY AP_INVALID_UPDATE_TYPE AP_INVALID_CLU_CRYPTOGRAPHY AP_DIR_ENTRY_PARENT AP_INVALID_RESOURCE_TYPES AP_NODE_ALREADY_STARTED AP_CHECKSUM_FAILED AP_NODE_FAILED_TO_START AP_DATA_CORRUPT AP_LU_ALREADY_DEFINED AP_INVALID_RETRY_FLAGS AP_IMPLICIT_LU_DEFINED AP_DELAYED_VERB_PENDING AP_POR
Appendix AReturn Code Values AP_INVALID_FQPCID AP_MLTG_LINK_PROPERTIES_DIFFER AP_INVALID_POOL_NAME AP_INVALID_ADJ_CP_NAME AP_BAD_TYPE AP_INVALID_NAU_ADDRESS AP_INVALID_ENABLE_POOL AP_INVALID_SEND_TERM_SELF AP_DEALLOC_BAD_TYPE AP_LU_NAME_POOL_NAME_CLASH AP_SECURITY_NOT_VALID AP_INVALID_TERM_METHOD AP_DEALLOC_FLUSH_BAD_STATE AP_INVALID_PRIORITY AP_INVALID_DISABLE_BRANCH_AWRN AP_DEALLOC_CONFIRM_BAD_STATE AP_INVALID_DNST_LU_NAME AP_INVALID_SHARING_PROHIBITED AP_INVALID_HOST_LU_NAME AP_INVALID_LINK_SPEC_FORMAT
Appendix AReturn Code Values AP_COS_TABLE_FULL AP_INCONSISTENT_IMPLICIT AP_INVALID_DAYS_LEFT AP_INVALID_PREFER_ACTIVE_DLUS AP_ANYNET_NOT_SUPPORTED AP_INVALID_PERSIST_PIPE_SUPP AP_INVALID_DISCOVERY_SUPPORT AP_ACTIVATION_PROHIBITED AP_SESSION_FAIL_ALREADY_REGD AP_INVALID_NULL_ADDR_MEANING AP_CANT_MODIFY_VISIBILITY AP_INVALID_CPLU_SYNCPT_SUPPORT AP_CANT_MODIFY_WHEN_ACTIVE AP_INVALID_CPLU_ATTRIBUTES AP_INVALID_BASE_NUMBER AP_INVALID_REG_LEN_SUPPORT AP_DEACT_CG_INVALID_CGID AP_INVALID_NAME_ATTRIBUTES AP_LUNAME_
Appendix AReturn Code Values AP_INVALID_LINK_ENABLE AP_INVALID_CLU_COMPRESSION AP_INVALID_DLUR_SUPPORT AP_ALREADY_STARTING AP_RCV_IMMD_BAD_STATE AP_INVALID_LINK_NAME AP_INVALID_USER_DEF_1 AP_RCV_IMMD_BAD_FILL AP_INVALID_USER_DEF_2 AP_INVALID_NODE_TYPE AP_INVALID_USER_DEF_3 AP_INVALID_NAME_LEN AP_INVALID_NETID_LEN AP_INVALID_NODE_TYPE_FOR_HPR AP_INVALID_MAX_DECOMPRESS_LVL AP_INVALID_CP_NAME AP_INVALID_COMP_IN_SERIES AP_INVALID_LIMITED_RESOURCE AP_RCV_AND_POST_BAD_STATE AP_INVALID_BYTE_COST AP_RCV_AND_POST_N
Appendix BCommon Return Codes AppendixB Common Return Codes This appendix describes the primary return codes (and, if applicable, secondary return codes) that are common to several APPC verbs. Verb-specific return codes are described in the documentation for the individual verbs. Common return codes are described in the following sections. B.1 AP_ALLOCATION_ERROR The primary and secondary return codes are: primary_rc AP_ALLOCATION_ERROR APPC has failed to allocate a conversation.
Appendix BCommon Return Codes 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 cause of the error has been corrected. AP_TRANS_PGM_NOT_AVAIL_RETRY The remote LU rejected the allocation request because it was unable to start the requested partner TP.
Appendix BCommon Return Codes as AP_SECURITY_NOT_VALID. See the define_defaults command in the HP-UX SNAplus2 Administration Command Reference and DEFINE_DEFAULTS NOF verb in the HP-UX SNAplus2 NOF Programmer’s Guide for details. B.2 AP_BACKED_OUT UNIX The primary and secondary return codes are: primary_rc AP_BACKED_OUT The partner TP (or another TP participating in the same logical unit of work) has issued a backout request.
Appendix BCommon Return Codes The return code indicates that the SNAplus2 software has ended abnormally, or that there is a problem with the LAN. The System Administrator should examine the error log to determine the reason for the abend. A secondary return code is not returned. B.
Appendix BCommon Return Codes B.7 AP_CONV_FAILURE_RETRY The primary return code is: primary_rc 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. A secondary return code is not returned. B.
Appendix BCommon Return Codes A secondary return code is not returned. B.11 AP_DEALLOC_ABEND_SVC The primary return code is: primary_rc AP_DEALLOC_ABEND_SVC The conversation has been deallocated because the partner TP issued the DEALLOCATE verb with dealloc_type set to AP_ABEND_SVC. A secondary return code is not returned. B.
Appendix BCommon Return Codes The TP has issued a conversation verb with a duplex type that does not match the conversation. If the conversation is full-duplex (as specified by the duplex_type parameter on [MC_]ALLOCATE or RECEIVE_ALLOCATE), the TP must set the option AP_FULL_DUPLEX_CONVERSATION in the opext parameter of all other verbs in this conversation. If the conversation is half-duplex, it must not set this option. A secondary return code is not returned. B.
Appendix BCommon Return Codes B.18 AP_PROG_ERROR_PURGING The primary return code is: primary_rc AP_PROG_ERROR_PURGING The partner TP issued one of the following verbs: • SEND_ERROR with err_type set to AP_PROG • MC_SEND_ERROR while in Receive, Pending_Post, Confirm, Confirm_Send, or Confirm_Deallocate state. Data sent but not yet received is purged. A secondary return code is not returned. B.
Appendix BCommon Return Codes A secondary return code is not returned. B.22 AP_SVC_ERROR_TRUNC The primary return code is: primary_rc AP_SVC_ERROR_TRUNC In Send state, after sending an incomplete logical record, the partner TP (or partner LU) issued a SEND_ERROR verb. The local TP may have received the first part of the logical record. A secondary return code is not returned. B.
Appendix BCommon Return Codes A secondary return code is not returned. B.25 AP_UNEXPECTED_SYSTEM_ERROR The primary return code is: primary_rc AP_UNEXPECTED_SYSTEM_ERROR The operating system has encountered an error while processing an APPC call from the local TP. The operating system return code is returned through the secondary_rc. If the problem persists, consult your System Administrator. UNIX For the meaning of the operating system return code, see the file /usr/include/errno.
Appendix CAPPC State Changes AppendixC APPC State Changes The following tables show the conversation states in which each APPC verb may be issued, and the state change which occurs on completion of the verb. In some cases, the state change depends on the primary_rc parameter returned to the verb; where this applies, the applicable primary_rc values are shown in the same column as the verb.
Appendix CAPPC State Changes C.
Appendix CAPPC State Changes Verb and primary_rc Values State in Which Issued Reset Send Send Recv Confm Confm Confm Pend (T) (S) Pend (R) (C) Send Deall Post (CS) (CD) (PP) (SP) [MC_]RECEIVE_AND_POST (See Note 4) X P P P X X X X [MC_]RECEIVE_AND_WAIT (See Note 4 for Windows) X See Note 5 See Note 5 See Note 5 X X X X [MC_]RECEIVE_ IMMEDIATE X X X See Note 5 X X X X [MC_]RECEIVE_EXPEDITED_DATA X X X R C X X P [MC_]REQUEST_TO_SEND X X X R C X X
Appendix CAPPC State Changes Notes 1. In the Return codes column of the table, the abbreviation AP_ERROR is used for: AP_BACKED_OUT AP_PROG_ERROR_TRUNC AP_PROG_ERROR_NO_TRUNC AP_PROG_ERROR_PURGING AP_SVC_ERROR_TRUNC AP_SVC_ERROR_NO_TRUNC AP_SVC_ERROR_PURGING 2. The conversation always enters Reset state if one of the following return codes is received.
Appendix CAPPC State Changes C.
Appendix CAPPC State Changes Verb and primary_rc Values State in Which Issued Reset Send Receive Send Only Receive Only (T) (SR) (S) (R) X SR S R AP_OK X SR S X AP_ERROR X SR T X AP_OK X SR S X AP_ERROR X SR T X [MC_]SEND_ EXPEDITED_DATA X SR S R [MC_]RECEIVE_ EXPEDITED_DATA [MC_]SEND_DATA [MC_]SEND_ERROR Notes 1.
Appendix DSNA LU 6.2 Support AppendixD SNA LU 6.2 Support This appendix details how the SNAplus2 implementation of APPC relates to the LU 6.2 architecture. It includes the following information: • A summary of the LU 6.2 option sets supported by SNAplus2 • A list of the control operator verbs which are included in the SNAplus2 APPC implementation • A list of the control operator verbs whose functions are performed in SNAplus2 by the administration tools or by the NOF API. D.1 LU 6.
Appendix DSNA LU 6.
Appendix DSNA LU 6.2 Support D.2 Control Operator Verb Support The functions of the following control operator verbs are provided as part of the SNAplus2 APPC implementation: RECEIVE_ALLOCATE TP_STARTED TP_ENDED The functions of the following control operator verbs are provided by the SNAplus2 administration programs and by the NOF API.
Index A abnormal deallocation basic conversation . . . . . . . . . . . mapped conversation . . . . . . . . . ABORT_ATTACH parameter check . . . . . . . . . . . successful execution . . . . . . . . . . supplied parameters . . . . . . . . . . VCB . . . . . . . . . . . . . . . . verb . . . . . . . . . . . . . . . . ACCEPT_ATTACH parameter check . . . . . . . . . . . successful execution . . . . . . . . . . supplied parameters . . . . . . . . . . VCB . . . . . . . . . . . . . . . . verb . . . . . . . . . . . .
data in local LU’s send buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140, 215 flushing (see flushing local LU’s send buffer) . . . . . . . . . . . . . . . . . . . . . . . . 140 C callback routine . . . . . . . . . . . . . . . . . . . callback routine on [MC_]DEALLOCATE verb . . . . . . callback routine used by [MC_]RECEIVE_AND_POST verb . callback routine used by [MC_]TEST_RTS_AND_POST verb child process . . . . . . . . . . . . . . . . . . . . comp_proc (callback routine) . . . . . . . . .
security ( See also conversation security ) sending . . . . . . . . . . . . starting . . . . . . . . . . . . state ( See also conversation state ) synchronization level . . . . . . TP’s view of the conversation . . . conversation identifier . . . . . . . conversation security already verified . . . . . . . . . establishing . . . . . . . . . . overview . . . . . . . . . . . password . . . . . . . . . . . user ID . . . . . . . . . . . . conversation state changes in state . . . . . . . .
entry points, synchronous and asynchronous for Windows . . . error log and DEALLOCATE verb . . . . . . . . . . . . . . . and SEND_ERROR verb . . . . . . . . . . . . . . . description . . . . . . . . . . . . . . . . . . . . errors reporting . . . . . . . . . . . . . . . . . . . . . reporting in basic conversations . . . . . . . . . . . . Expedited data notification receiving through [MC_]CONFIRM verb . . . . . . . . receiving through [MC_]DEALLOCATE verb . . . . . .
successful execution . supplied parameters . VCB . . . . . . . GET_TYPE parameter check . . state when issued . . successful execution . supplied parameters . VCB . . . . . . . GetAppcConfig call . . GetAppcReturnCode call getting LU status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
[MC_]verb notation . . . . . . . . . . . MC_ALLOCATE allocation error . . . . . . . . . . . . confirming the allocation . . . . . . . . EBCDIC-ASCII, ASCII-EBCDIC translation immediate allocation . . . . . . . . . parameter check . . . . . . . . . . . session not available . . . . . . . . . . state change . . . . . . . . . . . . . state when issued . . . . . . . . . . . successful execution . . . . . . . . . . supplied parameters . . . . . . . . . . VCB . . . . . . . . . . . . . . . . verb . . . . . . . . .
returned attributes . . . . . . . . . . state when issued . . . . . . . . . . successful execution . . . . . . . . . supplied parameter . . . . . . . . . VCB . . . . . . . . . . . . . . . verb . . . . . . . . . . . . . . . MC_PREPARE_TO_RECEIVE confirmation requests, sending . . . . . flushing before changing state . . . . . parameter check . . . . . . . . . . state change . . . . . . . . . . . . state check . . . . . . . . . . . . state when issued . . . . . . . . . . successful execution . . . . . . . . .
parameter check . . . . . . . . . . SEND indicator . . . . . . . . . . Send state, issuing verb in . . . . . . state check . . . . . . . . . . . . state when issued . . . . . . . . . . status information received . . . . . . successful execution . . . . . . . . . supplied parameters . . . . . . . . . VCB . . . . . . . . . . . . . . . verb . . . . . . . . . . . . . . . MC_RECEIVE_EXPEDITED_DATA conversation deallocated . . . . . . . data buffer too small . . . . . . . . DEALLOC_NORMAL indicator . . . .
successful execution . . . . . supplied parameters . . . . . VCB . . . . . . . . . . . verb . . . . . . . . . . . MC_SEND_DATA parameter check . . . . . . state change . . . . . . . . state check . . . . . . . . state when issued . . . . . . successful execution . . . . . supplied parameters . . . . . VCB . . . . . . . . . . . verb . . . . . . . . . . . waiting for partner TP . . . . MC_SEND_ERROR parameter check . . . . . . purged data . . . . . . . . state change . . . . . . . . state when issued . . . .
multiple sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . N nonqueued, automatically started TP . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 71 P parallel sessions . . . . . . . . . partner LU definition . . . . . . . . . . . specifying . . . . . . . . . . . partner TP . . . . . . . . . . . . Pending_Post state . . . . . . . . PIP data . . . . . . . . . . . . . PREPARE_TO_RECEIVE confirmation requests, sending . . . flushing before changing state . . .
state check . . . . . . . . . . . . state when issued . . . . . . . . . . successful execution . . . . . . . . . supplied parameters . . . . . . . . . VCB . . . . . . . . . . . . . . . verb . . . . . . . . . . . . . . . waits, avoiding . . . . . . . . . . . RECEIVE_AND_POST buffer format . . . . . . . . . . . callback routine . . . . . . . . . . CONFIRM_DEALLOCATE indicator . . CONFIRM_SEND indicator . . . . . . CONFIRM_WHAT_RECEIVED indicator conversation deallocated . . . . . . . DATA indicator . . . . .
data buffer too small . . . . . . . . DEALLOC_NORMAL indicator . . . . expedited data not supported . . . . . no data available . . . . . . . . . . parameter check . . . . . . . . . . state check . . . . . . . . . . . . state when issued . . . . . . . . . . successful execution . . . . . . . . . supplied parameters . . . . . . . . . VCB . . . . . . . . . . . . . . . verb . . . . . . . . . . . . . . . RECEIVE_IMMEDIATE buffer format . . . . . . . . . . . CONFIRM_DEALLOCATE indicator . .
verb . . . . . . . . . . . . . . . . . . . remote LU . . . . . . . . . . . . . . . . . . remote TP . . . . . . . . . . . . . . . . . . REQUEST_TO_SEND action of partner TP . . . . . . . . . . . . . conversation deallocated . . . . . . . . . . . parameter check . . . . . . . . . . . . . . state check . . . . . . . . . . . . . . . . state when issued . . . . . . . . . . . . . . successful execution . . . . . . . . . . . . . supplied parameters . . . . . . . . . . . . . VCB . . . . . . . . . . . . . . . . . .
successful execution . . . . . . . . . . . . . . . . . . . . . . supplied parameters . . . . . . . . . . . . . . . . . . . . . . VCB . . . . . . . . . . . . . . . . . . . . . . . . . . . . verb . . . . . . . . . . . . . . . . . . . . . . . . . . . . waiting for partner TP . . . . . . . . . . . . . . . . . . . . . SEND_ERROR parameter check . . . . . . . . . . . . . . . . . . . . . . . purged data . . . . . . . . . . . . . . . . . . . . . . . . . state change . . . . . . . . . . . . . . . . . . . . . . . . .
T TEST_RTS parameter check . . . . . . . . state when issued . . . . . . . . successful execution . . . . . . . supplied parameters . . . . . . . VCB . . . . . . . . . . . . . verb . . . . . . . . . . . . . TEST_RTS_AND_POST callback routine . . . . . . . . conversation deallocated . . . . . DEALLOC_NORMAL indicator . . how to use the verb . . . . . . . indefinite waits, avoiding . . . . . parameter check . . . . . . . . state when issued . . . . . . . . successful execution . . . . . . .
remote TP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 service TP ( See service TP ) starting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45, 78 U UNREGISTER_TP parameter check . . . . successful execution . . . supplied parameters . . . VCB . . . . . . . . . verb . . . . . . . . . UNREGISTER_TP_SERVER parameter check . . . . successful execution . . . supplied parameters . . . VCB . . . . . . . . . verb . . . . . . . . .
