4 Client Application Development (SNA Only)

Overview of Client Application

The Procedural Gateway Administration Utility (PGAU) generates a complete TIP using definitions you provide. The client application can then call the TIP to access the remote host transaction. Chapter 2, "Procedural Gateway Administration Utility", discusses the use of PGAU in detail.

This overview explains what you must do in order to call a TIP and control a remote host transaction.

The gateway receives PL/SQL calls from the Oracle database and issues APPC calls to communicate with a remote transaction program. The following three application programs make this possible:

1. an APPC-enabled remote host transaction program

2. a Transaction Interface Package, or TIP. A TIP is a PL/SQL package that handles communication between the client and the gateway and performs datatype conversions between COBOL and PL/SQL.

   PGAU generates the TIP specification for you. In the shipped samples, the PGAU-generated package is called pgadb2i.pkb. This generated TIP includes at least three function calls that map to the remote transaction program:

   • pgadb2i_init initializes the conversation with the remote transaction program

   • pgadb2i_main exchanges application data with the remote transaction program

   • pgadb2i_term terminates the conversation with the remote transaction program

   Refer to Appendix E, "Tip Internals" for more information about TIPs, if you are writing your own TIP or debugging.

3. a client application that calls the TIP.

   The client application calls the three TIP functions with input and output arguments. In the example, the client application passes empno, an employee number to the remote transaction and the remote transaction sends back emprec an employee record.

Table 4-1 demonstrates the logic flow between the PL/SQL driver, the TIP, and the gateway using the example CICS-DB2 transaction.

A client application which utilizes the gateway to exchange data with a remote host transaction performs some tasks for itself and instructs the TIP to perform other tasks on its behalf. The client application designer must consequently know the behavior of the remote transaction and how the TIP facilitates the exchange.

The following sections provide an overview of remote host transaction behavior, how this behavior is controlled by the client application and how TIP function calls and data declarations support the client application to control the remote host transaction. These sections also provide background information about what the TIP does for the client application and how the TIP calls exchange data with the remote host transaction.

Preparing the Client Application

To prepare the client application for execution you must understand the remote host transaction requirements and then perform these steps:

1. Move relevant COBOL records layout (copybooks) to the gateway system for input to PGAU.

2. Describe the remote host transaction data and calls to the PG Data Dictionary (PG DD) with DEFINE DATA, DEFINE CALL, and DEFINE TRANSACTION statements.

3. Generate the TIP in the Oracle database, using GENERATE.

4. Create the client application that calls the TIP public functions.

5. Grant privileges on the newly created package.

Understanding the Remote Host Transaction Requirements

Browse through the remote host transaction program (RTP) to determine:

• the PL/SQL parameters required on the various client application to TIP calls

• the order in which the calls are made

Identify the remote host transaction program (RTP) facilities to be called and the data to be exchanged on each call. You will then define the following, and store them in the PG DD:

• DEFINE DATA

• DEFINE CALL

• DEFINE TRANSACTION

Refer to Chapter 3, "Creating a TIP" for specific definition steps and for the actual creation and generation of a TIP.

Customized TIPs for Each Remote Host Transaction

Each remote host system might have hundreds of remote transaction programs (RTPs) which a user might want to call. Each remote transaction program is different, passes different data, and performs different functions. The interface between the user and each remote transaction program must consequently be specialized and customized to the user's requirements for each remote transaction program. The Transaction Interface Package provides this customized interface.

Example

Assume that the remote site has a transaction program which manages employee information in an employee database or other file system. The remote transaction program's name, in the remote host, is EMPT for Employee Tracking. EMPT provides both inquiry and update facilities, and different Oracle users are required to access and use these EMPT facilities.

Some users might be restricted to inquiry-only use of EMPT, while others might have update requirements. In support of the Oracle users' client applications, at least three possible TIPs could exist:

1. EMP_MGMT to provide access to all facilities of the EMPT remote transaction program.

2. EMP_UPDT to access only the update functions of the EMPT remote transaction program.

3. EMP_INQR to access only the lookup functions of the EMPT remote transaction program.

End-user access to these TIPs is controlled by Oracle privileges. Additional security might be imposed on the end-user by the remote host.

Each TIP also has encoded within it the name of the remote transaction program (EMPT) and network information sufficient to establish an APPC conversation with EMPT.

Client Application Requirements

Using the TIP, the client application must correspond with and control the remote host transaction. This involves:

1. client application initialization

2. user input and output

3. remote host transaction initialization using the TIP initialization functions (with and without overrides)

4. remote host transaction control and data exchange using the TIP user functions

5. remote host transaction termination using the TIP termination function

6. exception handling

7. client application termination

Steps 3, 4 and 5 vary, based on the requirements of the remote host transaction.

One-shot remote host transaction client applications must:

• Declare RHT/TIP datatypes to be exchanged. All client applications must declare variables to be exchanged with the RHTs using TIPs. PL/SQL datatypes for such variables have already been defined in the TIP corresponding to each RHT and the client application need only reference the TIP datatype in its declaration. Refer also to "Declaring TIP Variables" for more information. Also refer to the TIP content documentation file for the specific TIP/RHT for more information about the exact usage of these variables.

• Initialize the RHT using the TIP initialization function. The TIP directs the gateway server to initialize a conversation with the desired RHT, specifying either default RHT identifying parameters (supplied when the RHT was defined in the PG DD and encoded within the TIP when it was generated) or override RHT identifying parameters supplied by the user or client application when the TIP initialization function is called. Refer to "Initializing the Conversation" and "Overriding TIP Initializations" for more details.

• Exchange data with the RHT using the TIP user function (one call). As previously discussed, a one-shot remote host transaction only accommodates a single data exchange and upon completion of that exchange, the RHT terminates on its own. The client application consequently needs only to execute a single call to the user-defined TIP function to cause the data exchange.

  Refer to the TIP content documentation file in %ORACLE_HOME%\dg4appc\demo\CICS\ on Microsoft Windows or $ORACLE_HOME/dg4appc/demo/CICS/ on UNIX based systems, for the specific TIP/RHT for the exact syntax of this call.

  The client application should initialize values into IN or IN OUT parameter values before calling the TIP function call. These are the same variables that were declared above, when you declared the RHT/TIP datatypes to be exchanged.

  All TIP function calls return a 0 return code value and all returned user gateway data values are exchanged in the function parameters. Any exception conditions are raised as required and can be intercepted in an exception handler.

  Upon return from the TIP function call, the client application can analyze and operate on the IN OUT or OUT parameter values. These are the same variables that were declared above, when you declared the RHT/TIP datatypes to be exchanged.

  Refer to Appendix D, "Datatype Conversions" for details about how TIPs convert the various types and formats of remote host data.

• Terminate the RHT using the TIP termination function. Regardless of the type of RHT being accessed, the TIP terminate function should be called to clean up and terminate the conversation with the RHT. Conversations with one-shot RHTs can be terminated from the gateway server before the RHT terminates. The TIP must perform its cleanup as well. Cleanup is only performed at the termination request of the client application.

  The client application can request a normal or an aborted termination.

  Refer to "Terminating the Conversation" for more information.

Persistent remote host transaction client applications must:

• Declare RHT/TIP datatypes to be exchanged. All client applications must declare variables to be exchanged with the RHTs using TIPs. PL/SQL datatypes for such variables have already been defined in the TIP corresponding to each RHT; the client application need only reference the TIP datatype in its declaration. Refer to "Declaring TIP Variables" for more information. Refer also to the TIP content documentation file for the specific TIP/RHT for more information about the exact usage of these variables.

• Initialize the RHT using the TIP initialization function. The TIP directs the gateway server to initialize a conversation with the desired RHT, specifying either default RHT identifying parameters (supplied when the RHT was defined in the PG DD and encoded within the TIP when it was generated) or override RHT identifying parameters supplied by the user or client application when the TIP initialization function is called. Refer to "Initializing the Conversation" and "Overriding TIP Initializations" for more details.

• Repetitively exchange data with RHT using the TIP user function(s). Remote host transactions that provide or require ongoing or repetitive control sequences should be controlled by the client application in the same manner that the RHT would be operated by an interactive user or other control program. The intercession of the TIP and gateway server does not alter the RHT behavior; instead, it extends control of that behavior to the client application using the various function calls defined in the TIP.

  A persistent RHT can be controlled with one or more TIP function calls. The RHT might be designed, for example, to loop and return output for every input until the conversation is explicitly terminated. Or it could have been designed to accept as input a count or list of operations to perform and return the results in multiple exchanges for which the TIP function has only OUT parameters.

  A persistent RHT can also be interactive, each output being specified by a previous input selection and ending only when the conversation has been explicitly terminated by the client application.

  The TIP function calls available to the client applications and their specific syntax is documented in the TIP Content documentation file for the specific TIP/RHT.

  The manner in which the RHT interprets the TIP IN parameters and returns TIP OUT parameters must be determined from the RHT or explained by the RHT programmer. The TIP provides the function calls and the exchanged parameter datatypes to facilitate the client application's control of the RHT and imposes no limitations or preconditions on the sequence of operations the RHT is directed to perform. The TIP provides the client application with the calls and data parameters the RHT was defined to accept in the PG DD.

• Terminate the RHT using the TIP termination function. Regardless of the type of RHT being accessed, the TIP terminate function should be called to clean up and terminate the conversation with the RHT. Conversations with persistent RHTs can be terminated from the gateway server before the RHT terminates, or the RHT might have already terminated. The TIP must perform its cleanup as well and this cleanup is only performed at the termination request of the client application.

  The client application can request a normal or an aborted termination.

  Refer to "Terminating the Conversation" for more information.

Multi-conversational remote host transaction client applications must:

• Declare RHT/TIP datatypes to be exchanged. All client applications must declare variables to be exchanged with the RHTs using TIPs. PL/SQL datatypes for such variables have already been defined in the TIP corresponding to each RHT, and the client application need only reference the TIP datatype in its declaration. Refer to "Declaring TIP Variables" for more information. Also refer to the TIP content documentation file for the specific TIP/RHT for more information about the exact usage of these variables.

• Initialize each RHT involved, using the TIP initializing function. A specific customized TIP exists for each RHT as defined in the PG DD. Client applications that control multiple RHTs are multi-conversational and must start each RHT and its associated conversation. This is done by calling each TIP initialization function as before; but multiple TIPs are initialized.

  If a single RHT is designed to perform multiple services for one or more callers and if the client application is designed to use this RHT, the TIP corresponding to that RHT can be initialized multiple times by the client application.

  The client application subsequently distinguishes from active RHTs under its control using:

  • TIP schema tipname.callname when multiple TIP/RHTs are being controlled. By encoding the same TIP schema name on TIP user calls, the client application specifies to which RHT the call is being made.

  • tranuse IN OUT parameter value when multiple instances of the same TIP/RHT are being controlled. This is the value returned on the TIP initialization function call and subsequently passed as an IN parameter on the user-defined TIP function calls. The returned tranuse value corresponds to that conversation connected to a given instance of an RHT. By supplying the same tranuse value on TIP user calls, the client application specifies to which RHT instance the given RHT call is being made.

  Client application logic must keep track of which RHTs have been started and which TIPs and tranuse values correspond to started RHTs.

• Exchange data with each RHT, using the TIP user function(s), either once or repetitively if the RHT is one-shot or persistent. Client application logic must sequence the RHTs though their allowed steps in accordance with proper RHT operation, as does a user operating the RHTs interactively.

  Client application logic must also perform any cross-RHT result analysis or data transfer that might be required. All TIPs execute in isolation from each other.

  Output from one RHT intended as input to another RHT must be received in the client application as an IN or IN OUT parameter from the first RHT and sent as an IN or IN OUT parameter from the client application to the second RHT. All TIP-to-RHT function calls must be performed by the client application and data parameters exchanged must have been declared as variables by the client application. The TIPs provide both the required datatype definitions and the RHT function calls for the client application.

  Refer to the TIP content documentation file for each specific TIP/RHT for the exact syntax of the TIP function calls and definitions of the parameter datatypes exchanged.

• Terminate each initialized RHT, using the TIP termination function. To terminate an RHT, its corresponding TIP termination function must be called to terminate the RHT and its conversation and to initiate TIP cleanup. The RHT to be terminated is specified by its TIP schema name (the same schema as for its data exchange function calls) and the tranuse value when multiple instances of the same RHT are being terminated.

  RHTs and their corresponding TIPs can be terminated in any sequence desired by the client application and do not have to be terminated in the same order in which they are initialized.

  Note:

  The specific syntax of the various TIP data exchange variables function calls is the same as was previously defined in the PG DD for the particular RHT and can be researched by examining the TIP content documentation file (tipname.doc) or the TIP specification file produced when the TIP was generated. If a TIP has not yet been generated for the RHT being accessed, refer to Chapter 3, "Creating a TIP", and "DATA Correspondence", "CALL Correspondence", and "TRANSACTION Correspondence" for more information. It is preferable to define and generate the TIP first, however, so that the client application reference documentation is available to you when needed.

Ensuring TIP and Remote Transaction Program Correspondence

A remote host transaction program and its related TIP with client application must correspond on two key requirements:

• Parameter datatype conversion, which results from the way in which transaction DATA is defined. Refer to Appendix D, "Datatype Conversions" for a discussion of how PGAU-generated TIPs convert data based on the data definitions.

• APPC send/receive synchronization, which results from the way in which transaction CALLs are defined

These DATA and CALL definitions are then included by reference in a TRANSACTION definition.

pgadb2i_main(trannum,empno,emprec)

DEFINE DATA EMPNO
       PLSDNAME (EMPNO)
       USAGE (PASS)
       LANGUAGE (IBMVSCOBOLII)
       (
       01 EMP-NO PIC X(6).
       ); 

DEFINE DATA EMPREC
       PLSDNAME (DCLEMP)
       USAGE (PASS)
       LANGUAGE (IBMVSCOBOLII)
       INFILE("emp.cob");

DEFINE CALL DB2IMAIN
       PKGCALL (pgadb2i_main)
       PARMS ((empno IN),(emprec OUT));

APPC SEND    5 fields  (field1-field5)
APPC RECEIVE 1 fields  (field6)
APPC SEND    1 field   (field7)
APPC RECEIVE 3 fields  (field8 - field10)

tip_call1(parm1 OUT,  <-- APPC SEND field1 from remote TP
         parm2 OUT,  <-- APPC SEND field2 from remote TP
         parm3 OUT); <-- APPC SEND field3 from remote TP

tip_call2(parm4 OUT,  <-- APPC SEND field4 from remote TP
         parm5 OUT); <-- APPC SEND field5 from remote TP
tip_call3(parm6 IN OUT); --> APPC RECEIVE field6 in remote TP
                         <-- APPC SEND field7 from remote TP

tip_call4(parm8 IN,   --> APPC RECEIVE field8 into remote TP
          parm9 IN,   --> APPC RECEIVE field9 into remote TP
          parm10 IN); --> APPC RECEIVE field10 into remote TP

tip_callO( parmO OUT); <-- APPC SEND outfield from remote TP

tip_callI( parmI IN);  --> APPC RECEIVE infield to remote TP

DEFINE TRANSACTION DB2I
   CALL (   DB2IMAIN,
            DB2IDIAG   )
   SIDEPROFILE(CICSPROD)
   TPNAME(DB2I)
   LOGMODE(ORAPLU62)
   SYNCLEVEL(0)
   NLS_LANGUAGE("AMERICAN_AMERICA.WE8EBCDIC37C");

Calling the TIP from the Client Application

Once a TIP is created, a client application must be written to interface with the TIP. A client application that calls the TIP functions must include five logical sections:

• declaring TIP variables

• initializing the conversation

• exchanging data

• terminating the conversation

• error handling

FUNCTION tip_call1    tranuse,   IN      BINARY_INTEGER, 
                      tip_var1   io_mode pls_type1, 
                      tip_record io_mode tran_rectype) 
RETURN INTEGER;

TYPE  tran_rectype is RECORD
      (rec_field1 pls_type1,
      ...
      rec_fieldN pls_typeN);

appl_var  pls_type1;    /* declare appl variable for ....  */

appl_record tipname.tran_rectype;  /* declare appl record */

rc = tip_call1( tranuse,
                appl_var,
                appl_record);

...
...
CREATE or REPLACE PROCEDURE db2idriv(empno IN CHAR) IS
tranuse INTEGER :=0               /* transaction usage number     */
DCLEMP PGADB2I.DCLEMP_typ;        /* DB2 EMP row definition       */
DB2 PGADB2I.DB2_typ;              /* DB2 diagnostic information   */
rc INTEGER :=0                    /* PGA RPC return codes         */
line VARCHAR2(132);               /* work buffer for output       */
term INTEGER :=0;                 /* 1 if pgadb2i_term called     */
...
...

TYPE override_Typ IS RECORD (
        tranname  VARCHAR2(255),  /* Transaction Program     */
        transync  BINARY_INTEGER, /* RESERVED                */
        trannls   VARCHAR2(50),   /* RESERVED                */
        oltpname  VARCHAR2(255),  /* Logical Unit            */
        oltpmode  VARCHAR2(255),  /* LOG Mode Entry          */
        netaddr   VARCHAR2(255),  /* Side Profile            */
        oltpuser  VARCHAR2(8),    /* userid for OLTP access  */
        oltppass  VARCHAR2(8));   /* password for OLTP access*/

FUNCTION pgadb2i_init(                /* init standard */
           tranuse IN OUT BINARY_INTEGER)
           RETURN INTEGER;

FUNCTION pgadb2i_init(                /* init override */
           tranuse IN OUT BINARY_INTEGER,
           override IN override_Typ)
           RETURN INTEGER;

FUNCTION pgadb2i_init(               /* init diagnostic */
           tranuse IN OUT BNARY_INTEGER,
           tipdiag IN CHAR)
           RETURN INTEGER;

FUNCTION pgadb2i_init(                /* init over-diag */
           tranuse IN OUT BINARY_INTEGER,
           override IN override_Typ,
           tipdiag IN CHAR)
           RETURN INTEGER;

...
...
tranuse INTEGER := 0;/* transaction usage number*/
...
...
BEGIN
 rc := pgadb2i.pgadb2i_init(tranuse);
...
...

   ...
   ...
   my_overrides pgadb2i.override_Typ;   -- declaration
   ...
   ...
   my_overrides.oltpname := 'CICSPROD'; -- swap to production CICS
   my_overrides.tranname := 'TNEW';     -- new transaction name

BEGIN
   rc := pgadb2i.pgadb2i_init(tranuse,my_overrides); -- init
   ...
   ...

Exchanging Data

The client application should pass the transaction instance number, returned from a previous tip_init call, to identify which remote transaction program is affected and to identify any client application data parameters to be exchanged with the remote transaction program.

In this CICS-DB2 inquiry example, we pass an employee number and receive an employee record back:

rc = pgadb2i.pgadb2i_main(tranuse, /* transfer data         */
                           empno,   /* employee number       */
                           DCLEMP); /* return employee record*/

...
...
term := 1;    /* indicate term called* */
 rc := pgadb2i.pgadb2i_term(tranuse,0); /* terminate normally  */
...
...

EXCEPTION
 WHEN OTHERS THEN
  IF term = 0 THEN         /* terminate function not called yet */
   rc := pgadb2i.pgadb2i_term(tranuse,1); /*terminate abnormally*/
  END IF;
 RAISE;
...
...

GRANT EXECUTE ON PGADB2I TO SCOTT

Executing the Application

Before executing the client application, ensure that a connection to the host is established and that the receiving partner is available. In this example we use PL/SQL driver DB2IDRIV to execute the CICS-DB2 inquiry. To execute this client application, enter from SQL*Plus:

set serveroutput on
execute DB2IDRIV('nnnnnn');

APPC Conversation Sharing

Multiple TIPs can share the same APPC conversation with one or more Remote Host Transactions (RHTs) which are also sharing that same conversation. Two benefits derive from this feature:

• Existing RHTs which rely upon passing control of a conversation are supported by Oracle Database Gateway for APPC.

• TIPs otherwise too large for PL/SQL compilation can be separated into multiple smaller TIPs, each with fewer user-defined functions, providing the client application with the same set of function calls and data definitions without any change to the RHT.

ORA-20704 PGA_TIP: tranuse value cannot be shared

DEFINE TRANSACTION rhtABC calls(menu_A, 
                                query_B, 
                                update_C, 
                                select_C) 
                          tpname(RHTA);   

rc := rhtABC.rhtABC_init(tranuse); 
rc := rhtABC.pick(tranuse, choice); 
rc := rhtABC.query(tranuse, input, answer); 
rc := rhtABC.update(tranuse, record); 
rc := rhtABC.select(tranuse, record); 
rc := rhtABC.rhtABC_term(tranuse); 

DEFINE TRANSACTION rhtA calls(menu_A)   tpname(RHTA); 
DEFINE TRANSACTION rhtB calls(query_B)  tpname(RHTA); 
DEFINE TRANSACTION rhtC calls(update_C, 
                              select_C) tpname(RHTA); 

rc := rhtA.rhtA_init(tranuse); 
rc := rhtA.pick(tranuse, choice); 
rc := rhtB.query(tranuse, input, answer); 
rc := rhtC.update(tranuse, record); 
rc := rhtC.select(tranuse, record); 
rc := rhtB.rhtB_term(tranuse); 

DEFINE TRANSACTION rhtABC calls(menu_A)   tpname(RHTA); 
DEFINE TRANSACTION rhtB   calls(query_B)  tpname(RHTA); 
DEFINE TRANSACTION rhtCU  calls(update_C) tpname(RHTA); 
DEFINE TRANSACTION rhtCS  calls(select_C) tpname(RHTA); 

rc := rhtB.rhtB_init(tranuse); 
rc := rhtABC.pick(tranuse, choice); 
rc := rhtB.query(tranuse, input); 
rc := rhtCU.update(tranuse, record); 
rc := rhtCS.select(tranuse, record); 
rc := rhtABC.rhtABC_term(tranuse); 

Application Development with Multi-Byte Character Set Support

COBOL presently only supports double byte character sets (DBCS) for PIC G datatypes.

PGAU processes COBOLII PIC G datatypes as PL/SQL VARCHAR2 variables and generates TIPs which automatically convert the data according to the Oracle NLS_LANGUAGEs specified for the remote host data and the local Oracle data.

These Oracle NLS_LANGUAGEs can be specified as defaults for all PIC G data exchanged by the TIP with the remote transaction (see DEFINE TRANSACTION ... REMOTE_MBCS or LOCAL_MBCS). The Oracle NLS_LANGUAGEs for any individual PIC G data item can be further overridden (see REDEFINE DATA ... REMOTE or LOCAL_LANGUAGE).

DBCS data can be encoded in any combination of supported DBCS character sets. For example, a remote host application which allows different codepages for each field of data in a record is supported by the Oracle Database Gateway MBCS support.

Use of REDEFINE DATA ... REMOTE_LANGUAGE or LOCAL_LANGUAGE on PIC X items is also supported. Thus a TIP can perform DBCS or MBCS conversions for specified PIC X data fields, in addition to SBCS conversions by default for the remaining PIC X data fields. Default SBCS conversion is according to the DEFINE TRANSACTION... NLS_LANGUAGE and local Oracle default LANGUAGE environment values.

When PGAU is generating a TIP, the PIC G datatypes are converted to PL/SQL VARCHAR2 datatypes. After conversion by the TIP, received 'PIC G' VARCHAR2 datatypes can have a length less then the maximum due to deletion of shift-out and shift-in meta characters, and sent 'PIC G' RAWs will have the shift-out and shift-in characters inserted as required by the remote host character set specified.

This is different from the conversions performed for PIC X data which is always a known fixed-length and hence CHAR datatypes are used in TIPs for PIC X data fields. However, even when the PIC X field contains DBCS or MBCS data, a CHAR variable is still used and padded with blanks if needed.

Some remote host applications bracket a PIC G field with PIC X bytes used for shift-out, shift-in meta-character insertion. Such a COBOL definition might look like:

01 MY_RECORD. 
   05 SO PIC X. 
   05 MY_SBCS_DATA PIC G(52). 
   05 SI PIC X. 

This is not processed correctly by PGAU, because all three fields are defined, and consequently treated, as separate data items when conversion is performed.

To be properly processed, the definition input to PGAU should be:

01 MY_RECORD. 
   05 MY_MBCS_DATA PIC G(51).

The PGAU REDEFINE DATA statement can redefine the 3-field definition to the 1-field definition by specifying USAGE(SKIP) on fields SO and SI, and '05 MY_MBCS_DATA PIC G(51).' to redefine MY_MBCS_DATA. The three REDEFINE statements can be placed in the PGAU input control file, and thus the remote host definition need not be altered.

Modifying a Terminal-Oriented Transaction to Use APPC

The remote transaction program must include mapped APPC verbs to initiate, communicate, and terminate the APPC conversation. However, when the remote transaction program is terminal-oriented, the following options are available:

• You can separate the terminal logic from the application and I/O logic. Once this separation is achieved, a small front end remote transaction program can be written to interface between the gateway calls and the transaction application logic. For example, in CICS the CICS LINK is used to implement this technique.

• You can modify your existing program so that APPC calls are embedded. In the example, PGADB2I, we use CICS and its associated mapped APPC verbs as follows:

  • EXEC CICS ASSIGN accepts the conversation initiated by the gateway.

  • EXEC CICS RECEIVE receives the arguments.

  • EXEC CICS SEND ends the results.

  • EXEC CICS RETURN terminates the conversation.

• If you do not want to modify your terminal-oriented transaction, you can insert an APPC-capable interface, such as IBM Corporation's FEPI for CICS Transaction Server for z/OS, between the terminal-oriented program and the gateway.

• With IMS/TM, existing unmodified IMS transactions can be accessed with the gateway using the implicit APPC facility. With implicit APPC, the standard DLI GU, GN, and ISRT calls using the I/O PCB are automatically converted to appropriate APPC send or receive calls when the IMS transaction is invoked through APPC.

Privileges Needed to Use TIPs

Execute privileges must be explicitly granted to callers of TIPs or procedures. This privilege cannot be granted through a role.

Any TIP user wanting to trace a TIP must be granted execute privileges on the rtrace and ptrace procedures. Refer to the "Configuring PGAU" section in the chapter appropriate for your communications protocol in the Oracle Database Gateway for APPC Installation and Configuration Guide for IBM AIX on POWER Systems (64-Bit), Linux x86-64, Oracle Solaris on SPARC (64-Bit), and HP-UX Itanium and Oracle Database Gateway for APPC Installation and Configuration Guide for Microsoft Windows for more information.

For example, on Microsoft Windows:

C:\> sqlplus pgaadmin\pw@database_specification_string 
SQL> grant execute on pgaadmin.purge_trace to tip_user_userid;
SQL> grant execute on pgaadmin.read_trace to tip_user_userid; 

On UNIX based systems:

$ sqlplus pgaadmin/pw@database_specification_string 
SQL> grant execute on pgaadmin.purge_trace to tip_user_userid;
SQL> grant execute on pgaadmin.read_trace to tip_user_userid; 

After a TIP has been developed, the TIP user must be granted execute privileges on the TIP by the TIP owner. The TIP owner is usually PGAADMIN, but can be another user who has been granted either the PGDDDEF or PGDDGEN roles.

For example, on Microsoft Windows:

C:\> sqlplus tip_owner\pw@database_specification_string 
SQL> grant execute on tipname to tip_user_userid;

On UNIX based systems:

$ sqlplus tip_owner/pw@database_specification_string 
SQL> grant execute on tipname to tip_user_userid;

where database_specification_string is the Oracle Net identifier for the Oracle database where the gateway UTL_RAW and UTL_PG components were installed. This is the same Oracle database where the TIPs are executed and where grants on the TIPs are performed from the TIP owner user ID.

A SQL script for performing these grants is provided in the %ORACLE_HOME%\\dg4appc\\admin directory on Microsoft Windows and in the $ORACLE_HOME/dg4appc/admin directory on UNIX based system. The pgddausr.sql script performs the grants for private access to the packages by a single TIP user. If private grants are to be used, the pgddausr.sql script must be run once for each TIP user's user ID.

To run these scripts, use SQL*Plus to connect to the Oracle database as user PGAADMIN. From SQL*Plus, run the pgddausr.sql script from the %ORACLE_HOME%\\dg4appc\\admin directory on Microsoft Windows or $ORACLE_HOME/dg4appc/admin directory on UNIX based system. The script performs the necessary grants as previously described. You are prompted for the required user IDs, passwords, and database specification strings. If you are using private grants, repeat this step for each user ID requiring access to the packages.

No script has been provided to perform public grants. To do this, issue the following commands:

For Microsoft Windows:

C:\> sqlplus tip_owner\pw@database_specification_string 
SQL> grant execute on tipname to PUBLIC;  

For UNIX based systems:

$ sqlplus tip_owner/pw@database_specification_string 
SQL> grant execute on tipname to PUBLIC;