Contents

List of Figures

List of Tables

Title and Copyright Information

Preface

• Intended Audience
• Documentation Accessibility
• Related Documents
• Legacy Compilers
• Conventions

1 Introduction to Oracle Database Gateway for APPC

• 1.1 Overview of the Gateway
• 1.2 Features of the Gateway
• 1.3 Terms
• 1.4 Examples and Sample Files for the Gateway
• 1.5 Architecture of the Gateway
• 1.6 Communication with the Gateway
• 1.7 RPC Functions
  • 1.7.1 TIP Function
    • 1.7.1.1 Remote Transaction Initiation
    • 1.7.1.2 Data Exchange
    • 1.7.1.3 Remote Transaction Termination
• 1.8 Overview of a Gateway Using SNA
  • 1.8.1 Transaction Types for a Gateway Using SNA
  • 1.8.2 Simple Gateway Communication with the Oracle Database (SNA)
    • 1.8.2.1 Steps to Communicate Between Gateway and Mainframe Using SNA
  • 1.8.3 Writing TIPs to Generate PL/SQL Programs Using SNA
    • 1.8.3.1 Steps to Writing a TIP on a Gateway Using SNA
• 1.9 Overview of a Gateway Using TCP/IP
  • 1.9.1 Transaction Types for a Gateway Using TCP/IP
  • 1.9.2 Simple Gateway Communication with the Oracle Database (TCP/IP)
    • 1.9.2.1 Preparing the Gateway to Communicate Using TCP/IP
    • 1.9.2.2 Steps to Communication Between the Gateway and IMS, Using TCP/IP
  • 1.9.3 Writing TIPs to Generate PL/SQL Programs Using TCP/IP
    • 1.9.3.1 Steps to Writing a TIP on a Gateway Using TCP/IP

2 Procedural Gateway Administration Utility

• 2.1 Overview of PGAU
• 2.2 COMMIT/ROLLBACK Processing
  • 2.2.1 COMMIT Processing
  • 2.2.2 ROLLBACK Processing
• 2.3 Invoking PGAU
• 2.4 Definitions and Generation in PGAU
• 2.5 Process to Define and Test a TIP
  • 2.5.1 Definition Names
  • 2.5.2 Definition Versioning
  • 2.5.3 Keywords
• 2.6 PGAU Commands
  • 2.6.1 CONNECT
  • 2.6.2 DEFINE CALL
  • 2.6.3 DEFINE DATA
  • 2.6.4 DEFINE TRANSACTION
  • 2.6.5 DESCRIBE
  • 2.6.6 DISCONNECT
  • 2.6.7 EXECUTE
  • 2.6.8 EXIT
  • 2.6.9 GENERATE
  • 2.6.10 GROUP
  • 2.6.11 HOST
  • 2.6.12 PRINT
  • 2.6.13 REDEFINE DATA
  • 2.6.14 REM
  • 2.6.15 REPORT
  • 2.6.16 SET
  • 2.6.17 SHOW
  • 2.6.18 SPOOL
  • 2.6.19 UNDEFINE CALL
  • 2.6.20 UNDEFINE DATA
  • 2.6.21 UNDEFINE TRANSACTION
  • 2.6.22 VARIABLE

3 Creating a TIP

• 3.1 Granting Privileges for TIP Creators
• 3.2 Evaluating the RHT
  • 3.2.1 Identify the Remote Host Transaction
  • 3.2.2 PGAU DEFINE CALL Command
  • 3.2.3 PGAU DEFINE DATA Command
  • 3.2.4 PGAU DEFINE TRANSACTION Command on a Gateway Using SNA
  • 3.2.5 PGAU DEFINE TRANSACTION Command on a Gateway Using TCP/IP
  • 3.2.6 Writing the PGAU Statements
  • 3.2.7 Writing a PGAU Script File
• 3.3 Defining and Generating the TIP
• 3.4 Compiling the TIP
• 3.5 TIP Content Documentation (tipname.doc)

4 Client Application Development (SNA Only)

• 4.1 Overview of Client Application
• 4.2 Preparing the Client Application
• 4.3 Understanding the Remote Host Transaction Requirements
  • 4.3.1 TIP Content and Purpose
  • 4.3.2 Remote Host Transaction Types
    • 4.3.2.1 One-Shot Transactions
    • 4.3.2.2 Persistent Transactions
    • 4.3.2.3 Multi-Conversational Transactions
• 4.4 Customized TIPs for Each Remote Host Transaction
• 4.5 Client Application Requirements
• 4.6 Ensuring TIP and Remote Transaction Program Correspondence
  • 4.6.1 DATA Correspondence
  • 4.6.2 CALL Correspondence
    • 4.6.2.1 Flexible Call Sequence
    • 4.6.2.2 Call Correspondence Order Restrictions
  • 4.6.3 TRANSACTION Correspondence
• 4.7 Calling the TIP from the Client Application
  • 4.7.1 Declaring TIP Variables
  • 4.7.2 Initializing the Conversation
    • 4.7.2.1 Transaction Instance Parameter
    • 4.7.2.2 Overriding TIP Initializations
    • 4.7.2.3 Security Considerations
• 4.8 Exchanging Data
  • 4.8.1 Terminating the Conversation
  • 4.8.2 Error Handling
  • 4.8.3 Granting Execute Authority
• 4.9 Executing the Application
• 4.10 APPC Conversation Sharing
  • 4.10.1 APPC Conversation Sharing Concepts
  • 4.10.2 APPC Conversation Sharing Usage
  • 4.10.3 APPC Conversation Sharing TIP Compatibility
  • 4.10.4 APPC Conversation Sharing for TIPs That Are Too Large
  • 4.10.5 APPC Conversation Sharing Example
  • 4.10.6 APPC Conversation Sharing Overrides and Diagnostics
• 4.11 Application Development with Multi-Byte Character Set Support
• 4.12 Modifying a Terminal-Oriented Transaction to Use APPC
• 4.13 Privileges Needed to Use TIPs

5 Implementing Commit-Confirm (SNA Only)

• 5.1 Overview of Commit-Confirm
• 5.2 Supported OLTPs
• 5.3 Components Required to Support Commit-Confirm
• 5.4 Application Design Requirements
• 5.5 Commit-Confirm Architecture
  • 5.5.1 Components
  • 5.5.2 Interactions
• 5.6 Commit-Confirm Flow
  • 5.6.1 Commit-Confirm Logic Flow, Step by Step
  • 5.6.2 Gateway Server Commit-Confirm Transaction Log

6 PG4TCPMAP Commands (TCP/IP Only)

• 6.1 Preparation for Populating the PGA_TCP_IMSC Table
• 6.2 Overview
• 6.3 Populating the PGA_TCP_IMSC Table
• 6.4 Before You Run the pg4tcpmap Tool
• 6.5 pg4tcpmap Tool Commands
  • 6.5.1 Inserting a Row into the PGA_TCP_IMSC Table
  • 6.5.2 Deleting Rows from the PGA_TCP_IMSC Table
  • 6.5.3 Querying the PGA_TCP_IMSC Table

7 Client Application Development (TCP/IP Only)

• 7.1 Overview of Client Application
• 7.2 Preparing the Client Application
  • 7.2.1 TIP Content and Purpose
  • 7.2.2 Remote Host Transaction Types
• 7.3 Ensuring TIP and Remote Transaction Program Correspondence
  • 7.3.1 DATA Correspondence
  • 7.3.2 CALL Correspondence
    • 7.3.2.1 Flexible Call Sequence
    • 7.3.2.2 Call Correspondence Order Restrictions
  • 7.3.3 TRANSACTION Correspondence
• 7.4 Calling the TIP from the Client Application
  • 7.4.1 Declaring TIP Variables
  • 7.4.2 Initializing the Conversation
    • 7.4.2.1 Transaction Instance Parameter
    • 7.4.2.2 Overriding TIP Initializations
    • 7.4.2.3 Security Considerations
• 7.5 Exchanging Data
  • 7.5.1 Terminating the Conversation
  • 7.5.2 Error Handling
  • 7.5.3 Granting Execute Authority
• 7.6 Calling PG4TCPMAP
• 7.7 Executing the Application
• 7.8 Application Development with Multi-Byte Character Set Support
• 7.9 Privileges Needed to Use TIPs

8 Troubleshooting

• 8.1 TIP Definition Errors
• 8.2 Problem Analysis with PG DD Diagnostic References
• 8.3 Problem Analysis with PG DD Select Scripts
• 8.4 Data Conversion Errors
• 8.5 Problem Analysis with TIP Runtime Traces
• 8.6 TIP Runtime Trace Controls
  • 8.6.1 Generating Runtime Data Conversion Trace and Warning Support
  • 8.6.2 Controlling TIP Runtime Conversion Warnings
  • 8.6.3 Controlling TIP Runtime Function Entry/Exit Tracing
  • 8.6.4 Controlling TIP Runtime Data Conversion Tracing
  • 8.6.5 Controlling TIP Runtime Gateway Exchange Tracing
• 8.7 Suppressing TIP Warnings and Tracing
• 8.8 Problem Analysis of Data Conversion and Truncation Errors
• 8.9 Gateway Server Tracing
  • 8.9.1 Defining the Gateway Trace Destination
  • 8.9.2 Enabling the Gateway Trace
    • 8.9.2.1 Enabling the Gateway Trace Using Initialization Parameters
    • 8.9.2.2 Enabling the Gateway Trace Dynamically from PL/SQL

A Database Gateway for APPC Data Dictionary

• A.1 PG DD Environment Dictionary
  • A.1.1 Environment Dictionary Sequence Numbers
  • A.1.2 Environment Dictionary Tables
    • A.1.2.1 pga_maint
    • A.1.2.2 pga_environments
    • A.1.2.3 pga_env_attr
    • A.1.2.4 pga_env_values
    • A.1.2.5 pga_compilers
    • A.1.2.6 pga_datatypes
    • A.1.2.7 pga_datatype_attr
    • A.1.2.8 pga_datatype_values
    • A.1.2.9 pga_usage
    • A.1.2.10 pga_modes
• A.2 PG DD Active Dictionary
  • A.2.1 Active Dictionary Versioning
  • A.2.2 Active Dictionary Sequence Numbers
  • A.2.3 Active Dictionary Tables
    • A.2.3.1 pga_trans
    • A.2.3.2 pga_trans_attr
    • A.2.3.3 pga_trans_values
    • A.2.3.4 pga_trans_calls
    • A.2.3.5 pga_call
    • A.2.3.6 pga_call_parm
    • A.2.3.7 pga_data
    • A.2.3.8 pga_fields
    • A.2.3.9 pga_data_attr
    • A.2.3.10 pga_data_values

B Gateway RPC Interface

• B.1 Calling Gateway Functions to Execute Transaction Programs
  • B.1.1 PGAINIT and PGAINIT_SEC
  • B.1.2 PGAXFER
  • B.1.3 PGATERM
  • B.1.4 PGATCTL
  • B.1.5 PGATRAC

C The UTL_PG Interface

• C.1 UTL_PG Functions
  • C.1.1 Common Parameters
    • C.1.1.1 Common Input Parameters
    • C.1.1.2 Common Output Parameter
  • C.1.2 RAW_TO_NUMBER
  • C.1.3 NUMBER_TO_RAW
  • C.1.4 MAKE_RAW_TO_NUMBER_FORMAT
  • C.1.5 MAKE_NUMBER_TO_RAW_FORMAT
  • C.1.6 RAW_TO_NUMBER_FORMAT
  • C.1.7 NUMBER_TO_RAW_FORMAT
  • C.1.8 WMSGCNT
  • C.1.9 WMSG
• C.2 NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values

D Datatype Conversions

• D.1 Length Checking
  • D.1.1 Parameters Over 32K in Length
• D.2 Conversion
  • D.2.1 USAGE(PASS)
  • D.2.2 USAGE(ASIS)
  • D.2.3 USAGE(SKIP)
  • D.2.4 PL/SQL Naming Algorithms

E Tip Internals

• E.1 Background Reading
• E.2 PL/SQL Package and TIP File Separation
  • E.2.1 Independent TIP Body Changes
    • E.2.1.1 Determine if a Specification Has Remained Valid
  • E.2.2 Dependent TIP Body or Specification Changes
    • E.2.2.1 Recompile the TIP Body
  • E.2.3 Inadvertent Alteration of TIP Specification

F Administration Utility Samples

• F.1 Sample PGAU DEFINE DATA Statements
• F.2 Sample PGAU DEFINE CALL Statements
• F.3 Sample PGAU DEFINE TRANSACTION Statement
• F.4 Sample PGAU GENERATE Statement
• F.5 Sample Implicit Versioning Definitions
• F.6 Sample PGAU REDEFINE DATA Statements
• F.7 Sample PGAU UNDEFINE Statements

Index