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
ATB70017I
ATB70018I
ATB70033I
Error_Extract (ATB8) Messages
ATB80003I
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)