Skip Headers
Oracle Procedural Gateway® for APPC User's Guide
10g Release 2 (10.2) for Microsoft Windows (32-Bit)

Part Number B16212-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

1 Introduction to Oracle Procedural Gateway for APPC

This guide is intended for for Microsoft Windows (32-Bit) users.

Refer to the Oracle Database Installation Guide 10g Release 2 (10.2) for Microsoft Windows (32-Bit) and to the certification matrix on the OracleMetaLink Web site for the most up-to-date list of certified hardware platforms and operating system versions. The OracleMetaLink Web site can be found at:

http://metalink.oracle.com

The Oracle Procedural Gateway for APPC (the "gateway") enables users to initiate transaction program execution on remote online transaction processors (OLTPs). The Oracle Procedural Gateway for APPC can establish connection with OLTP using the SNA communication protocol. The gateway can also use TCP/IP for IMS Connect to establish communication with IMS/TM through TCP/IP. The gateway provides Oracle applications with seamless access to IBM mainframe data and services through Remote Procedural Call (RPC) processing.

Read this chapter to learn more about the architecture, uses, and features of the Oracle Procedural Gateway for APPC.

This chapter contains the following sections:

1.1 Overview of the Gateway

The Oracle Procedural Gateway for APPC extends the Remote Procedural Call (RPC) facilities available with the Oracle server. The gateway enables any client application to use PL/SQL to request execution of a remote transaction program (RTP) residing on a host. The gateway provides RPC processing to systems using the SNA APPC (Advanced Program-to-Program Communication) protocol and to IMS/TM systems using TCP/IP support for IMS Connect. This architecture allows efficient access to data and transactions available on the IBM mainframe and IMS, respectively.

The gateway requires no Oracle software on the remote host system. Thus, the gateway uses existing transactions with little or no programming effort on the remote host.

1.2 Features of the Gateway

The Oracle Procedural Gateway for APPC provides the following benefits:

1.3 Terms

The following terms and definitions are used throughout this guide:

Gateway Initialization File

This file is known as initsid.ora and it contains parameters that govern the operation of the gateway. If you are using the SNA protocol, refer to Appendix A, "Gateway Initialization Parameters for SNA Protocol" in the Oracle Procedural Gateway for APPC Installation and Configuration Guide for more information. If your protocol is TCP/IP, refer to Appendix B, "Gateway Initialization Parameters for TCP/IP Communication Protocol" in the Oracle Procedural Gateway for APPC Installation and Configuration Guide.

Gateway Remote Procedure

The Oracle Procedural Gateway for APPC provides prebuilt remote procedures. In general, the following three remote procedures are used:

Refer to Appendix B, "Gateway RPC Interface" in this guide and to "Remote Procedural Call Functions" in Chapter 1 of the Oracle Procedural Gateway for APPC Installation and Configuration Guide for more information about gateway remote procedures.

tg4pwd

tg4pwd is a utility which encrypts passwords that are normally stored in the gateway initialization file. Passwords are stored in an encrypted form in the password file, making the information more secure. Refer to "Passwords in the Gateway Initialization File" in the security requirements chapter of the Oracle Procedural Gateway for APPC Installation and Configuration Guide for detailed information about how the tg4pwd utility works.

pg4tcpmap Tool

This tool is applicable only when the gateway is using TCP/IP support for IMS Connect. Its function is to map SNA parameters (such as Side Profile Name) to TCP/IP parameters (such as OLTP host name, IMS Connect port number and IMS destination ID).

PGA (Procedural Gateway Administration)

PGA is a general reference within this guide to all or most components comprising the Oracle Procedural Gateway for APPC. This term is used when references to a specific product or component are too narrow.

PGDL (Procedural Gateway Definition Language)

PGDL is the collection of statements used to define transactions and data to the PGAU.

PL/SQL Stored Procedure Specification (PL/SQL package)

This is a precompiled PL/SQL procedure that is stored in Oracle Integrating Server.

UTL_RAW PL/SQL Package (the UTL_RAW Functions)

This component of the gateway represents a series of data conversion functions for PL/SQL RAW variables and remote host data. The types of conversions performed depend on the language of the remote host data. Refer to Appendix D, "Datatype Conversions" in this guide for more information.

UTL_PG PL/SQL Package (the UTL_PG Functions)

This component of the gateway represents a series of COBOL numeric data conversion functions. Refer to "NUMBER_TO_RAW and RAW_TO_NUMBER Argument Values" in Appendix C of this guide for supported numeric datatype conversions.

Oracle Integrating Server

This is any Oracle server instance that communicates with the gateway for purposes of performing remote procedural calls to execute remote transaction programs (RTP). The Oracle Integrating Server can be on the same system as the gateway or on a different system. If it is on a different system, then Oracle Net is required on both systems. Refer to Figure 1-2, "Gateway Architecture Featuring SNA or TCP/IP Protocol" for a view of the gateway architecture.

OLTP (Online Transaction Processor)

OLTP is any of a number of online transaction processors available from other vendors, including CICS Transaction Server for z/OS, IMS/TM, and IDMS-DC.

Note:

When your communications protocol is TCP/IP, only IMS is supported as the Online Transaction Processor (OLTP).

PGAU (Procedural Gateway Administration Utility)

PGAU is the tool that is used to define and generate PL/SQL transaction interface packages (TIPs). Refer to Chapter 2, "Procedural Gateway Administration Utility" in this guide for more information about PGAU.

PG DD (Data Dictionary)

This component of the gateway is a repository of remote host transaction definitions and data definitions. PGAU accesses definitions in the PG DD when generating TIPs. The PG DD has datatype dependencies because it supports the PGAU and is not intended to be directly accessed by the customer. Refer to Appendix A, "Procedural Gateway for APPC Data Dictionary" in this guide for a list of PG DD tables.

RPC (Remote Procedural Call)

RPC is a programming call that executes program logic on one system in response to a request from another system. Refer to "Gateway Remote Procedure" in Appendix C of the Oracle Procedural Gateway for APPC Installation and Configuration Guide, and to Appendix B, "Gateway RPC Interface" in this guide for more information.

RTP (Remote Transaction Program)

A remote transaction program is a customer-written transaction, running under the control of an OLTP, which the user invokes remotely using a PL/SQL procedure. To execute a remote transaction program through the gateway, you must use RPC to execute a PL/SQL program to call the gateway functions.

TIP (Transaction Interface Package)

A TIP is an Oracle PL/SQL package that exists between your application and the remote transaction program. The transaction interface package, or TIP, is a set of PL/SQL stored procedures that invoke the remote transaction program through the gateway. TIPs perform the conversion and reformatting of remote host data using PL/SQL and UTL_RAW/UTL_PG functions.

Figure 1-1 illustrates where the terminology discussed in the preceding sections applies to the gateway's architecture.

Figure 1-1 Relationship of Gateway and Oracle Integrating Server on Windows

Description of Figure 1-1 follows
Description of "Figure 1-1 Relationship of Gateway and Oracle Integrating Server on Windows"

1.4 Examples and Sample Files for the Gateway

The following sample files and examples are referred to for illustration purposes throughout this guide. There are different example and sample files for a gateway using the SNA protocol than for a gateway using TCP/IP for IMS Connect.

Examples and Sample Files for Gateway Using SNA

For gateways using the SNA communication protocol, this guide uses a CICS-DB2 inquiry as an example. Transaction Interface Packages (TIPs) pgadb2i.pkb and pgadb2i.pkh send an employee number, empno, to a DB2 application and receive an employee record, emprec.

The CICS-DB2 inquiry sample and its associated PGAU commands are also available in the %ORACLE_HOME%\pg4appc\demo\CICS directory. The sample CICS-DB2 inquiry used as an example in this chapter is in files pgadb2i.pkh and pgadb2i.pkb. Refer to the README.doc file in the same directory for information about installing and using the samples. It can be found in the %ORACLE_HOME%pg4appc\demo\CICS directory.

Examples and Sample Files for Gateway Using TCP/IP

If your gateway is using the TCP/IP communication protocol, this guide uses an IMS inquiry as an example. Transaction Interface Packages (TIPs) pgtflip.pkh and pgtflip.pkb send input to IMS, through IMS Connect, and receive the flipped input as the output.

The IMS inquiry sample (FLIP) and its associated PGAU commands are located in the %ORACLE_HOME%\pg4appc\demo\IMS directory. The sample IMS inquiry used as an example for a gateway using TCP/IP is located in files pgtflip.pkh and pgtflip.pkb.

Refer to the README.doc file for more information about installing and using other IMS samples. It can be found in the %ORACLE_HOME%\pg4appc\demo\IMS directory.

1.5 Architecture of the Gateway

The architecture of Oracle Procedural Gateway for APPC consists of several components:

  1. Oracle Integrating Server

    Refer to the configuration chapter appropriate to your communications protocol in the Oracle Procedural Gateway for APPC Installation and Configuration Guide for a description of the various methods for establishing the gateway-Oracle Integrating Server relationship.

    The Oracle Integrating Server can also be used for non-gateway applications.

  2. The gateway

    Oracle Procedural Gateway for APPC must be installed on a server that can run the required version of the operating system.

  3. An OLTP (online transaction processor)

    The OLTP must be accessible from the gateway using your SNA or TCP/IP communication protocol. Multiple Oracle Integrating Servers can access the same gateway. A single system gateway installation can be configured to access more than one OLTP.

    • For gateway using TCP/IP for IMS Connect: The only OLTP that is supported through TCP/IP is IMS through IMS Connect.The OLTP must be accessible to the system using the TCP/IP protocol. Multiple Oracle Integrating Servers can access the same gateway. A single system gateway installation can be configured to access more than one OLTP. Multiple IMS can be accessed from an IMS Connect. If you have a number of IMS Connect systems available, any of these may be connected to one or more IMS systems.

Figure 1-2 illustrates the architecture of the Oracle Procedural Gateway for APPC using SNA or TCP/IP, as described in the previous section.

Figure 1-2 Gateway Architecture Featuring SNA or TCP/IP Protocol

Description of Figure 1-2 follows
Description of "Figure 1-2 Gateway Architecture Featuring SNA or TCP/IP Protocol"

1.6 Starting the Gateway

Because the gateway does not have background processes and doesn't need a management utility such as Oracle Enterprise Manager, you needn't "start" the gateway. Each Oracle Integrating Server user session that accesses a particular gateway creates an independent process on Windows that runs the gateway server and executes either the SNA or ­TCP/IP functions to communicate with an OLTP, depending upon your protocol.

1.7 Communication With the Gateway

All of the communication between the user or client program and the gateway is handled through a transaction interface package (TIP) which executes on an Oracle Integrating Server. The TIP is a standard PL/SQL package that provides the following functions:

The Procedural Gateway Administration Utility (PGAU), provided with the gateway, automatically generates the TIP specification.

The gateway is identified to the Oracle Integrating Server using a database link. The database link is the same construct used to identify other Oracle server databases. The functions in the gateway are referenced in PL/SQL as:

function_name@dblink_name 

1.8 Remote Procedural Call Functions

The Oracle Procedural Gateway for APPC provides a set of functions that are invoked by the client through remote procedural call (RPC). These functions direct the gateway to initiate, transfer data with, and terminate remote transaction programs running under an OLTP on another system.

Table 1-1 lists the remote procedural call functions and the correlating commands that are invoked in the gateway and remote host.

Table 1-1 RPC Functions and Commands in the Gateway and Remote Host

Applications Oracle TIP Gateway Remote Host

call tip_init

tip_init

call pgainit@gateway

PGAINIT

Initiate program

call tip_main

tip_main

call pgaxfer@gateway

PGAXFER

Exchange data

call tip_term

tip_term

call pgaterm@gateway

PGATERM

Terminate program


1.8.1 TIP Function

The following sections describe how a TIP works by first establishing a connection to the remote host, then exchanging data from the target transaction program and finally, terminating a conversation.

1.8.1.1 Remote Transaction Initiation

The TIP initiates a connection to the remote host using one of the gateway functions, PGAINIT.

When the communication protocol is SNA: PGAINIT provides, as input, the required SNA parameters to start a conversation with the target transaction program. These parameters are sent across the SNA network, which returns a conversation identifier to PGAINIT. Any future calls to the target program use the conversation identifier as an INPUT parameter.

When the communication protocol is TCP/IP: PGAINIT provides, as input, the required TCP/IP parameters.These parameters are sent across the TCP/IP network to start the conversation with the target transaction program; the TCP/IP network returns a socket file descriptor to PGAINIT. Any future calls, such as PGAXFER and PGATERM, use this same socket file descriptor as an input parameter.

1.8.1.2 Data Exchange

After the conversation is established, a procedural gateway function called PGAXFER can exchange data in the form of input and output variables. PGAXFER sends and receives buffers to and from the target transaction program. The gateway sees a buffer as only a RAW stream of bytes. The TIP that is residing in the Oracle Integrating Server is responsible for converting the application's PL/SQL datatypes to RAW before sending the buffer to the gateway. It is also responsible for converting RAW to the PL/SQL datatypes before returning the results to the application.

1.8.1.3 Remote Transaction Termination

When communication with the remote program is complete, the gateway function PGATERM terminates the conversation between the gateway and the remote host.

When the communication protocol is SNA: PGATERM uses the conversation identifier as an INPUT parameter to request conversation termination.

When the communication protocol is TCP/IP: PGATERM uses the socket file descriptor for TCP/IP as an INPUT parameter to request conversation termination.

1.9 Overview of a Gateway Using SNA

If you are using the SNA communication protocol, read the following sections to develop an understanding of how the gateway communicates with the Oracle Integrating Server and with the mainframe, as well as transaction types unique to your gateway and writing TIPs.

1.9.1 Transaction Types for a Gateway Using SNA

The Oracle Procedural Gateway for APPC supports three types of transactions that read data from and write data to remote host systems:

  • one-shot

    In a one-shot transaction, the application initializes the connection, exchanges data and terminates the connection, all in a single call.

  • persistent

    In a persistent transaction, multiple calls to exchange data with the remote transaction can be executed before terminating the conversation.

  • multi-conversational

    In a multi-conversation transaction, the procedural gateway server can be used to exchange multiple records in one call to the remote transaction program.

Refer to "Remote Host Transaction Types" in Chapter 4, "Client Application Development (SNA Only)" of this guide for more information about transaction types.

The following list demonstrates examples of the power of the Oracle Procedural Gateway for APPC:

  • You can initiate a CICS transaction on the mainframe to retrieve data from a VSAM file for a PC application.

  • You can modify and monitor the operation of a remote process control computer.

  • You can initiate an IMS/TM transaction that executes static SQL in DB2.

  • You can initiate a CICS transaction that returns a large number of records in a single call.

1.10 Simple Gateway Communication With the Oracle Server (SNA)

This section describes simple communication between the mainframe and the Oracle Integrating Server on a gateway using the SNA communication protocol. The Oracle Procedural Gateway for APPC lets you write your own procedures to begin transferring information between the Oracle Integrating Server and a variety of programs on an IBM mainframe, including IBM CICS, IMS, and APPC/MVS.

For an illustration of the communications function of the Oracle Procedural Gateway for APPC, refer to %ORACLE_HOME%\pg4appc\demo\CICS\pgacics.sql, which is a simple sample communication between the Oracle server and CICS Transaction Server for z/OS. Executing the simple PL/SQL procedure pgacics.sql causes the Oracle Integrating Server to invoke the procedural gateway, which uses SNA to converse with the FLIP transaction in CICS. These steps are described in detail in Section 1.10.1, "Steps to Communication Between Gateway and Mainframe, Using SNA". Note that you will already have compiled and linked the stored procedure when you configured the gateway.

1.10.1 Steps to Communication Between Gateway and Mainframe, Using SNA

The following steps describe the Windows-to-mainframe communications process illustrated in Figure 1-3, "Communication Between the Oracle Server and the Mainframe, Using SNA" when your communication protocol is SNA to communicate between the gateway and the mainframe:

  1. From SQL*Plus, execute pgacics; this invokes the PL/SQL stored procedure in the Oracle Integrating Server.

    C:\> sqlplus <userid>/<password>@<database_specification_string>
    SQL> execute pgacics('==< .SCIC htiw gnitacinummoc si yawetag ruoy ,snoitalutargnoC >==');
    
    
  2. The pgacics PL/SQL stored procedure will start up the gateway. The gateway will start up communication with CICS Transaction Server for z/OS through SNA and will call FLIP.

  3. FLIP processes the input, generates the output and sends the output back to the procedural gateway.

  4. Finally, the procedural gateway will send the output back to the PL/SQL stored procedure in the Oracle Integrating Server. The result is displayed in SQL*Plus:

    ==> Congratulations, your gateway is communicating with CICS. <==
    PL/SQL procedure successfully completed.
    
    

    Figure 1-3, "Communication Between the Oracle Server and the Mainframe, Using SNA" illustrates the communications process described in steps 0 through 4 in the previous section.

Figure 1-3 Communication Between the Oracle Server and the Mainframe, Using SNA

Description of Figure 1-3 follows
Description of "Figure 1-3 Communication Between the Oracle Server and the Mainframe, Using SNA"

1.11 Writing TIPs to Generate PL/SQL Programs on Gateway Using SNA

Most transactions using SNA communication protocol are much larger and more complex than the simple sample pgacics.sql file referred to in Figure 1-3, "Communication Between the Oracle Server and the Mainframe, Using SNA". Additionally, communication with a normal-sized RTP (remote transaction program) would require you to create an extremely long PL/SQL file. Oracle Procedural Gateway for APPC's PGAU function generates the PL/SQL procedure for you.

The following is a brief description of the four steps necessary for you to generate a TIP. Refer to Chapter 3, "Creating a TIP" for detailed information about this procedure, and refer to Chapter 2, "Procedural Gateway Administration Utility" for more information about PGAU.

All parameter names in this section are taken from a file called pgadb2i.ctl in the %ORACLE_HOME%\pga4appc\demo\CICS directory.

1.11.1 Steps to Writing a TIP on a Gateway Using SNA

Follow these steps to write a TIP.


Step 1 Create a control file:

The user writes the control files. The control file has four main types of PGAU commands:

  1. DEFINE DATA. This is used to define input and output fields, using COBOL data definitions.

    • Sample define data:

      define data empno plsdname(empno) usage(pass) language(ibmvscobolii)
                        infile("empno.cob");
      
      
  2. DEFINE CALL. This is used to define PL/SQL functions calls to be generated as part of the package.

    • Sample define call:

      define call db2imain pkgcall(pgadb2i_main) 
                           parms((empno in),(emprec out));
      
      
  3. DEFINE TRANSACTION. This is used to group the above functions and specify other parameters on which the TIP depends.

    • Sample define transaction:

      define transaction db2i call(db2imain,db2idiag)
                              sideprofile(CICSPGA) 
                              tpname(DB2I)
                              logmode(oraplu62)
                              synclevel(0)
                              nls_language("american_america.we8ebcdic37c");
      
      
  4. GENERATE. This is used to generate the TIP specification files from the previously stored transaction, call and data definitions.

    • Sample generate transaction:

      generate db2i pkgname(pgadb2i) pganode(pga) outfile("pgadb2i");
      
      

Step 2 Execute the control file within PGAU

Running the control file within PGAU will create PG DD entries for the data, call, and transaction definitions, and will generate the specification files (For example, pgadb2i.pkh and pgadb2i.pkb):

C:\> pgau
PGAU> CONNECT<userid>/<password>@<database>_specification_string>
PGAU> @pgadb2i.ctl

Step 3 Execute the specification files

Running the specification files will create the PL/SQL stored procedures. Note that the header specification file (for example, pgadb2i.pkh) must be run first:

C:\> sqlplus<userid>/<password>@<database_specification_string>
SQL> @pgadb2i.pkh;
SQL> @pgadb2i.pkb;

Step 4 Create a driver procedure to run the TIP

The TIP is now ready for use. For convenience, it will usually be called using a driver procedure (for example, db2idriv). This driver will then call the individual stored procedures in the correct order. Create the driver procedure and run it:

C:\> sqlplus <userid>/<password>@<database_specification string> 
SQL> @pgadb2id.sql
SQL> execute db2idriv('000320');

1.12 Overview of a Gateway Using TCP/IP

If you are using the TCP/IP communication protocol, read the following sections to develop an understanding of how the gateway communicates with the Oracle Integrating Server and with the mainframe, as well as transaction types unique to your gateway and writing TIPs.

1.12.1 Transaction Types for a Gateway Using TCP/IP

The Oracle Procedural Gateway for APPC using TCP/IP support for IMS Connect supports three types of transaction socket connections:

  • transaction socket

    The socket connection lasts across a single transaction.

  • persistent socket

    The socket connection lasts across multiple transactions.

  • non-persistent socket

    The socket connection lasts across a single exchange consisting of one input and one output.

    Note:

    Do not use the non-persistent socket type if you plan on implementing conversational transactions because multiple connects and disconnects will occur.

    Refer to the section about pg4tcpmap commands in Chapter 6, "PG4TCPMAP Commands (TCP/IP Only)" of this guide for more information about the function and use of these parameters.

    You can initiate an IMS/TM transaction that executes static SQL in DB2; this illustrates the power of the Oracle Procedural Gateway for APPC's feature supporting TCP/IP for IMS Connect.

1.13 Simple Gateway Communication with the Oracle Server (TCP/IP)

This section describes simple communication between IMS and the Oracle Integrating Server whenTCP/IP for IMS Connect is being used as the communication protocol between the gateway and the remote host (IMS). The Oracle Procedural Gateway for APPC lets you write your own procedures to begin transferring information between the Oracle Integrating Server and I/O PCB programs on IMS.

For an illustration of the communications function of the gateway using TCP/IP for IMS Connect, refer to %ORACLE_HOME%\pg4appc\demo\IMS\pgaims.sql file.

Executing the simple PL/SQL procedure pgaims.sql causes the Oracle Integrating Server to invoke the gateway, which uses TCP/IP to converse with the sample transaction FLIP in IMS. The communication steps that take place when you execute the PL/SQL procedure are described in detail in Section 1.13.2, "Steps to Communication Between the Gateway and IMS, Using TCP/IP". Note that you will already have compiled and linked the stored procedure when you configured the gateway.

1.13.1 Preparing the Gateway to Communicate Using TCP/IP

If your gateway is using TCP/IP support for IMS Connect, then you must use the pg4tcpmap tool to create the required mapping between PGAINIT parameters and the target system network address information. The pg4tcpmap tool maps the Side Profile Name specified in a DEFINE TRANSACTION to TCP/IP and IMS Connect attributes, such as port number, IP address (host name) and IMS subsystem ID. The TCP/IP parameters are used to start a conversation with the target transaction program.

The pg4tcpmap tool must be run in order to populate the PGA_TCP_IMSC table before executing any TIPs which rely on TPC/IP support for IMS Connect.

  • Refer to Chapter 6, "PG4TCPMAP Commands (TCP/IP Only)" in this guide for complete instructions for setting up and executing pg4tcpmap commands to populate the PGA_TCP_IMSC table. Chapter 6 also explains the content of the PGA_TCP_IMSC table and an example of how to use the table.

  • For more information about the role of the pg4tcpmap tool in configuring the gateway, refer to Chapter 10 in the Oracle Procedural Gateway for APPC Installation and Configuration Guide regarding gateway configuration using the TCP/IP protocol.

  • A trace file from a sample pg4tcpmap execution is located in Chapter 8, "Problem Determination" in this guide.

  • A screen output file is located in Appendix B, "Gateway Initialization Parameter File Using TCP/IP" in the Oracle Procedural Gateway for APPC Installation and Configuration Guide.

1.13.2 Steps to Communication Between the Gateway and IMS, Using TCP/IP

The following steps describe the Windows-to-IMS on a mainframe communications process, as illustrated in Figure 1-4 when your communication protocol is TCP/IP:

  1. From SQL*Plus, execute pgaims.sql; this invokes the PL/SQL stored procedure in the Oracle Integrating Server.

    C:\> sqlplus <userid>/<password>@<database_specification_string>
    SQL> execute pgaims 'snoitalutargnoC';
    
    

    The pgaims.sql stored procedure will start up the gateway.

  2. The gateway which has the APPC information will call the mapping table (PGA_TCP_IMSC). The mapping table will map the information so that it will have the host name (TCP/IP address) and the port number.

    Note:

    Rather than insert, delete or update the PGA_TCP_IMSC mapping table manually, you should use the pg4tcpmap tool to do so. You may use the select statement to query the rows.
  3. When the gateway has the port number and host name, it will initiate communication with IMS through TCP/IP, and will call FLIP through IMS Connect.

  4. FLIP processes the input, generates the output and sends the output back to the gateway.

  5. Finally, the gateway will send the output back to the PL/SQL stored procedure in the Oracle Integrating Server. The result is displayed in SQL*Plus:

    Congratulations
    PL/SQL procedure successfully completed.
    
    

Figure 1-4, "Communication Between Oracle Server and Mainframe, Using TCP/IP" illustrates the communications process described in the previous Steps 0 through 5.

Figure 1-4 Communication Between Oracle Server and Mainframe, Using TCP/IP

Description of Figure 1-4 follows
Description of "Figure 1-4 Communication Between Oracle Server and Mainframe, Using TCP/IP"

1.14 Writing TIPs to Generate PL/SQL Programs on Gateway Using TCP/IP

Most transactions are much larger and more complex than the simple sample pgaims.sql file referred to in Figure 1-4, "Communication Between Oracle Server and Mainframe, Using TCP/IP". Additionally, communication with a normal-sized RTP (remote transaction program) would require you to create an extremely long PL/SQL file. Oracle Procedural Gateway for APPC's TIP function generates the PL/SQL procedure for you.

The following is a brief description of the four steps necessary for you to generate a TIP. Refer to Chapter 3, "Creating a TIP" for detailed information about this procedure, and refer to Chapter 2, "Procedural Gateway Administration Utility" for more information about PGAU.

All parameter names in this section are taken from a file called pgtflip.ctl in the %ORACLE_HOME%\pga4appc\demo\IMS directory.

1.14.1 Steps to Writing a TIP on a Gateway Using TCP/IP

Follow these steps to write a TIP.


Step 1 Create a control file:

Step 2 Execute the control file within PGAU

Running the control file within PGAU will create PG DD entries for the data, call, and transaction definitions, and will generate the specification files (For example, pgtflip.pkh and pgtflip.pkb):

C:\> cd %ORACLE_HOME%\pg4appc\demo\IMS
C:\> pgau
PGAU> CONNECT userid/password@database_specification_string
PGAU> @pgtflip.ctl

Step 3 Execute the specification files

Running the specification files will create the PL/SQL stored procedures. Note that the header specification file (for example, pgtflip.pkh) must be run first:

C:\> sqlplus userid/password@database_specification_string
SQL> @pgtflip.pkh;
SQL> @pgtflip.pkb;

Step 4 Create a driver procedure to run the TIP

The TIP is now ready for use. For convenience, it will usually be called using a driver procedure (for example, pgtflipd). This driver will then call the individual stored procedures in the correct order. Create the driver procedure and run it:

C:\> sqlplus <userid>/<password>@<database_specification string> 
SQL> @pgtflip.sql
SQL> execute pgtflipd('hello');