Contents

Title and Copyright Information

Send Us Your Comments

Preface

Intended Audience

Related Publications

Conventions

Documentation Accessibility

1 Introduction to Oracle Procedural Gateway for APPC

Overview

Terms

Examples and Sample Files

Features

Architecture

Starting the Gateway

Communication

Remote Procedural Call Functions

Remote Transaction Initiation

Data Exchange

Remote Transaction Termination

Transaction Types

Simple Communication Between Mainframe and Oracle Integrating Server

Steps to Communication Between Oracle Server and Mainframe

Writing TIPs to Generate PL/SQL Programs

2 Procedural Gateway Administration Utility

Overview of PGAU

COMMIT/ROLLBACK Processing

COMMIT Processing

ROLLBACK Processing

Invoking PGAU

Definitions and Generation

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

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

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

Overview of Commit-Confirm

Supported OLTPs

Required Components

Configuring Commit-Confirm

Configuring the Oracle Integrating Server

Configuring the Gateway Initialization Parameters

Configuring the OLTP

Application Design Requirements

Commit-Confirm Architecture

Components

Interactions

Commit-Confirm Flow

Commit-Confirm Logic Flow, Step by Step

Gateway Server Commit-Confirm Transaction Log

Sample Applications

6 Problem Determination

TIP Definition Errors

Problem Analysis with PG DD Diagnostic References

Problem Analysis with PG DD Select Scripts

Data Conversion Errors

Problem Analysis of Data Conversion and Truncation 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

Gateway Server Tracing

Defining the Gateway Trace Destination

Enabling the Gateway Trace

Enabling the APPC Trace Using Initialization Parameters

Enabling the APPC Trace Dynamically from PL/SQL

Sample Gateway Server Initialization and Trace Output Files

A Procedural Gateway for APPC Data Dictionary

PG DD Environment Dictionary

Environment Dictionary Sequence Numbers

Environment Dictionary Tables

PG DD Active Dictionary

Active Dictionary Versioning

Active Dictionary Sequence Numbers

Active Dictionary Tables

B TIP Internals

Background Reading

PL/SQL Package and TIP File Separation

Independent TIP Body Changes

Dependent TIP Body or Specification Changes

Inadvertent Alteration of TIP Specification

TIP Call to APPC Call Relationship

TIP Function Calls and Remote Transaction Program APPC Calls

Parameter Datatype Conversion

APPC Send/Receive Synchronization

Oracle Procedural Gateway for APPC Restrictions

TIP Specification

TIP Body

TIP Initialization

TIP Init and Term Functions

TIP Initialization Function

TIP Terminate Function

C Gateway RPC Interface

Calling Gateway Functions to Execute Transaction Programs

PGAINIT and PGAINIT_SEC

PGAXFER

PGATERM

PGATCTL

PGATRAC

D The UTL_PG and UTL_RAW Interfaces

UTL_RAW Functions

BIT_AND

BIT_COMPLEMENT

BIT_OR

BIT_XOR

CAST_TO_RAW

CAST_TO_VARCHAR2

COMPARE

CONCAT

CONVERT

COPIES

LENGTH

OVERLAY

REVERSE

SUBSTR

TRANSLATE

TRANSLITERATE

XRANGE

UTL_PG Functions

Common Parameters

Input Parameters

Output Parameters

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

E 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

Sample PGAU REPORT Output

Sample PGAU Script File (pgadb2i.ctl)

Sample TIP Content Documentation

Sample TIP Trace Output

Sample TIP Output

F CICS APPC Transaction Samples

Description of Sample CICS APPC Transaction

COBOL Source Code

Sample pgacics.sql File

G Datatype Conversions

Procedural Gateway for APPC Components

Length Checking

Parameters Over 32K in Length

Conversion

USAGE(PASS)

Datatype Conversion

Alphanumeric and DBCS Editing Field Positions

Format Conversion

USAGE(ASIS)

USAGE(SKIP)

PL/SQL Naming Algorithms

Delimiters

Qualified Compound Names

Truncated and Non-Unique Names

Duplicate Names

H National Language Support

Overview

Languages Supported for Messages

Languages Supported for Data Conversion

Index