Table of Contents (exploded view)
Abstract for MVS Programming: Writing Transaction Programs for APPC/MVS
z/OS Version 2 Release 1 summary of changes
Introduction
Introduction to APPC/MVS
Programming
Designing and Writing an APPC/MVS Transaction Program
Benefits of APPC/MVS for Application Programs
The Elements of Conversation
Conversation States
APPC Conversation Services
Starting a Conversation
Sending and Receiving Data
Requesting Permission to Send
Granting Permission to Send
Requesting Confirmation
Sending Error Notification
Returning Error Information
Ending Conversations
Identifying TP Partners to MVS
Supplying TP Profiles on MVS
Supplying Side Information on MVS
Relating MVS Callable Services to CPI Communications
Flow Diagrams of Typical APPC/MVS Conversations
Simple One-Way Conversation
Simple Two-Way Conversation
Confirmation of a Transaction
Sending Error Notification
TP Environment and Design Considerations
The General APPC/MVS Environment for Transaction Programs
Requirements for TPs in Problem-Program State
General Requirements
Features of APPC/MVS for All TPs
Portability and MVS-Specific Services
Features of the MVS-Specific Services
Security
Using Basic or Mapped Conversations
Data Conversion
Using Protected Conversations
Error Handling and Deallocation of Conversations
Error_Extract Service
Send_Error Service
API Trace Facility
Using CPI Communications
CPI Communications in APPC/MVS
Invocation Details for CPI Communications
Interface Definition Files (IDFs) for CPI-C Calls
Transaction Program (TP) Environment
Requirements for TPs in Problem-Program State
General Requirements
High-Level Language Compilers
Calling CPI Communications Routines
Parameter Descriptions
Required Modules
Conversation States
Performance Considerations
The APPC/MVS Programming Interface
APPC/MVS TP Conversation Services
APPC/MVS TP Conversation States
Guide to the Conversation Services
Starting a Conversation
Asynchronous notification
Authorized parameters
Accepting a Conversation
Obtaining Information about the Conversation
Getting Current TP Properties
Changing Syncpoint Options for Protected Conversations
Sending and Receiving Data
Support for Data Spaces
Requesting Permission to Send
Granting Permission to Send
Requesting Confirmation
Returning Error Information
Sending Error Notification
Ending Conversations
Using Asynchronous Services
Using the Asynchronous_Manager Service
Obtaining Asynchronous Notification of Data to be Received
Using Post_on_Receipt
Using Receive_and_Wait with a Receive_Length of Zero
Setting a Timeout Value for Potential Network Delays
Performance Considerations for Conversation Services
Advanced TP Services
Extracting Detailed Scheduling and Conversation Information
Adding User Data to Accounting Records
Using TP Schedule Types
Using the Standard Schedule Type
Using the Multi-Trans Schedule Type
Examples of Multi-Trans Scheduling
Security for the Standard and Multi-Trans Schedule Types
Performance Considerations for TP Schedule Types
Assigning Multi-Trans TPs to their own Class of Transaction Initiators
Establishing a Multi-Trans Transaction Program that is Always Available
SMF Recording for Multi-Trans Services
Identifying and Deallocating Conversations with Outstanding Asynchronous Requests
Rejecting Conversations
Testing TPs
System Services
Example APPC/MVS Transaction Programs
Installing and Testing Transaction Programs
Installing a TP for Testing
Testing a TP on MVS
Methods You Can Use to Create a Test Shell
Descriptions of APPC/MVS Test Services
Test Shell Characteristics
Calling APPC/MVS Test Services from Your Application
Using the TSO/E TEST Command to Test an Assembler Language TP
Testing a TP under APPC/MVS Scheduling
Requesting a User-Level or Group-Level TP Profile
Requesting Access to a User-Level TP Profile
Requesting Side Information
Enabling an LU for User-Level TP Profiles
Collecting Problem Data for Errors that Occur During Testing
Displaying APPC Activity on MVS
Tracing APPC Conversations
Putting a Tested TP into Production
Replacing an Active TP
Diagnosing Problems with APPC/MVS TPs
Comparing the Detectives: Error_Extract, API Trace, and the TP Message Log
Clues: What Information They Collect
Modus Operandi: How They Interrogate Suspects
Fees: How to Reduce the Cost of the Investigation
The Initial Consultation: Building Your Crime Lab
The All-Star Collaboration: A Team Approach
Calls that Error_Extract or API Trace Support
Diagnosing TP Conversation Errors with the API Trace Facility
Setting Up API Trace Data Sets
Getting Access to APPC/MVS Resources for Tracing Activity
Determining Data Set Characteristics
Avoiding Loss of Data through Wrapping
Avoiding Loss of Data through Suspension of Tracing Activity
Some Suggestions for Data Set Setup...
Starting API Tracing Activity
How APPC/MVS Handles an ATBTRACE START Request
Timing: When Tracing Starts
Using VTAM Generic Resource Names
Using Symbolic Destination Names
Collecting Trace Data for Concurrent Conversations
Filtering Trace Data by User ID
Collecting Trace Data for Security_None Conversations
Collecting Trace Data for TPs with Multiple Levels
Some Suggestions for ATBTRACE START Requests...
Using the ATBTRACE REXX Exec
Programming Considerations
Requirements
Restrictions
Output from the API Trace Facility
Return Codes
Messages
Methods of Invoking the ATBTRACE REXX Exec
Invoking the ATBTRACE Exec in the TSO/E Foreground
Explicitly Invoking the ATBTRACE Exec
Implicitly Invoking the ATBTRACE Exec
Invoking the ATBTRACE Exec in MVS Batch
Using IRXJCL
Using IKJEFT01
Invoking the ATBTRACE Exec from an HLL Program
Invoking the ATBTRACE Exec from TP Profile JCL
Starting an API Trace
Selecting the Invocation Method for the ATBTRACE START Request
Coding an ATBTRACE START Request
Stopping Trace Activity
Selecting the Invocation Method for the ATBTRACE STOP Request
Coding an ATBTRACE STOP Request
Listing Active API Traces
Selecting the Invocation Method for the ATBTRACE LIST Request
Coding an ATBTRACE LIST Request
Interpreting API Trace Data
Reading Service-Entry and Service-Return Trace Entries
Reading Trace Entries When Wrapping Occurred
Finding All Trace Entries for a Specific Conversation
Determining the Level of TP Traced
Assessing the Impact of Trace Entries Lost during Suspension
Assessing the Impact of Trace Entries Lost because of Termination
Overview of Error_Extract Service
Types of Error Information that Error_Extract Returns
Error Log Information
Product Set Identifiers
Rules for Calling Error_Extract
Calling Error_Extract for an Unestablished Conversation
Using Error_Extract for Synchronous and Asynchronous Calls
Calling Error_Extract for Synchronous Requests
Example Call to Error_Extract (Synchronous)
Calling Error_Extract for Asynchronous Requests
Example Call to Error_Extract (Asynchronous)
Diagnosing Product-Specific Errors
Reference
Invocation Details for APPC/MVS Callable Services
APPC/MVS Program Environment
High-Level Language Compilers
Syntax and Linkage Conventions for the Callable Services
Parameter Description for Callable Services
Required Modules
Versions of Callable Services
Interface Definition Files (IDFs) for LU6.2 and APPC/MVS Services
APPC/MVS TP Conversation Callable Services
Allocate
Confirm
Confirmed
Deallocate
Error_Extract
Flush
Get_Attributes
Get_Conversation
Get_TP_Properties
Get_Type
Post_on_Receipt
Prepare_to_Receive
Receive_Immediate
Receive_and_Wait
Request_to_Send
Send_Data
Send_Error
Set_Syncpt_Options
Set_TimeOut_Value
APPC/MVS Advanced TP Callable Services
Advanced TP Callable Services with Multiple Call Names
Asynchronous_Manager
Accept_Test
Cleanup_TP
Extract_Information
Get_Transaction
Register_Test
Reject_Conversation
Return_Transaction
Set_Conversation_Accounting_Information
Unregister_Test
Version_Service
API Trace Facility Messages
ATB60001I
Error_Extract Reason Codes and Messages
Summary of Error_Extract Reason Codes
Error_Extract Error Log Information (ASB, ATB7) Messages
ASB70000I
ASB70001I
ASB70002I
ASB70003I
ASB70004I
ASB70005I
ASB70006I
ASB70007I
ASB70008I
ASB70009I
ASB70010I
ASB70011I
ASB70012I
ASB70013I
ASB70014I
ASB70015I
ATB70001I
ATB70002I
ATB70003I
ATB70005I
ATB70006I
ATB70007I
ATB70008I
ATB70009I
ATB70010I
ATB70011I
ATB70012I
ATB70013I
ATB70014I
ATB70015I
ATB70016I
ATB70017I
ATB70018I
ATB70020I
ATB70021I
ATB70022I
ATB70023I
ATB70024I
ATB70025I
ATB70026I
ATB70027I
ATB70028I
ATB70030I
ATB70031I
ATB70032I
ATB70033I
ATB70034I
ATB70034I
ATB70035I
ATB70036I
ATB70040I
ATB70041I
ATB70042I
ATB70043I
ATB70044I
ATB70050I
ATB70051I
ATB70052I
ATB70053I
ATB70054I
ATB70055I
ATB70056I
ATB70057I
ATB70058I
ATB70059I
ATB70061I
ATB70999I
Error_Extract (ATB8) Messages
ATB80003I
ATB80004I
ATB80005I
ATB80006I
ATB80008I
ATB80009I
ATB80010I
ATB80011I
ATB80014I
ATB80016I
ATB80020I
ATB80023I
ATB80025I
ATB80026I
ATB80033I
ATB80034I
ATB80036I
ATB80037I
ATB80038I
ATB80039I
ATB80040I
ATB80041I
ATB80042I
ATB80043I
ATB80044I
ATB80045I
ATB80046I
ATB80047I
ATB80048I
ATB80049I
ATB80050I
ATB80051I
ATB80052I
ATB80053I
ATB80054I
ATB80055I
ATB80058I
ATB80059I
ATB80060I
ATB80061I
ATB80062I
ATB80063I
ATB80064I
ATB80065I
ATB80066I
ATB80067I
ATB80068I
ATB80069I
ATB80070I
ATB80071I
ATB80073I
ATB80074I
ATB80075I
ATB80076I
ATB80077I
ATB80078I
ATB80079I
ATB80082I
ATB80083I
ATB80084I
ATB80085I
ATB80086I
ATB80087I
ATB80088I
ATB80089I
ATB80090I
ATB80091I
ATB80092I
ATB80093I
ATB80094I
ATB80095I
ATB80096I
ATB80097I
ATB80098I
ATB80099I
ATB80100I
ATB80101I
ATB80102I
ATB80103I
ATB80104I
ATB80105I
ATB80106I
ATB80107I
ATB80108I
ATB80109I
ATB80110I
ATB80111I
ATB80112I
ATB80114I
ATB80115I
ATB80116I
ATB80117I
ATB80119I
ATB80120I
ATB80121I
ATB80122I
ATB80123I
ATB80124I
ATB80125I
ATB80126I
ATB80127I
ATB80128I
ATB80129I
ATB80130I
ATB80131I
ATB80133I
ATB80134I
ATB80135I
ATB80136I
ATB80138I
ATB80139I
ATB80140I
ATB80141I
ATB80142I
ATB80143I
ATB80144I
ATB80145I
Character Sets
Explanations of Return Codes for CPI Communications Services
APPC/MVS Conversation State Table
Explanation of State-Table Abbreviations
Conversation Characteristics ( )
Return Code Values [ ]
Data_received and Status_received {, }
Table Symbols
How to Use the State Table
Support for SNA LU 6.2 Verbs and Option Sets
Mapping APPC/MVS TP Services to LU 6.2 Verbs and CPI Communications
APPC/MVS Support for LU 6.2 Option Sets
Flush the LU's Send Buffer (101)
Get Attributes (102)
Prepare to Receive (105)
Receive Immediate (106)
Sync Point Services (108)
Get Conversation Type (110)
Queued Allocation of a Conwinner Session (201)
Immediate Allocation of a Session (203)
Conversations between Programs Located at the Same LU (204)
Session-Level LU-LU Verification (211)
User ID Verification (212)
Program Supplied User ID and Password (213)
User ID Authorization (214)
Profile Verification and Authorization (215)
Origin LU Authorization (216)
Profile Passthrough (217)
Program-Supplied Profile (218)
Receive Persistent Verification (220)
Receive SIGNON/Change Password (222)
Accounting (243)
Long Locks (244)
Test for Request-to-Send Received (245)
Vote Read-Only Response to a Sync Point Operation (249)
Extract Transaction and Conversation Identification Information (251)
CHANGE_SESSION_LIMIT Verb (501)
Session-Level Mandatory Cryptography (611)
Previous Versions of APPC/MVS Callable Services
ATBALLC - Allocate (For MVS/ESA 4.2 and 4.2.2)
ATBALC2 - Allocate (For MVS/ESA 4.3 through OS/390 Release 7)
ATBALC5 - Allocate (For OS/390 Release 8 through z/OS V1R6)
ATBCMCTU - Cleanup_TP (Unauthorized, for MVS/ESA 4.2)
ATBGTA2 - Get_Attributes (For MVS/ESA 4.3 through z/OS V1R6)
ATBGETP - Get_TP_Properties (For MVS/ESA 4.2 through OS/390 V1R2)
ATBST05 - Set_TimeOut_Value (For OS/390 Release 8 through z/OS V1R6)