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