1/20

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

• Overview of the Gateway
• Features of the Gateway
• Terms
• Examples and Sample Files for the Gateway
• Architecture of the Gateway
• Communication with the Gateway
• RPC Functions
  • TIP Function
    • Remote Transaction Initiation
    • Data Exchange
    • Remote Transaction Termination
• Overview of a Gateway Using SNA
  • Transaction Types for a Gateway Using SNA
  • Simple Gateway Communication with the Oracle Database (SNA)
    • Steps to Communicate Between Gateway and Mainframe Using SNA
  • Writing TIPs to Generate PL/SQL Programs Using SNA
    • Steps to Writing a TIP on a Gateway Using SNA
• Overview of a Gateway Using TCP/IP
  • Transaction Types for a Gateway Using TCP/IP
  • Simple Gateway Communication with the Oracle Database (TCP/IP)
    • Preparing the Gateway to Communicate Using TCP/IP
    • Steps to Communication Between the Gateway and IMS, Using TCP/IP
  • Writing TIPs to Generate PL/SQL Programs Using TCP/IP
    • Steps to Writing a TIP on a Gateway Using TCP/IP

2 Procedural Gateway Administration Utility

• Overview of PGAU
• COMMIT/ROLLBACK Processing
  • COMMIT Processing
  • ROLLBACK Processing
• Invoking PGAU
• Definitions and Generation in PGAU
• Process to Define and Test a TIP
  • Definition Names
  • Definition Versioning
  • Keywords
• PGAU Commands
  • CONNECT
  • DEFINE CALL
  • DEFINE DATA
  • DEFINE TRANSACTION
  • DESCRIBE
  • DISCONNECT
  • EXECUTE
  • EXIT
  • GENERATE
  • GROUP
  • HOST
  • PRINT
  • REDEFINE DATA
  • REM
  • REPORT
  • SET
  • SHOW
  • SPOOL
  • UNDEFINE CALL
  • UNDEFINE DATA
  • UNDEFINE TRANSACTION
  • VARIABLE

3 Creating a TIP

• Granting Privileges for TIP Creators
• Evaluating the RHT
  • Identify the Remote Host Transaction
  • PGAU DEFINE CALL Command
  • PGAU DEFINE DATA Command
  • PGAU DEFINE TRANSACTION Command on a Gateway Using SNA
  • PGAU DEFINE TRANSACTION Command on a Gateway Using TCP/IP
  • Writing the PGAU Statements
  • Writing a PGAU Script File
• Defining and Generating the TIP
• Compiling the TIP
• TIP Content Documentation (tipname.doc)

4 Client Application Development (SNA Only)

• Overview of Client Application
• Preparing the Client Application
• Understanding the Remote Host Transaction Requirements
  • TIP Content and Purpose
  • Remote Host Transaction Types
    • One-Shot Transactions
    • Persistent Transactions
    • Multi-Conversational Transactions
• Customized TIPs for Each Remote Host Transaction
• Client Application Requirements
• Ensuring TIP and Remote Transaction Program Correspondence
  • DATA Correspondence
  • CALL Correspondence
    • Flexible Call Sequence
    • Call Correspondence Order Restrictions
  • TRANSACTION Correspondence
• Calling the TIP from the Client Application
  • Declaring TIP Variables
  • Initializing the Conversation
    • Transaction Instance Parameter
    • Overriding TIP Initializations
    • Security Considerations
• Exchanging Data
  • Terminating the Conversation
  • Error Handling
  • Granting Execute Authority
• Executing the Application
• APPC Conversation Sharing
  • APPC Conversation Sharing Concepts
  • APPC Conversation Sharing Usage
  • APPC Conversation Sharing TIP Compatibility
  • APPC Conversation Sharing for TIPs That Are Too Large
  • APPC Conversation Sharing Example
  • APPC Conversation Sharing Overrides and Diagnostics
• Application Development with Multi-Byte Character Set Support
• Modifying a Terminal-Oriented Transaction to Use APPC
• Privileges Needed to Use TIPs

5 Implementing Commit-Confirm (SNA Only)

• Overview of Commit-Confirm
• Supported OLTPs
• Components Required to Support Commit-Confirm
• Application Design Requirements
• Commit-Confirm Architecture
  • Components
  • Interactions
• Commit-Confirm Flow
  • Commit-Confirm Logic Flow, Step by Step
  • Gateway Server Commit-Confirm Transaction Log

6 PG4TCPMAP Commands (TCP/IP Only)

• Preparation for Populating the PGA_TCP_IMSC Table
• Overview
• Populating the PGA_TCP_IMSC Table
• Before You Run the pg4tcpmap Tool
• pg4tcpmap Tool Commands
  • Inserting a Row into the PGA_TCP_IMSC Table
  • Deleting Rows from the PGA_TCP_IMSC Table
  • Querying the PGA_TCP_IMSC Table

7 Client Application Development (TCP/IP Only)

• Overview of Client Application
• Preparing the Client Application
  • TIP Content and Purpose
  • Remote Host Transaction Types
• Ensuring TIP and Remote Transaction Program Correspondence
  • DATA Correspondence
  • CALL Correspondence
    • Flexible Call Sequence
    • Call Correspondence Order Restrictions
  • TRANSACTION Correspondence
• Calling the TIP from the Client Application
  • Declaring TIP Variables
  • Initializing the Conversation
    • Transaction Instance Parameter
    • Overriding TIP Initializations
    • Security Considerations
• Exchanging Data
  • Terminating the Conversation
  • Error Handling
  • Granting Execute Authority
• Calling PG4TCPMAP
• Executing the Application
• Application Development with Multi-Byte Character Set Support
• Privileges Needed to Use TIPs

8 Troubleshooting

• TIP Definition Errors
• Problem Analysis with PG DD Diagnostic References
• Problem Analysis with PG DD Select Scripts
• Data Conversion Errors
• Problem Analysis with TIP Runtime Traces
• TIP Runtime Trace Controls
  • Generating Runtime Data Conversion Trace and Warning Support
  • Controlling TIP Runtime Conversion Warnings
  • Controlling TIP Runtime Function Entry/Exit Tracing
  • Controlling TIP Runtime Data Conversion Tracing
  • Controlling TIP Runtime Gateway Exchange Tracing
• Suppressing TIP Warnings and Tracing
• Problem Analysis of Data Conversion and Truncation Errors
• Gateway Server Tracing
  • Defining the Gateway Trace Destination
  • Enabling the Gateway Trace
    • Enabling the Gateway Trace Using Initialization Parameters
    • Enabling the Gateway Trace Dynamically from PL/SQL

A Database Gateway for APPC Data Dictionary

• PG DD Environment Dictionary
  • Environment Dictionary Sequence Numbers
  • Environment Dictionary Tables
    • pga_maint
    • pga_environments
    • pga_env_attr
    • pga_env_values
    • pga_compilers
    • pga_datatypes
    • pga_datatype_attr
    • pga_datatype_values
    • pga_usage
    • pga_modes
• PG DD Active Dictionary
  • Active Dictionary Versioning
  • Active Dictionary Sequence Numbers
  • Active Dictionary Tables
    • pga_trans
    • pga_trans_attr
    • pga_trans_values
    • pga_trans_calls
    • pga_call
    • pga_call_parm
    • pga_data
    • pga_fields
    • pga_data_attr
    • pga_data_values

B Gateway RPC Interface

• Calling Gateway Functions to Execute Transaction Programs
  • PGAINIT and PGAINIT_SEC
  • PGAXFER
  • PGATERM
  • PGATCTL
  • PGATRAC

C The UTL_PG Interface

• UTL_PG Functions
  • Common Parameters
    • Common Input Parameters
    • Common Output Parameter
  • RAW_TO_NUMBER
  • NUMBER_TO_RAW
  • MAKE_RAW_TO_NUMBER_FORMAT
  • MAKE_NUMBER_TO_RAW_FORMAT
  • RAW_TO_NUMBER_FORMAT
  • NUMBER_TO_RAW_FORMAT
  • WMSGCNT
  • WMSG
• NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values

D Datatype Conversions

• Length Checking
  • Parameters Over 32K in Length
• Conversion
  • USAGE(PASS)
  • USAGE(ASIS)
  • USAGE(SKIP)
  • PL/SQL Naming Algorithms

E Tip Internals

• Background Reading
• PL/SQL Package and TIP File Separation
  • Independent TIP Body Changes
    • Determine if a Specification Has Remained Valid
  • Dependent TIP Body or Specification Changes
    • Recompile the TIP Body
  • Inadvertent Alteration of TIP Specification

F Administration Utility Samples

• Sample PGAU DEFINE DATA Statements
• Sample PGAU DEFINE CALL Statements
• Sample PGAU DEFINE TRANSACTION Statement
• Sample PGAU GENERATE Statement
• Sample Implicit Versioning Definitions
• Sample PGAU REDEFINE DATA Statements
• Sample PGAU UNDEFINE Statements

Index