The content of a PGAU-generated TIP reflects the calls available to the remote host transaction and the data that has been exchanged. Understanding this content helps when designing and debugging client applications that call the TIP.

A TIP is a PL/SQL package, and accordingly has two sections:

• A Package Specification containing:

  • Public function prototypes and parameters, and

• A Package Body containing:

  • Private functions and internal control variables

  • Public functions

  • Package initialization following the last public function.

The purpose of the TIP is to provide a PL/SQL callable public function for every allowed remote transaction program interaction. A remote transaction program interaction is a logically related group of data exchanges through one or more PGAXFER RPC calls. This is conceptually similar to a screen or menu interaction in which several fields are filled in, the enter key is pressed, and several fields are returned to the user. Carrying the analogy further:

• the user might be likened to the TIP or client application

• fields to be filled in are IN parameters on the TIP function call

• fields returned are OUT parameters on the TIP function call

• screen or menu is the group of IN and OUT parameters combined

• a pressed enter key is likened to the PGAXFER remote procedural call (RPC)

The actual grouping of parameters that constitute a transaction call is defined by the user. The gateway places no restrictions on how a remote transaction program might correspond to a collection of TIP function calls, each call having many IN and OUT parameters.

PGA users typically have one TIP per remote transaction program. How the TIP function calls are grouped and what data parameters are exchanged on each call depends on the size, complexity and behavior of the remote transaction program.

Refer to Oracle's Oracle Database PL/SQL Language Reference for a discussion of how PL/SQL packages work. The following discussion covers the logic that must be performed within a TIP. Refer to the sample TIP and driver supplied in the %ORACLE_HOME%\dg4appc\demo\CICS directory for Microsoft Windows or $ORACLE_HOME/dg4appc/demo/CICS directory for UNIX based systems, in files pgadb2i.pkh, pgadb2i.pkb, and pgadb2id.sql.

From a database gateway application perspective, there are three main types of remote host transactions:

• one-shot

• persistent

• multi-conversational

Using data definitions programmed in the language of the remote host transaction, the PGAU DEFINE DATA command stores in the PG DD the information needed for PGAU GENERATE to create the TIP function logic to perform:

• all data conversion from PL/SQL IN parameters supplied by the receiving remote host transaction

• all buffering into the format expected by the receiving remote host transaction

• all data unbuffering from the format supplied by the sending remote host transaction

• all data conversion to PL/SQL OUT parameters supplied by the sending remote host transaction

PGAU determines the information needed to generate the conversion and buffering logic from the data definitions included in the remote host transaction program. PGAU DEFINE DATA reads this information from files, such as COBOL copy books, or in-stream from scripts and saves it in the PG DD for repeated use. The gateway Administrator needs to transfer these definition files from the remote host to the Oracle host where PGAU runs.

From the data definitions stored in the PG DD, PGAU GENERATE determines the remote host datatype and matches it to an appropriate PL/SQL datatype. It also determines data lengths and offsets within records and buffers and generates the needed PL/SQL logic into the TIP. Refer to the PGAU "DEFINE DATA" statement in Procedural Gateway Administration Utility and "Sample PGAU DEFINE DATA Statements" in Administration Utility Samples for more information.

All data that are referenced as parameters by subsequent calls must first be defined using PGAU DEFINE DATA. Simple data items, such as single numbers or character strings, and complex multi-field data aggregates, such as records or structures, can be defined. PGAU automatically generates equivalent PL/SQL variables and records of fields or tables for the client application to reference in its calls to the generated TIP.

As discussed, a parameter might be a simple data item, such as an employee number, or a complex item, such as an employee record. PGAU DEFINE DATA automatically extracts the datatype information it needs from the input program data definition files.

In this example, empno and emprec are the arguments to be exchanged.

pgadb2i_main(trannum,empno,emprec)

A PGAU DEFINE DATA statement must therefore be issued for each of these parameters:

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");

Note that a definition is not required for the trannum argument. This is the APPC conversation identifier and does not require a definition in PGAU.

The requirement to synchronize APPC SENDs and RECEIVEs means that when the remote transaction program expects data parameters to be input, it issues APPC RECEIVEs to read the data parameters. Accordingly, the TIP must cause the gateway to issue APPC SENDs to write the data parameters to the remote transaction program. The TIP must also cause the gateway to issue APPC RECEIVEs when the remote transaction program issues APPC SENDs.

The PGAU DEFINE CALL statement specifies how the generated TIP is to be called by the client application and which data parameters are to be exchanged with the remote host transaction for that call. Each PGAU DEFINE CALL statement might specify the name of the TIP function, one or more data parameters, and the IN/OUT mode of each data parameter. Data parameters must have been previously defined with PGAU DEFINE DATA statements. Refer to "DEFINE CALL" in Procedural Gateway Administration Utility and "Sample PGAU DEFINE CALL Statements" in Administration Utility Samples for more information.

PGAU DEFINE CALL processing stores the specified information in the PG DD for later use by PGAU GENERATE. PGAU GENERATE then creates the following in the TIP package specification:

• declarations of public PL/SQL functions for each CALL defined with PL/SQL parameters for each DATA definition specified on the CALL

• declarations of the public PL/SQL data parameters

The client application calls the TIP public function as a PL/SQL function call, using the function name and parameter list specified in the PGAU DEFINE CALL statement. The client application might also declare, by reference, private variables of the same datatype as the TIP public data parameters to facilitate data passing and handling within the client application, thus sharing the declarations created by PGAU GENERATE.

In this example, the following PGAU DEFINE CALL statement must be issued to define the TIP public function:

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

The remote host transaction is defined with the PGAU DEFINE TRANSACTION statement with additional references to prior definitions of CALLs that the transaction supports.

You specify the remote host transaction attributes, such as:

• transaction ID or name

• network address or location

• system type (such as IBM370)

• Oracle National Language of the remote host

  Note:

  The PL/SQL package name is specified when the transaction is defined; this is the name by which the TIP is referenced and which the public function calls to be included within the TIP. Each public function must have been previously defined with a PGAU DEFINE CALL statement, which has been stored in the PG DD. If you do not specify a package name (TIP name) in the GENERATE statement, the transaction name you specified will become the package name by default. In that case, the transaction name (tname) must be unique and must be in valid PL/SQL syntax within the database containing the PL/SQL packages.

  For more information, refer to "DEFINE TRANSACTION" in Procedural Gateway Administration Utility and "Sample PGAU DEFINE TRANSACTION Statement" in Administration Utility Samples.

In this example, the following DEFINE TRANSACTION statements are used to define a remote CICS transaction called DB2I:

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

The user declarations section of the tipname.doc file documents the required declarations.

When passing PL/SQL parameters on calls to TIP functions, the client application must use the exact same PL/SQL datatypes for TIP function arguments as are defined by the TIP in its specification section. Assume, for example, the following is in the TIP specification, or tipname.doc:

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);

Table 4-2 provides a description of the function declarations:

In the client application PL/SQL atomic datatypes should be defined as the exact same datatype of their corresponding arguments in the TIP function definition. The following should be coded in the client application before the BEGIN command:

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

TIP datatypes need not be redefined. They must be declared locally within the client application, appearing in the client application before the BEGIN:

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

Table 4-3 describes the command line arguments:

Refer to the tipname.doc content file for a complete description of the user declarations you can reference.

The client application calls the TIP public function as if it were any local PL/SQL function:

rc = tip_call1( tranuse,
                appl_var,
                appl_record);

In the CICS-DB2 inquiry example, the PL/SQL driver pgadb2id.sql, which is located in %ORACLE_HOME%\dg4appc\demo\CICS directory for Microsoft Windows and $ORACLE_HOME/dg4appc/demo/CICS directory for UNIX based systems, is the client application and includes the following declaration:

...
...
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     */
...
...

The call to initialize the conversation serves several purposes:

• To cause the PL/SQL package, the TIP, to be loaded and to perform the initialization logic programmed in the TIP initialization section.

• To cause the TIP init function to call the PGAINIT remote procedural call (RPC), which in turn establishes communication with the remote transaction program (RTP), and returns a transaction instance number to the application.

Optionally, calls to initialize the conversation can be used to:

• Override default RHT/OLTP identification, network address attributes, and conversation security user ID and password.

• Specify what diagnostic traces the TIP is to produce. Refer to Troubleshooting for more information about diagnostic traces.

PGAU-generated TIPs provide four different initialization functions that client applications can call. These are overloaded functions which all have the same name, but vary in the types of parameters passed.

Three initialization parameters are passed:

• The transaction instance number for RHT conversation identification. The tranuse parameter is required on all TIP initializations.

• TIP diagnostic flags for TIP runtime diagnostic controls. The tipdiag parameter is optional. Refer to Troubleshooting for a discussion of TIP diagnostics.

• TIP default overrides for overriding OLTP and network attributes. The override parameter is optional.

The following four functions are shown as they might appear in the TIP Content documentation file. Examples of client application use are provided later.

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;

The client application calls the TIP termination function as if it were any local PL/SQL function. For example:

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

After a transaction instance number has been passed on a TIP terminate call to terminate the transaction, or after the remote transaction program has abended, that particular transaction instance number may be forgotten.

The client application should include an exception handler that can clean up any active APPC conversations before the client application terminates. The sample client application provided in pgadb2id.sql contains an example of exception handling.

Gateway exceptions are reported in the range PGA-20900 to PGA-20999. When an exception occurs, the TIP termination function should be called for any active conversations that have been started by prior calls to the TIP initialization function.

For example:

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

The remote transaction should also include provisions for error handling and debugging, such as writing debugging information to the CICS temporary storage queue area. Refer to the Oracle Database PL/SQL Language Reference for a discussion of how to intercept and handle Oracle exceptions.

Mainframe OLTPs, such as IMS, allow transactions to share a single APPC conversation by passing it when the transaction calls another transaction. RHTs are defined to PGAU as single transactions with calls, inputs and outputs for which PGAU generates a single TIP with initialization, transfer and termination functions corresponding to that specific RHT.

Logic generated into every TIP allows that TIP either:

• to initiate a new conversation when its init function is called, or

• to transfer data on an existing conversation when its user-defined functions are called, or

• to terminate an existing conversation when its "term" function is called.

An APPC conversation is treated as a resource shared and managed by multiple TIPs. There is no requirement for any TIP to be the sole user of an APPC conversation.

Any TIP generated at 3.4.0 or later can perform any of the following combinations of service:

• initiate

• initiate and transfer

• initiate, transfer, and terminate (standard operation)

• transfer

• transfer and terminate

• terminate

• initiate and terminate (assumes other TIPs perform transfer)

A single APPC conversation can be shared in the following ways:

• from one TIP to multiple RHTs

• from multiple TIPs to one RHT

• from multiple TIPs to multiple RHTs

Without APPC conversation sharing, a single TIP must be defined which contains all functions and data for all RHTs which a client application might need to call. Creating TIPs with a superset of RHTs often causes such TIPs to be too large for PL/SQL to compile.

Conversely, with APPC conversation sharing, each RHT (or even each RHT data exchange for those RHTs which perform multiple, different data exchange operations) can be defined in a single TIP which is smaller and less likely to exceed PL/SQL compilation limits.

APPC conversation sharing is automatically available in every TIP generated at 3.4.0 or later. No TIPs generated before 3.4.0 can participate in APPC conversation sharing. TIPs generated before 3.4.0 must be regenerated using PGAU 3.4.0. or later to participate in APPC conversation sharing. PGAU is upward compatible and regeneration should be transparent, provided only the regenerated TIP body (tipname.pkb) is recompiled. If the TIP specification is also recompiled, the client application needs recompilation as well. Refer to Tip Internals for more detailed information.

Definition and generation of TIPs is accomplished as previously discussed in Chapters 1, 2, and 3. No additional options or parameters need be specified.

Run-time use of APPC conversation sharing is under the control of the client application. It is accomplished simply by calling the init function of one of the TIPs that share a conversation and passing the tranuse value returned to the other TIP functions as each is called in its desired order. Any TIP init function can be used, provided that all TIPs were defined with the same DEFINE TRANSACTION TPNAME or SIDEPROFILE value. The TPNAME or SIDEPROFILE value specifies which RHT to initialize.

When the init function of an APPC conversation sharing-capable TIP is called to initialize a conversation, the tranuse value returned indicates conversation sharing is enabled. By passing that same tranuse value when calling functions in other TIPs, those other TIPs perform their transfers on the same conversation already initialized, provided that all TIPs involved were generated at Version 3.4.0 or later.

TIPs generated at 3.4.0 or later of the database gateway use and expect different values for tranuse than do pre-3.4.0 TIPs. If a pre-3.4.0 TIP is used to initialize a conversation and its tranuse value is passed to a 3.4.0 or later generated TIP, the following exception is raised:

ORA-20704 PGA_TIP: tranuse value cannot be shared

Pre-3.4.0 generated TIPs do not detect the different tranuse value for shared conversations, however, and this can result in unpredictable errors.

The tranuse values are incompatible between pre-3.4.0 and 3.4.0 or later releases. This should not pose a problem for you for the following reason: before 3.4.0, all RHT functions defined in a TIP had to be called through that TIPs functions, and the init function of that same TIP had to be called first to initialize the conversation. The tranuse value was only valid for the TIP which initialized it. Thus, unless you make programming changes, it is not possible for an existing application to accidentally mix tranuse values.

Pre-3.4.0 TIPs and client applications can continue to be used without change and old client applications can call new 3.4.0 or later TIPs without change. This is made possible when an old TIP body is regenerated and compiled; the TIP now becomes capable of APPC conversation sharing, even though the old client application has not changed.

None of the functions of a pre-3.4.0 TIP can share an APPC conversation. However, once a TIP is regenerated at 3.4.0 or later, any of its functions can share APPC conversations.

You can use conversation sharing to circumvent a TIP that is too large to compile. This is identified by 'PLS-00123 - package too large to compile', or some other problem symptom such as PL/SQL compilation hanging. In this case you must choose which function calls to remove from the former TIP and define into new TIPs.

Specifically, you must decide which PGAU DEFINE CALL statements and their related DEFINE DATA statements should be moved from the old PGAU control file (.ctl) into one or more new PGAU control files. In addition, you must decide which PGAU DEFINE TRANSACTION statements should be included in each new PGAU control file defining each new TIP.

You must consider several PGAU statements; refer to Table 4-4 for a list of the PGAU statements and their descriptions:

Assume the existence of RHTs A, B and C, and that RHT A performs a menu selection and calls RHT B for a query function or RHT C for an update followed by a select function.

You could define the following DATA and CALLs:

• DEFINE DATA choice ...

• DEFINE DATA input ...

• DEFINE DATA answer ...

• DEFINE DATA record ...

• DEFINE CALL menu_A callname(pick) parms(choice in);

• DEFINE CALL query_B callname(query) parms((input in), (answer out));

• DEFINE CALL update_C callname(update) parms(record in);

• DEFINE CALL select_C callname(select) parms(record out);

The following example TIPs could be defined:

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); 

TIP default override parameters are processed in the TIP init function which was called to perform initialization. Once the APPC conversation is established, no further sharing of overriding parameters is necessary. You need do nothing more than pass the overrides to the TIP init function.

TIP diagnostic parameters are shared among all TIPs sharing a given conversation. In effect, requesting diagnostics of the TIP performing initialization causes the same diagnostics to be requested of all TIPs sharing the conversation. Requesting diagnostics from only one TIP of several sharing a conversation is not possible. The application designer or user need only pass the TIP runtime trace controls to the TIP init function.