3
Creating a TIP

This chapter shows in detail how you can define, generate and compile a Transaction Interface Package (TIP). It assumes that a remote host transaction program (RTP) already exists. This transaction program has operational characteristics that dictate how the TIP is defined and how the TIP is used by the client application.

This chapter contains the following sections:

• Granting Privileges for TIP Creators

• Evaluating the RHT

• Writing the PGAU Statements

• Defining and Generating the TIP

• Compiling the TIP

• TIP Content Documentation (tipname.doc)

The following steps create a TIP for use with a remote host transaction (RHT):

• evaluating the RHT

• preparing the PGAU statements

• defining and generating the TIP

• compiling the TIP

This chapter also discusses the generated TIP content file.

Granting Privileges for TIP Creators

Every TIP developer requires access to the following PL/SQL packages, which are shipped with the Oracle server:

• DBMS_PIPE in $ORACLE_HOME/rdbms/admin

• UTL_RAW in $ORACLE_HOME/rdbms/admin

• UTL_PG in $ORACLE_HOME/rdbms/admin

If anyone other than the PG ADMIN will be developing TIPs, they will need explicit grants to perform these operations. Refer to the Optional Configuration Steps section in Chapter 4 of the Oracle Procedural Gateway for APPC Installation and Configuration Guide for your platform for more information about private and public grants.

Evaluating the RHT

Follow the steps below to identify and become familiar with your remote host transaction data exchanges.

Identify the Remote Host Transaction

1. You must first identify the RHT data exchange steps. These are the APPC send and receive calls embedded within the RHT program. They are identified under the following languages:
   • You may use IBM VS/COBOL II for:
     • CICS

     • IMS

   • You may use IBM 370 Assembler for:
     • CICS

     • IDMS

     • IMS

   • You may use IBM REXX for:
     • CICS

     • IDMS

     • IMS

     • MVS

PGAU DEFINE CALL Command

2. Make a call list of every data exchange. This list dictates a series of PGAU DEFINE CALL statements. Refer to "DEFINE CALL" in Chapter 2, "Procedural Gateway Administration Utility" for more information about this PGAU command.

   The three important parameters that you will use for each call are:

   • cname: the name of the call definition to be created;

   • dname: the name of the data structure to be exchanged; and

   • whether it is send (OUT) or receive (IN)

   RHT send corresponds to a TIP OUT and RHT receive corresponds to a TIP IN. Refer to "APPC Send/Receive Synchronization" for more information.

   PGAU call entries are only defined once, so eliminate any duplicates.

   This call list defines the TIP function calls, not the order in which they are used. Note that the order in which each call is made is a behavior of the transaction and dictates the order of calls made by the high-level application to the TIP, which then calls the RHT through the Procedural Gateway server. While this calling sequence is critical to maintaining the synchronization between the application and the RHT, the TIP is only an access method for the application and has no knowledge of higher level sequencing of calls.

DEFINE PGAU Command

3. For each call in the RHT call list, identify the RHT data structures being sent or received in the call buffers.

   Make a data list of every such structure. This list dictates a series of PGAU DEFINE DATA statements.

   The two important parameters that you will use for DEFINE DATA are:

   • dname: the name of the data definition to be created; and

   • dname.ext: the file in which the data definition is stored.

   PGAU data entries are only defined once, so eliminate any duplicates.

   Note: Move COBOL record layouts (copybooks) to the gateway machine. PGAU can use copybooks as input when defining the data items. Once you have identified the data items to be exchanged, use a file transfer program to download the copybooks to the gateway machine. The copybooks are later used to define the data items. The sample copybook used in the example is documented in Appendix E, "Administration Utility Samples".

   PGAU DEFINE TRANSACTION Command

   4. Determine the network address information for the RHT program. Your network or OLTP system programmer can provide you with this information.

      The five important parameters that you will use for PGAU DEFINE TRANSACTION are:

      • Side Profile name

      • TP name

      • LU name

      • LOGMODE

      • SYNCLEVEL

      You must also identify the Oracle NLS character set (charset) for the language in which the OLTP expects the data.

   Writing the PGAU Statements

   After evaluating the RHT, define the TIP to PGAU for placement in the PG DD.

   1. Write a DEFINE DATA statement for each entry in your data list. If, for example, your RHT had three different data structures, your data definitions might be:

      DEFINE DATA dname1 LANGUAGE(IBMVSCOBOLII) INFILE(dnamel.ext);
      DEFINE DATA dname2 LANGUAGE(IBMVSCOBOLII) INFILE(dname2.ext);
      DEFINE DATA dname3 LANGUAGE(IBMVSCOBOLII) INFILE(dname3.ext);
      
      

      Then you must copy or transfer the source file containing these data definitions to the directory where PGAU can read them as input.

   2. Write a DEFINE CALL statement for each entry in your call list. If, for example, your RHT had a receive send receive send sequence, your call definitions would be:

      DEFINE CALL cname1 PARMS((dnamel IN));
      DEFINE CALL cname2 PARMS((dname2 OUT));
      DEFINE CALL cname3 PARMS((dname3 IN));
      DEFINE CALL cname4 PARMS((dname2 OUT));
      

      NOTE: Optionally, you can rewrite your call definitions to consolidate the data transmission into fewer exchanges, as long as you do not alter the data transmission sequence. For example: DEFINE CALL cname1 PARMS((dname1 IN), (dname2 OUT)); DEFINE CALL cname3 PARMS((dname3 IN), (dname2 OUT)); This reduces the calls between the application and the TIP from four calls to two calls passing an IN and OUT parameter on each call. Because TIPs always process IN parameters before OUT parameters, the data transmission sequence is unchanged. However, this consolidation is not always possible. Refer to "APPC Send/Receive Synchronization" for more information.

   3. Write a DEFINE TRANSACTION statement that contains every call, specifying the network address and NLS information:

      DEFINE TRANSACTION tname CALLS(cname1
                                     cname2, ....
                                     cnameN)
                         ENVIRONMENT(IBM370)
                         SIDEPROF(profname) |
                           TPNAME(tpid) LUNAME(luname) LOGMODE(mode)
                         SYNCLEVEL(n)
                         NLS_LANGUAGE(charset);
      
      

   4. You can add a GENERATE statement to create the TIP specification:

      GENERATE tname 
      

      Note: You can also add a REPORT statement to list the PG DD entries for tname: REPORT TRANSACTION tname with CALLS with DATA; Also annotate the script with Comments: # this is a Comment

   Writing a PGAU Script File

   The previous section describes the three steps you need to follow in order to execute PGAU statements via your PGAU command line processor. As a time saving measure, you can choose to write all of the statements (DEFINE DATA, DEFINE CALL, AND DEFINE TRANSACTION) into a single PGAU script file named tname.ctl, in the following order:

   • define data

   • define call

   • define transaction

   • generate

     Warning: Because you will probably run this script more than once, you should include UNDEFINE statements first to remove any previous entries in the PG DD.

   This is an example of a tname.ctl PGAU script file:

   UNDEFINE TRANSACTION tname Version(all);
   UNDEFINE CALL cname1 Version(all);
   UNDEFINE CALL cname2 Version(all);
   UNDEFINE DATA dname1 Version(all);
   UNDEFINE DATA dname2 Version(all);
   UNDEFINE DATA dname3 Version(all);
   DEFINE DATA dname1 LANGUAGE(IBMVSCOBOLII) INFILE(dnamel.ext);
   DEFINE DATA dname2 LANGUAGE(IBMVSCOBOLII) INFILE(dname2.ext);
   DEFINE DATA dname3 LANGUAGE(IBMVSCOBOLII) INFILE(dname3.ext);
   DEFINE CALL cname1 PARMS(dname1 IN),
                             (dname2 OUT));
   DEFINE CALL cname2 PARMS(dname3 IN),
                            (dname2 OUT));
   DEFINE TRANSACTION tname CALLS(cname1,
                                 cname2, ....
                                 cnameN)
                      ENVIRONMENT(IBM370)
                      SIDEPROF(profname) |
                        TPNAME(tpid) LUNAME(luname) LOGMODE(mode)
                      SYNCLEVEL(n)
                      NLS_LANGUAGE(charset);
   Generate tname
   

   Defining and Generating the TIP

   After you have created your control file, use PGAU to create the PG DD entries and the TIP specification files.

   Note: The user ID under which you run PGAU must have: write access to output the specification files (pgau.pkh, pgau.pkb, and pgau.doc), where pgau is the default name; and read access to the data definition source files (dname.ext), where dname.ext will be specified in PGAU DEFINE DATA statement(s).

   Invoke PGAU against your PG DD stored in the Oracle Procedural Gateway for APPC Administrator's user ID:

   $ pgau
   PGAU> connect pgaadmin/pw@database_specification_string 
   
   

   Issue the following commands:

   $PGAU> set echo on
   PGAU> spool tname.def
   PGAU> @tname.ctl
   PGAU> spool off
   
   

   The TIP is now ready to be compiled. By default, the GENERATE statement writes your TIP specifications to the following output files in your current directory:

   pgau.pkh (TIP Header)
   pgau.pkb (TIP Body)
   pgau.doc (TIP content documentation)
   
   

   Note: You can optionally add spool and echo to your script (tname.ctl) or make other enhancements, such as using PG DD roles and the PGAU GROUP statement for shared PG DDs. Refer to Chapter 4, "Client Application Development" for more information.

   Compiling the TIP

   Exit PGAU. Remain in your current directory and invoke SQL*Plus.

   $ sqlplus userid/pw@database_specification_string
   SQL> set echo on
   SQL> @pgau.pkh
   SQL> @pgau.pkb
   
   

   The last two commands compile the TIP specification and body, respectively.

   You have now compiled a TIP which can be called by your client application. If your client application is already written you can begin testing.

   For more information about designing your client application and compiling a TIP, refer to Chapter 1, "Introduction to Oracle Procedural Gateway for APPC" and Appendix B, "TIP Internals" and refer to Chapter 4, "Client Application Development" for information about PGAU statement syntax and usage.

   TIP Content Documentation (tipname.doc)

   This section discusses the TIP documentation file that is produced when the user issues a PGAU GENERATE command. This TIP content file describes the function calls and PL/SQL variables and datatypes available in the TIP.

   PGAU GENERATE always produces a TIP content file named tipname.doc. The filename is the name of the transaction that was specified in the PGAU GENERATE command, and the filetype is always .doc. This TIP content file contains the following sections:

   • GENERATION Status

     This section contains the status under which the TIP is generated.

   • TIP Transaction

     This section identifies the defined transaction attributes. These result from the PGAU DEFINE TRANSACTION definition.

   • TIP Default Calls

     This section identifies the syntax of the calls made by the user's application to initialize and terminate the transaction. PGAU generates these calls into every TIP regardless of how the TIP or transaction is defined.

   • TIP User Calls

     This section identifies the syntax of the calls which the user defines for the application to interact with the transaction.

   • TIP User Declarations

     This section identifies the TIP package public datatype declarations, implied by the user's data definition specified in each call parameter.

   • TIP User Variables

     This section contains TIP variables that can be referred to by applications or referenced by applications.