Contents

Title and Copyright Information

Preface

• Intended Audience
• Documentation Accessibility
• Related Documents
• Conventions
• Accessing Installed Documentation
• Oracle Services and Support

1 Introduction to Oracle Procedural 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 Starting the Gateway
• 1.7 Communication With the Gateway
• 1.8 Remote Procedural Call Functions
• • 1.8.1 TIP Function
  • • 1.8.1.1 Remote Transaction Initiation
    • 1.8.1.2 Data Exchange
    • 1.8.1.3 Remote Transaction Termination
• 1.9 Overview of a Gateway Using SNA
• • 1.9.1 Transaction Types for a Gateway Using SNA
• 1.10 Simple Gateway Communication With the Oracle Server (SNA)
• • 1.10.1 Steps to Communication Between Gateway and Mainframe, Using SNA
• 1.11 Writing TIPs to Generate PL/SQL Programs on Gateway Using SNA
• • 1.11.1 Steps to Writing a TIP on a Gateway Using SNA
• 1.12 Overview of a Gateway Using TCP/IP
• • 1.12.1 Transaction Types for a Gateway Using TCP/IP
• 1.13 Simple Gateway Communication with the Oracle Server (TCP/IP)
• • 1.13.1 Preparing the Gateway to Communicate Using TCP/IP
  • 1.13.2 Steps to Communication Between the Gateway and IMS, Using TCP/IP
• 1.14 Writing TIPs to Generate PL/SQL Programs on Gateway Using TCP/IP
• • 1.14.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 Problem Determination

• 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 of Data Conversion and Truncation Errors
• 8.6 Problem Analysis with TIP Runtime Traces
• 8.7 TIP Runtime Trace Controls
• • 8.7.1 Generating Runtime Data Conversion Trace and Warning Support
  • 8.7.2 Controlling TIP Runtime Conversion Warnings
  • 8.7.3 Controlling TIP Runtime Function Entry/Exit Tracing
  • 8.7.4 Controlling TIP Runtime Data Conversion Tracing
  • 8.7.5 Controlling TIP Runtime Gateway Exchange Tracing
• 8.8 Suppressing TIP Warnings and Tracing
• 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
• 8.10 Sample Gateway Server Initialization and Trace Output Files
• • 8.10.1 Sample Trace Output File for Gateway Using SNA
  • 8.10.2 Sample Trace Output File for Gateway Using TCP/IP
  • 8.10.3 Sample Output Log for pg4tcpmap Tool

A Procedural 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 and UTL_RAW Interface

• C.1 UTL_RAW Functions
• • C.1.1 BIT_AND
  • C.1.2 BIT_COMPLEMENT
  • C.1.3 BIT_OR
  • C.1.4 BIT_XOR
  • C.1.5 CAST_TO_RAW
  • C.1.6 CAST_TO_VARCHAR2
  • C.1.7 COMPARE
  • C.1.8 CONCAT
  • C.1.9 CONVERT
  • C.1.10 COPIES
  • C.1.11 LENGTH
  • C.1.12 OVERLAY
  • C.1.13 REVERSE
  • C.1.14 SUBSTR
  • C.1.15 TRANSLATE
  • C.1.16 TRANSLITERATE
  • C.1.17 XRANGE
• C.2 UTL_PG Functions
• • C.2.1 Common Parameters
  • • C.2.1.1 Common Input Parameters
    • C.2.1.2 Common Output Parameter
  • C.2.2 RAW_TO_NUMBER
  • C.2.3 NUMBER_TO_RAW
  • C.2.4 MAKE_RAW_TO_NUMBER_FORMAT
  • C.2.5 MAKE_NUMBER_TO_RAW_FORMAT
  • C.2.6 RAW_TO_NUMBER_FORMAT
  • C.2.7 NUMBER_TO_RAW_FORMAT
  • C.2.8 WMSGCNT
  • C.2.9 WMSG
• C.3 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 National Language Support

• E.1 Overview
• E.2 Languages Supported for Messages
• E.3 Languages Supported for Data Conversion

F Tip Internals

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

G Administration Utility Samples

• G.1 Sample PGAU DEFINE DATA Statements
• G.2 Sample PGAU DEFINE CALL Statements
• G.3 Sample PGAU DEFINE TRANSACTION Statement
• G.4 Sample PGAU GENERATE Statement
• G.5 Sample Implicit Versioning Definitions
• G.6 Sample PGAU REDEFINE DATA Statements
• G.7 Sample PGAU UNDEFINE Statements
• G.8 Sample PGAU REPORT Output
• G.9 Sample TIP Content Documentation
• G.10 Sample TIP Trace Output
• G.11 Sample TIP Output

Index