3 Creating a TIP

3.2.1 Identify the Remote Host Transaction

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

  • IMS

• You may use IBM REXX for:

  • CICS

  • 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.

3.2.2 PGAU DEFINE CALL Command

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 Database 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.

3.2.3 PGAU DEFINE DATA Command

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.

3.2.4 PGAU DEFINE TRANSACTION Command on a Gateway Using SNA

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 Globalization Support 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".

3.2.5 PGAU DEFINE TRANSACTION Command on a Gateway Using TCP/IP

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.

3.2.6 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.

   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.

3. Write a DEFINE TRANSACTION statement that contains every call, specifying the network address and Globalization Support 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:

   REM this is a Comment

3.2.7 Writing a PGAU Script File

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:

1. define data

2. define call

3. define transaction

4. generate

   Caution:

   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