SNAP-IX APPC Programmer's Guide
BeforeYou Begin
Prerequisite Knowledge
Intended Audience
About This Book
Organization of This Book
Typographic Conventions
Graphic Conventions
SNAP-IX Publications
Publications for Users
Publications for Administrators
Publications for Programmers
Related Publications
1 Concepts
1.1 What Is APPC?
1.1.1 Transaction Programs
1.1.2 Communication between TPs
1.1.3 Logical Unit 6.2
1.1.4 Sessions
1.1.5 Conversations
1.1.6 APPC Verbs
1.1.7 The Conversation Process
1.1.8 Conversation Types
1.1.9 Multiple Conversations
1.2 A Simple Mapped Conversation
1.2.1 Starting a Conversation
1.2.2 Sending Data
1.2.3 Receiving Data
1.2.4 Ending a Conversation
1.3 Confirmation Processing
1.3.1 Establishing the Synchronization Level
1.3.2 Sending a Confirmation Request
1.3.3 Receiving Data and a Confirmation Request
1.3.4 Responding to the Confirmation Request
1.3.5 Deallocating the Conversation
1.4 Sending and Receiving Status with Data
1.4.1 Sending Status Information with Data
1.4.2 Receiving Status Information with Data
1.5 Conversation States
1.5.1 The TP's View of the Conversation
1.5.2 State Changes
1.5.3 State Checks
1.6 Changing Conversation States
1.6.1 Initial States
1.6.2 Changing to Receive State
1.6.3 Changing to Send State
1.7 Synchronous and Asynchronous APPC Calls
1.8 Receiving Data Asynchronously
1.9 Syncpoint Support
1.10 APPC and CPI-C
1.11 TP Server API
2 Writing Transaction Programs
2.1 Categories of APPC Verbs
2.1.1 Control Verbs
2.1.2 Conversation Verbs
2.1.3 TP Server Verbs
2.2 APPC Verb Summary
2.2.1 Starting a Conversation
2.2.2 Sending Data
2.2.3 Receiving Data
2.2.4 Confirming Receipt of Data or Reporting Errors
2.2.5 Getting Information
2.2.6 Ending a Conversation
2.2.7 Starting a Transaction Program (TP)
2.3 APPC Entry Points: Solaris Systems
2.3.1 APPC Entry Point
2.3.2 APPC_Async Entry Point
2.3.3 Scheduling Asynchronous Events
2.3.4 Callback Routine for Asynchronous Verb Completion
2.4 APPC Entry Points: Windows Systems
2.4.1 WinAPPCStartup
2.4.2 WinAsyncAPPC
2.4.3 WinAsyncAPPCEx
2.4.4 WinAPPCCancelAsyncRequest
2.4.5 WinAPPCCleanup
2.4.6 Blocking Verbs
2.4.7 APPC
2.4.8 WinAPPCCancelBlockingCall
2.4.9 WinAPPCIsBlocking
2.4.10 WinAPPCSetBlockingHook
2.4.11 WinAPPCUnhookBlockingHook
2.4.12 GetAppcConfig
2.4.13 GetAppcReturnCode
2.5 Solaris Considerations
2.5.1 Multiple Processes
2.5.2 Compiling and Linking the APPC Application
2.6 Windows Considerations
2.6.1 Compiling and Linking APPC Programs
2.6.2 Terminating Applications
2.7 Configuration Information
2.7.1 Invoked TP
2.7.2 Invoking TP
2.8 Overview of Conversation Security
2.9 Starting TPs
2.9.1 Invoking TPs
2.9.2 Invoked TPs
2.9.3 Invoked TPs: User-Started
2.9.4 Invoked TPs: Automatically Started by the SNAP-IX Attach Manager
2.9.5 Invoked TPs: Automatically Started by a TP Server Application
2.9.6 Timeout Values for Invoked TPs
2.10 LU-to-LU Sessions
2.10.1 Contention
2.11 Basic Conversations
2.11.1 Logical Records
2.11.2 Reporting Errors and Abends
2.11.3 Error Log
2.11.4 Timeouts Versus Critical Errors
2.12 Writing TP Servers
2.12.1 TP Server Responsibilities
2.12.2 Default TP Server
2.13 Writing Portable TPs
3 APPC Control Verbs
3.1 TP_STARTED
3.1.1 VCB Structure: TP_STARTED
3.1.2 VCB Structure: TP_STARTED (Windows)
3.1.3 Supplied Parameters
3.1.4 Returned Parameters
3.1.5 State When Issued
3.1.6 State Change
3.2 TP_ENDED
3.2.1 VCB Structure: TP_ENDED
3.2.2 VCB Structure: TP_ENDED (Windows)
3.2.3 Supplied Parameters
3.2.4 Returned Parameters
3.2.5 State When Issued
3.2.6 State Change
3.3 RECEIVE_ALLOCATE
3.3.1 VCB Structure: RECEIVE_ALLOCATE
3.3.2 VCB Structure: RECEIVE_ALLOCATE (Windows)
3.3.3 Supplied Parameters
3.3.4 Returned Parameters
3.3.5 State When Issued
3.3.6 State Change
3.3.7 Avoiding Waits
3.3.8 Routing for Incoming Attaches
3.4 GET_LU_STATUS
3.4.1 VCB Structure: GET_LU_STATUS
3.4.2 Supplied Parameters
3.4.3 Returned Parameters
3.4.4 State When Issued
3.4.5 State Change
3.5 GET_TP_PROPERTIES
3.5.1 VCB Structure: GET_TP_PROPERTIES
3.5.2 VCB Structure: GET_TP_PROPERTIES (Windows)
3.5.3 Supplied Parameters
3.5.4 Returned Parameters
3.5.5 State When Issued
3.5.6 State Change
3.6 SET_TP_PROPERTIES
3.6.1 VCB Structure: SET_TP_PROPERTIES
3.6.2 Supplied Parameters
3.6.3 Returned Parameters
3.6.4 State When Issued
3.6.5 State Change
3.6.6 Usage and Restrictions
4 APPC Conversation Verbs
4.1 GET_TYPE
4.1.1 VCB Structure: GET_TYPE
4.1.2 VCB Structure: GET_TYPE (Windows)
4.1.3 Supplied Parameters
4.1.4 Returned Parameters
4.1.5 State When Issued
4.1.6 State Change
4.2 MC_ALLOCATE and ALLOCATE
4.2.1 VCB Structure: MC_ALLOCATE
4.2.2 VCB Structure: ALLOCATE
4.2.3 VCB Structure: MC_ALLOCATE (Windows)
4.2.4 VCB Structure: ALLOCATE (Windows)
4.2.5 Supplied Parameters
4.2.6 Returned Parameters
4.2.7 State When Issued
4.2.8 State Change
4.2.9 EBCDIC-ASCII, ASCII-EBCDIC Translation
4.2.10 Immediate Allocation
4.2.11 Confirming the Allocation
4.3 MC_CONFIRM and CONFIRM
4.3.1 VCB Structure: MC_CONFIRM
4.3.2 VCB Structure: CONFIRM
4.3.3 VCB Structure: MC_CONFIRM (Windows)
4.3.4 VCB Structure: CONFIRM (Windows)
4.3.5 Supplied Parameters
4.3.6 Returned Parameters
4.3.7 State When Issued
4.3.8 State Change
4.3.9 Synchronizing with Partner TP
4.4 MC_CONFIRMED and CONFIRMED
4.4.1 Sources of Confirmation Requests
4.4.2 Receiving Confirmation Requests
4.4.3 VCB Structure: MC_CONFIRMED
4.4.4 VCB Structure: CONFIRMED
4.4.5 VCB Structure: MC_CONFIRMED (Windows)
4.4.6 VCB Structure: CONFIRMED (Windows)
4.4.7 Supplied Parameters
4.4.8 Returned Parameters
4.4.9 State When Issued
4.4.10 State Change
4.5 MC_DEALLOCATE and DEALLOCATE
4.5.1 VCB Structure: MC_DEALLOCATE
4.5.2 VCB Structure: DEALLOCATE
4.5.3 VCB Structure: MC_DEALLOCATE (Windows)
4.5.4 VCB Structure: DEALLOCATE (Windows)
4.5.5 Supplied Parameters
4.5.6 Returned Parameters
4.5.7 State When Issued
4.5.8 State Change
4.5.9 Implied Forget Notification
4.6 MC_FLUSH and FLUSH
4.6.1 Sources of Buffered Data
4.6.2 VCB Structure: MC_FLUSH
4.6.3 VCB Structure: FLUSH
4.6.4 VCB Structure: MC_FLUSH (Windows)
4.6.5 VCB Structure: FLUSH (Windows)
4.6.6 Supplied Parameters
4.6.7 Returned Parameters
4.6.8 State When Issued
4.6.9 State Change
4.7 MC_GET_ATTRIBUTES and GET_ATTRIBUTES
4.7.1 VCB Structure: MC_GET_ATTRIBUTES
4.7.2 VCB Structure: GET_ATTRIBUTES
4.7.3 VCB Structure: MC_GET_ATTRIBUTES (Windows)
4.7.4 VCB Structure: GET_ATTRIBUTES (Windows)
4.7.5 Supplied Parameters
4.7.6 Returned Parameters
4.7.7 State When Issued
4.7.8 State Change
4.8 MC_PREPARE_TO_RECEIVE and PREPARE_TO_RECEIVE
4.8.1 VCB Structure: MC_PREPARE_TO_RECEIVE
4.8.2 VCB Structure: PREPARE_TO_RECEIVE
4.8.3 VCB Structure: MC_PREPARE_TO_RECEIVE (Windows)
4.8.4 VCB Structure: PREPARE_TO_RECEIVE (Windows)
4.8.5 Supplied Parameters
4.8.6 Returned Parameters
4.8.7 State When Issued
4.8.8 State Change
4.8.9 Usage Note
4.9 MC_RECEIVE and RECEIVE Verbs
4.9.1 How a TP Receives Data
4.9.2 The what_rcvd Parameter
4.9.3 End of Data
4.9.4 Testing the what_rcvd Parameter
4.10 MC_RECEIVE_AND_POST and RECEIVE_AND_POST
4.10.1 VCB Structure: MC_RECEIVE_AND_POST
4.10.2 VCB Structure: RECEIVE_AND_POST
4.10.3 VCB Structure: MC_RECEIVE_AND_POST (Windows)
4.10.4 VCB Structure: RECEIVE_AND_POST (Windows)
4.10.5 Supplied Parameters
4.10.6 Returned Parameters
4.10.7 State When Issued
4.10.8 State Change
4.10.9 Usage Notes
4.11 MC_RECEIVE_AND_WAIT and RECEIVE_AND_WAIT
4.11.1 VCB Structure: MC_RECEIVE_AND_WAIT
4.11.2 VCB Structure: RECEIVE_AND_WAIT
4.11.3 VCB Structure: MC_RECEIVE_AND_WAIT (Windows)
4.11.4 VCB Structure: RECEIVE_AND_WAIT (Windows)
4.11.5 Supplied Parameters
4.11.6 Returned Parameters
4.11.7 State When Issued
4.11.8 State Change
4.11.9 Usage Notes
4.12 MC_RECEIVE_IMMEDIATE and RECEIVE_IMMEDIATE
4.12.1 VCB Structure: MC_RECEIVE_IMMEDIATE
4.12.2 VCB Structure: RECEIVE_IMMEDIATE
4.12.3 VCB Structure: MC_RECEIVE_IMMEDIATE (Windows)
4.12.4 VCB Structure: RECEIVE_IMMEDIATE (Windows)
4.12.5 Supplied Parameters
4.12.6 Returned Parameters
4.12.7 State When Issued
4.12.8 State Change
4.12.9 PS Header Data
4.13 MC_REQUEST_TO_SEND and REQUEST_TO_SEND
4.13.1 Action of the Partner TP
4.13.2 When the Local TP Can Send Data
4.13.3 VCB Structure: MC_REQUEST_TO_SEND
4.13.4 VCB Structure: REQUEST_TO_SEND
4.13.5 VCB Structure: MC_REQUEST_TO_SEND (Windows)
4.13.6 VCB Structure: REQUEST_TO_SEND (Windows)
4.13.7 Supplied Parameters
4.13.8 Returned Parameters
4.13.9 State When Issued
4.13.10 State Change
4.13.11 Receiving Request-to-Send Notification
4.14 MC_SEND_CONVERSATION and SEND_CONVERSATION
4.14.1 VCB Structure: MC_SEND_CONVERSATION
4.14.2 VCB Structure: SEND_CONVERSATION
4.14.3 VCB Structure: MC_SEND_CONVERSATION (Windows)
4.14.4 VCB Structure: SEND_CONVERSATION (Windows)
4.14.5 Supplied Parameters
4.14.6 Returned Parameters
4.14.7 State When Issued
4.14.8 State Change
4.15 MC_SEND_DATA and SEND_DATA
4.15.1 VCB Structure: MC_SEND_DATA
4.15.2 VCB Structure: SEND_DATA
4.15.3 VCB Structure: MC_SEND_DATA (Windows)
4.15.4 VCB Structure: SEND_DATA (Windows)
4.15.5 Supplied Parameters
4.15.6 Returned Parameters
4.15.7 State When Issued
4.15.8 State Change
4.15.9 Waiting for Partner TP
4.15.10 Logical Records in Basic Conversations
4.16 MC_SEND_ERROR and SEND_ERROR
4.16.1 VCB Structure: MC_SEND_ERROR
4.16.2 VCB Structure: SEND_ERROR
4.16.3 VCB Structure: MC_SEND_ERROR (Windows)
4.16.4 VCB Structure: SEND_ERROR (Windows)
4.16.5 Supplied Parameters
4.16.6 Returned Parameters
4.16.7 State When Issued
4.16.8 State Change
4.16.9 Purged Data
4.17 MC_TEST_RTS and TEST_RTS
4.17.1 VCB Structure: MC_TEST_RTS
4.17.2 VCB Structure: TEST_RTS
4.17.3 VCB Structure: MC_TEST_RTS (Windows)
4.17.4 VCB Structure: TEST_RTS (Windows)
4.17.5 Supplied Parameters
4.17.6 Returned Parameters
4.17.7 State When Issued
4.17.8 State Change
4.18 MC_TEST_RTS_AND_POST and TEST_RTS_AND_POST
4.18.1 VCB Structure: MC_TEST_RTS_AND_POST
4.18.2 VCB Structure: TEST_RTS_AND_POST
4.18.3 VCB Structure: MC_TEST_RTS_AND_POST (Windows)
4.18.4 VCB Structure: TEST_RTS_AND_POST (Windows)
4.18.5 Supplied Parameters
4.18.6 Returned Parameters
4.18.7 State When Issued
4.18.8 State Change
4.18.9 Usage Notes
5 TP Server Verbs
5.1 REGISTER_TP_SERVER
5.1.1 VCB Structure: REGISTER_TP_SERVER
5.1.2 Supplied Parameters
5.1.3 Returned Parameters
5.1.4 Usage Notes
5.2 UNREGISTER_TP_SERVER
5.2.1 VCB Structure: UNREGISTER_TP_SERVER
5.2.2 Supplied Parameters
5.2.3 Returned Parameters
5.3 REGISTER_TP
5.3.1 VCB Structure: REGISTER_TP
5.3.2 Supplied Parameters
5.3.3 Returned Parameters
5.4 UNREGISTER_TP
5.4.1 VCB Structure: UNREGISTER_TP
5.4.2 Supplied Parameters
5.4.3 Returned Parameters
5.5 QUERY_ATTACH
5.5.1 VCB Structure: QUERY_ATTACH
5.5.2 Supplied Parameters
5.5.3 Returned Parameters
5.6 ACCEPT_ATTACH
5.6.1 VCB Structure: ACCEPT_ATTACH
5.6.2 Supplied Parameters
5.6.3 Returned Parameters
5.7 REJECT_ATTACH
5.7.1 VCB Structure: REJECT_ATTACH
5.7.2 Supplied Parameters
5.7.3 Returned Parameters
5.8 ABORT_ATTACH
5.8.1 VCB Structure: ABORT_ATTACH
5.8.2 Supplied Parameters
5.8.3 Returned Parameters
6 Sample Transaction Programs
6.1 Processing Overview
6.2 Pseudocode
6.2.1
asample1
(Invoking TP)
6.2.2
asample2
(Invoked TP)
6.3 Testing the TPs
Appendix A: Common Return Codes
A.1 AP_ALLOCATION_ERROR
A.2 AP_BACKED_OUT
A.3 AP_CANCELLED
A.4 AP_COMM_SUBSYSTEM_ABENDED
A.5 AP_COMM_SUBSYSTEM_NOT_LOADED
A.6 AP_CONV_FAILURE_NO_RETRY
A.7 AP_CONV_FAILURE_RETRY
A.8 AP_CONVERSATION_TYPE_MIXED
A.9 AP_DEALLOC_ABEND
A.10 AP_DEALLOC_ABEND_PROG
A.11 AP_DEALLOC_ABEND_SVC
A.12 AP_DEALLOC_ABEND_TIMER
A.13 AP_DEALLOC_NORMAL
A.14 AP_INVALID_VERB
A.15 AP_INVALID_VERB_SEGMENT
A.16 AP_PROG_ERROR_NO_TRUNC
A.17 AP_PROG_ERROR_PURGING
A.18 AP_PROG_ERROR_TRUNC
A.19 AP_SVC_ERROR_NO_TRUNC
A.20 AP_SVC_ERROR_PURGING
A.21 AP_SVC_ERROR_TRUNC
A.22 AP_THREAD_BLOCKING
A.23 AP_TP_BUSY
A.24 AP_UNEXPECTED_SYSTEM_ERROR
Appendix B: APPC State Changes
Appendix C: SNA LU 6.2 Support
C.1 LU 6.2 Option Set Support
C.1.1 LU 6.2 Option Sets Supported by APPC Verbs
C.1.2 LU 6.2 Option Sets Supported by the Administration Tools and by theNOF API
C.2 Control Operator Verb Support
Index