Calling Application Engine Programs from COBOL

To facilitate the conversion of existing COBOL programs to Application Engine programs, you can call Application Engine programs from existing COBOL code.

This chapter discusses how to:

• Add copybooks to COBOL programs.

• Assign copybook values.

• Handle COBOL errors.

Adding Copybooks to COBOL Programs

To enable you to call Application Engine programs from COBOL programs, include the copybook called PTCCBLAE.CBL with your COBOL programs. This copybook is located in PS_HOME\src\cbl\base.

The following is the PTCCBLAE.CBL copybook.

*01  CBLAE.

NOCLN      02  CBLAE-PRCSNAME          PIC X(12)   VALUE SPACE.

NOCLN      02  CBLAE-COMMIT-FLAG       PIC X(1)    VALUE SPACE.

               88 AE-COMMITS-SUCCESS               VALUE 'B'.

               88 AE-COMMITS-ALL                   VALUE 'C'.

           02  CBLAE-PARMS.

               03  CBLAE-PARM-CNT      PIC 9(4)                COMP.

               03  CBLAE-PARM-ENT      OCCURS 500 TIMES.

                   05 CBLAE-STATEREC   PIC X(15).

                   05 CBLAE-FIELDNM    PIC X(18).

                   05 CBLAE-DATA-PTR               POINTER.

                   05 CBLAE-LENGTH     PIC 9999                COMP.

                   05 CBLAE-SCALE      PIC 99                  COMP.

NOCLN              05 CBLAE-TYPE       PIC X.

                       88  CBLAE-TYPE-CHAR         VALUE 'C'.

                       88  CBLAE-TYPE-SMALLINT     VALUE 'S'.

                       88  CBLAE-TYPE-INT          VALUE 'I'.

                       88  CBLAE-TYPE-DEC          VALUE 'P'.

                       88  CBLAE-TYPE-DATE         VALUE 'D'.

                       88  CBLAE-TYPE-TIME         VALUE 'T'.

                       88  CBLAE-TYPE-TIMEONLY     VALUE 'V'.

                       88  CBLAE-TYPE-NUMERIC      VALUE 'S' 'I' 'P'.

Data Transfer Process Between COBOL Programs and Application Engine Programs

To interface between COBOL programs and Application Engine programs, the process uses a file to pass parameters from COBOL to the Application Engine program. This file is owned by the process and has the prm extension. The location of the file is determined by the following:

• If an application server root directory is defined, the file resides in the output directory of that particular process instance.

• If the output directory on the application server is not defined, the file resides in the default output directory of the Process Scheduler domain..

• If neither one of the above is defined, the file is written to the default temp directory.

Assigning Copybook Values

To assign values to the calling COBOL program’s copybook to be passed as parameters into the state records of the called Application Engine program:

• Identify the fields in your COBOL program that contain the values you want to pass to the Application Engine program.

• Load the PTCCBLAE.CBL copybook with the state record name, field name, field length (this should be the size of the field not the size of the contents), the scale (decimal places if any), and set the field type.

• Call the PTPSETAD program to set the pointer in PTCCBLAE.CBL to the host programs variable.

• Set the variable AE-COMMIT-FLAG to either AE-COMMITS-ALL or AE-COMMITS-SUCCESS.

  AE-COMMITS-ALL means that the Application Engine program commits as specified in the program. AE-COMMITS-SUCCESS means that the Application Engine program ignores all commits and performs one commit at the end of successful execution.

Example of Loading Values from PTPTSTAE.CBL Sample Program

Make sure the calling COBOL program has successfully connected to the database before calling the PTPCBLAE copybook, and ensure that the calling program is not running through a RemoteCall function.

The following code shows an example of how to load values from the copybook:

MOVE 0 TO CBLAE-PARM-CNT OF CBLAE


           ADD  1 TO CBLAE-PARM-CNT OF CBLAE

           MOVE 'QE_CBLAETST_AET' TO CBLAE-STATEREC

                  OF CBLAE (CBLAE-PARM-CNT OF CBLAE)

           MOVE 'DESCR' TO CBLAE-FIELDNM

                  OF CBLAE (CBLAE-PARM-CNT OF CBLAE)

           MOVE 30 TO CBLAE-LENGTH

                  OF CBLAE (CBLAE-PARM-CNT OF CBLAE)

           MOVE 0 TO CBLAE-SCALE

                  OF CBLAE (CBLAE-PARM-CNT OF CBLAE)

           SET CBLAE-TYPE-CHAR OF CBLAE (CBLAE-PARM-CNT OF CBLAE)

                  TO TRUE

           CALL 'PTPSETAD' USING  CBLAE-DATA-PTR

                  OF CBLAE (CBLAE-PARM-CNT OF CBLAE)

                  W-DESCR OF W-WORK


           ADD  1 TO CBLAE-PARM-CNT OF CBLAE

           MOVE 'QE_CBLAETST_AET' TO CBLAE-STATEREC

                  OF CBLAE (CBLAE-PARM-CNT OF CBLAE)

           MOVE 'QE_AE_INT_7' TO CBLAE-FIELDNM

                  OF CBLAE (CBLAE-PARM-CNT OF CBLAE)

           MOVE 2 TO CBLAE-LENGTH

                  OF CBLAE (CBLAE-PARM-CNT OF CBLAE)

           MOVE 0 TO CBLAE-SCALE

                  OF CBLAE (CBLAE-PARM-CNT OF CBLAE)

           SET CBLAE-TYPE-SMALLINT 

   OF CBLAE (CBLAE-PARM-CNT OF CBLAE)

                  TO TRUE

           CALL 'PTPSETAD' USING  CBLAE-DATA-PTR

                  OF CBLAE (CBLAE-PARM-CNT OF CBLAE)

                  W-SMINT OF W-WORK


*

       DA000-CALL-AE SECTION.

       DA000.

*                                  

    MOVE 'QE_AETESTPRG' TO CBLAE-PRCSNAME OF CBLAE

           SET AE-COMMITS-ALL TO TRUE


       CALL 'PTPCBLAE' USING SQLRT CBLAE.

       CALL-AE-EXIT.

       EXIT.

Sample of the Communication Area of PTPBLAE.CBL

If the called Application Engine program updated the state records or fields that were passed by PTPCBLAE, they fields or records are stored in the calling program’s local variables as identified by PTPSETAD.

* PTCCBLAE - Communication area for PTPCBLAE                     *

*01  CBLAE.

NOCLN   02   CBLAE-PRCSNAME   PIC X(12)   VALUE SPACE.

*      Name of AE program to be called.

NOCLN   02   CBLAE-COMMIT-FLAG   PIC X(1)   VALUE SPACE.

*      Flag to determine which of the following commits to make.

           88 AE-COMMITS-SUCCESS         VALUE 'B'.

*      No in-process commit; if successful, then commit occurs.

           88 AE-COMMITS-ALL         VALUE 'C'.

*      Commits occur when defined in the AE program.

         02  CBLAE-PARMS.

           03  CBLAE-PARM-CNT   PIC 9(4)COMP.

*      Counter of the number of state records passed.

           03  CBLAE-PARM-ENT   OCCURS 500 TIMES.

*      Maximum value of state record entries.

             05 CBLAE-STATEREC   PIC X(15).

*      State record name.

             05 CBLAE-FIELDNM   PIC X(18).

*      Field name.

             05 CBLAE-DATA-PTR   POINTER.

*      Pointer to your own working storage area.

             05 CBLAE-LENGTH   PIC 9999   COMP.

*      Field length of defined state record.

             05 CBLAE-SCALE   PIC 99   COMP.

*      Number of decimal places.


NOCLN        05 CBLAE-TYPE      PIC X.

*      Field data type.

                88  CBLAE-TYPE-CHAR         VALUE 'C'.

                88  CBLAE-TYPE-SMALLINT     VALUE 'S'.

                88  CBLAE-TYPE-INT          VALUE 'I'.

                88  CBLAE-TYPE-DEC          VALUE 'P'.

                88  CBLAE-TYPE-DATE         VALUE 'D'.

                88  CBLAE-TYPE-TIME         VALUE 'T'.

                88  CBLAE-TYPE-TIMEONLY     VALUE 'V'.

                88  CBLAE-TYPE-NUMERIC      VALUE 'S' 'I' 'P'.

Handling COBOL Errors

If your COBOL program needs error handling, try the following process:

1. Add a field (return code) to your state record.

2. Initialize the field to a negative value.

3. Pass the value into the Application Engine program.

4. At the successful completion of the Application Engine program, change the field value to a positive value.

5. Check for that value in your COBOL program.