gtpa3m0oApplication Requester User's Guide

Preparing an Application

Figure 15 shows the basic flow of transforming an application from source code to object code on TPF and into a bind file on DB2 through the DB2 bind process. The bind process converts output from a DB2 precompiler (DBRM) to the usable control structure known as a bind file. During this process, complete error checking and access strategy is performed for each SQL command. In ISO-C programs, you can perform binding directly on DB2 offline (static binding) before you run the application. Alternatively, TPF can perform a bind at run time (run-time binding).

Figure 15. Overview of TPF Application Preparation




TPF application programs must be precompiled using the DB2 precompiler on the MVS system. The DB2 program preparation procedure is described in the IBM Database 2 Application Programming and SQL Guide.

The following explains each of the steps in Figure 15.

Note:
You must ensure that the object code from the modified source produced from the DB2 precompiler matches the package produced by the database-request-module bind process from the DB2 precompiler.
  1. The TPF application is written in C or assembler with imbedded SQL commands.
  2. The DB2 precompiler extracts the SQL commands from the TPF application and places them in a database request module (DBRM). The DBRM is a data set member containing information about SQL commands. This data set contains information on all SQL commands used in your application program. Information is included about how the SQL commands are executed and DB2's access strategy.

    In place of the SQL commands, the DB2 precompiler places host language system calls into the application programs.

    The following parameters are important to the DB2 precompiler:

    DEC
    Specifies the maximum precision to be used in decimal arithmetic operations. This parameter must be set to DEC(15) for use with TPFAR. This parameter is ignored for C programs.

    HOST
    Informs the DB2 precompiler about which host language is being used. This parameter must be set to one of the following:
    • HOST(C) for TARGET(TPF) programs or ISO-C programs
    • HOST(ASM) for assembler programs.

    See Using the TPF DB2 Postprocessor (TPF DB2PP) for more information about the TPF DB2PP HOST parameter.

    VERSION
    Allows the DB2 precompiler to separate two different applications with the same name, so that the bind files created are not the same. This is important when supporting multiple copies of the same program (that is, when using the TPF online loader and fallback packages).

    Supporting multiple versions can also be accomplished by changing the member name of the DBRM data set where the DB2 precomplier places the output DBRM. This member name is what DB2 uses to correlate different DB2 packages. By changing the DBRM member for different versions of the same program, multiple copies of the same program can have active DB2 packages. See step 5 for more information on DB2 packages.

    Note:
    For DB2 Version 3, you must specify the CONNECT(1) precompiler option to specify the rules for the CONNECT (Type 1) statement. The TPF system does not support the CONNECT (Type 2) option.

    See the IBM DATABASE 2 Command and Utility Reference for more information regarding the DB2 precompiler options.

  3. C language programs that are output from the DB2 precompiler are then run through the TPF DB2 postprocessor (TPF DB2PP), an offline program generated by SIP that alters some of the DB2 global variables placed in the program. (This step is not performed on assembler language programs.) See Using the TPF DB2 Postprocessor (TPF DB2PP) for more information on this program.
  4. The modified assembler or C programs are assembled or compiled. Care must be taken at this point to check the output. Because the DB2 precompiler has added code to the segments, you must check the size of the program to make sure that it fits in the segment if you are using assembler or TARGET(TPF). The amount of code added depends on individual SQL commands and their parameters. After this has been checked, the programs can be loaded to the TPF system using the online loader package.
    Note:
    When you are compiling an ISO-C program, the RENT option should be specified.
  5. The DBRM, also referred to as a bind file, must be bound on the DB2 subsystem that is to connect to the TPF system. This bind process can run on the application server containing the target relational database before the TPF application can access this system. Target C programs and assembler programs must be bound offline. ISO-C programs can be bound offline or online at run-time. Run-time binding for ISO-C programs is automatic. For Target C and assembler programs, any attempt to run a TPF application before the DBRM has been bound results in an error.

    The output from the bind process is called a package. A package is an object containing a set of SQL statements that have been bound and are available for processing.

    The DB2 package is called at program execution time to execute the SQL commands extracted from the program during DB2 precompilation. (See step 2.) The package is in a format understood only by the DB2. The DBRM could be transported to another MVS system, using MVS system utilities for example, and bound on the second system if the TPFAR application is to also connect and to work on this second system.

    When binding the DBRM, the following options are required:

    PACKAGE or COLLECTION-ID
    Must be the same as that used by TPFAR, which is made up of the TPF:
    • complex name
    • subsystem name
    • subsystem user name.

    Each of these pieces is separated by an underscore (_). For example, the parameter could be:

        TPFNET_BSS_HPN
    

    When running the bind process in a batch mode, the parameter is specified as PACKAGE. When running the bind process through the DB2 interactive panels, the parameter is specified at the COLLECTION-ID entry field. Both PACKAGE and COLLECTION-ID refer to the same value.

    RELEASE
    Specifies when the application server (AS) can release the resources reserved for this conversation or connection. This option must be COMMIT when using hotcons because TPF reuses this session if another program requests a connection to the same AS. If RELEASE was DEALLOCATE, these AS resources would continue to be held until the session was deallocated. When using hotcons, the deallocation may not happen for quite a while.

    MEM
    Indicates the member that is to be bound. This option must be the same as the member name used for the partitioned data set in which the DBRM output was placed in the DB2 precompiler.

    See the IBM DATABASE 2 Command and Utility Reference for more information about the bind options.

Using the TPF DB2 Postprocessor (TPF DB2PP)

When writing a C application using SQL, the TPF DB2 postprocessor (TPF DB2PP) offline module needs to be run against the DB2 precompiler output. The TPF DB2PP program alters and removes some variables that the DB2 precompiler sets up for the TPF C compiler with the TPF option to run successfully.

If the modified C program is not run through TPF DB2PP before C compiling, the program does not compile. Table 2 shows the strings that are altered by the TPF DB2PP program for C programs.

Table 2. Strings Altered by TPF DB2PP for C Programs

Original String Altered String
#pragma linkage (DSNHLI,OS); (This field is removed by the TPF DB2PP program. The C header file tpfarapi.h will resolve the DSNHLI call.)
char SQLTEMP??( 19 ??); static char SQLTEMP??(19??);
struct sqlca sqlca; static struct sqlca sqlca;
struct SQLVTAG SQLVERS static struct SQLVTAG SQLVERS
char DSNPNM??( 57 ??); static char DSNPNM??( 57 ??);
Note:
Trigraph representations of square brackets are used in the preceding examples. The DB2 precompiler output may not always contain the trigraph representation. Regardless of which representation is used by the DB2 precompiler, DB2PP will always alter the string using the trigraph representation.

Invoking TPF DB2PP

TPF DB2PP has different required PARM parameters, depending on whether an ISO-C or a TARGET(TPF) program is to be processed.

If an ISO-C program is being postprocessed, there are two required parameters. Any additional parameters result in an error.

HOST
The HOST parameter specifies the language of the host program to the TPF DB2PP program. This parameter must be set to HOST(ISOC).

PKGISO
The PKGISO parameter specifies the package isolation level, a security technique for DB2 packages, to be passed during the bind process. Acceptable values for this parameter are CS and RR. Any other value specified results in an error from TPF DB2PP. A typical PARM parameter specification is:
       PARM='HOST(ISOC) PKGISOL(CS)'

If a TARGET(TPF) program is being postprocessed, there is one required parameter. Any additional parameters result in an error.

HOST
The HOST parameter specifies the language of the host program to the TPF DB2PP program. You must set this parameter to HOST(C).
       PARM='HOST(C)'

Sample JCL

Figure 16 shows sample JCL that you can use to process the output from the DB2 precompiler. The HOST(ISOC) and package isolation level PKISOL are also shown.

Note:
The INFILE data set specified must be the data set where the DB2 precompiler placed the modified output file.

Figure 16. Sample JCL to Run TPF DB2PP

  //MODIFY  EXEC PGM=DB2PP,REGION=4096K,PARM='HOST(ISOC) PKGISOL(CS)'
  //STEPLIB   DD DSN=AR20000.DEVP.TEST.LK,DISP=SHR
  //          DD DSN=ACP.LINK.INTG40.BSS,DISP=SHR
  //          DD DSN=ACP.LINK.RLSE31.BSS,DISP=SHR
  //          DD DSN=SYS1.CEE.SCEERUN,DISP=SHR
  //SYSPRINT  DD SYSOUT=*
  //INFILE    DD DSN=&&DSNHOUT,DISP=(OLD,DELETE)
  //DBRMLIB   DD DSN=AR20000.DEVP.TEST.DBRM(QXMARF),DISP=(OLD,PASS)
  //OUTFILE   DD DSN=&&TEMP,DISP=(NEW,PASS),UNIT=SYSDA,
  //          DCB=(DSORG=PO,RECFM=FB,LRECL=80,BLKSIZE=80)
  //*
  //COPY    EXEC PGM=IEBGENER,REGION=58K
  //SYSPRINT  DD SYSOUT=A
  //SYSIN     DD DUMMY
  //SYSUT2    DD DSN=TPFAR.TEST.SRCE(QXP1JV),DISP=OLD
  //SYSUT1    DD DSN=&&TEMP,DISP=(OLD,PASS)
  //*