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:
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.
Every TIP developer requires access to the following PL/SQL packages, which are shipped with the Oracle server:
If anyone other than user PGAADMIN will be developing TIPs, they will need explicit grants to perform these operations. Refer to the "Optional Configuration Steps" section in the configuration chapter appropriate to your communication protocol in the Oracle Procedural Gateway for APPC Installation and Configuration Guide for more information about private and public grants.
Follow the steps below to identify and become familiar with your remote host transaction data exchanges.
You must first identify the RHT data exchange steps. These are the send and receive calls embedded within the RHT program.
If your gateway is using the SNA communication protocol:
The RHT data exchange steps are identified under the following languages:
You may use COBOL for:
CICS
IMS
You may use IBM 370 Assembler for:
CICS
IDMS
IMS
You may use IBM REXX for:
CICS
IDMS
IMS
z/OS
If your gateway is using the TCP/IP communication protocol:
IMS is the only OLTP that is supported when the gateway is using TCP/IP support for IMS Connect. The RHT programs must use embedded I/O PCB function calls. The function is identified only under the COBOL and Assembler languages.
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.
If your communication protocol is SNA: Refer to Section 4.6.2.1, "Flexible Call Sequence" for more information about PGAU DEFINE CALL commands.
If your communication protocol is TCP/IP: Refer to Section 7.3.2.1, "Flexible Call Sequence" for more information about PGAU DEFINE CALL commands.
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.
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 system.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 system. The copybooks are later used to define the data items. The sample copybook used in the example is documented in Appendix G, "Administration Utility Samples".
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.
At this point, if your gateway is using SNA, then proceed to Section 3.2.6, "Writing the PGAU Statements".
Before you use this command, you will need to know the IMS Connect hostname (or TCP/IP address), port number and the other IMS Connect parameters that are defined as columns within the PGA_TCP_IMSC table. Refer to Chapter 6, "PG4TCPMAP Commands (TCP/IP Only)" for complete information about preparation for mapping parameters to TCP/IP using the pg4tcpmap tool.
When you run the pg4tcpmap tool you need to specify a unique name (Side Profile Name). That name must be the same name that you are using here to create your TIP.
If you are converting your gateway from the SNA to a TCP/IP communications protocol to invoke IMS transactions: You need to regenerate the TIPs. Refer to Chapter 2, "Procedural Gateway Administration Utility" for details.
After evaluating the RHT, define the TIP to PGAU for placement in the PG DD.
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.
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.
If your communication protocol is SNA: Refer to Section 4.6.2.1, "Flexible Call Sequence" for more information about PGAU DEFINE CALL commands.
If your communication protocol is TCP/IP: Refer to Section 7.3.2.1, "Flexible Call Sequence" for more information about PGAU DEFINE CALL commands.
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);
You can add a GENERATE statement to create the TIP specification:
GENERATE tname
The previous section describes the 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
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
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:
C:\> 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.
If your gateway is using SNA: Refer to Chapter 4, "Client Application Development (SNA Only)" for more information.
If your gateway is using TCP/IP support for IMS Connect: Refer to Chapter 7, "Client Application Development (TCP/IP Only)" for more information.
Exit PGAU. Remain in your current directory and invoke SQL*Plus.
C:\> 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 F, "Tip Internals".
If your gateway is using SNA: Refer to Chapter 4, "Client Application Development (SNA Only)" for information about PGAU statement syntax and usage.
If your gateway is using TCP/IP support for IMS Connect: Refer to Chapter 7, "Client Application Development (TCP/IP Only)" for information about PGAU statement syntax and usage.
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:
This section contains the status under which the TIP is generated.
This section identifies the defined transaction attributes. These result from the PGAU DEFINE TRANSACTION definition.
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.
This section identifies the syntax of the calls which the user defines for the application to interact with the transaction.
This section identifies the TIP package public datatype declarations, implied by the user's data definition specified in each call parameter.
This section contains TIP variables that can be referred to by applications or referenced by applications.