Calling COBOL Modules

Using the PeopleCode RemoteCall function, you can call COBOL modules from a PeopleCode action. This option supports existing Application Engine programs that call COBOL modules. You also can use it to upgrade Application Engine programs from previous releases.

PTPECOBL Program

The PTPECOBL interface program is a PeopleSoft executable that enables you to invoke your called COBOL module and pass it required values. You code the RemoteCall function to invoke PTPECOBL, which in turn calls the specified COBOL module.

If you use PTPECOBL, you do not have to write your own executable to process this task. However, PTPECOBL does not perform any SQL processing other than retrieving a list of state record values. Consequently, if your current logic requires previous SQL processing, you may want to write your own executable file to call your COBOL module. In most situations, PTPECOBL saves you from having to write a custom executable file to handle each call to a generated dynamically loadable code (.GNT) file.

PTPECOBL performs the following tasks:

  1. Initializes the specified state record in memory.

  2. Invokes the COBOL module specified in your PeopleCode.

  3. Submits required parameters to the called COBOL module.

  4. Updates the state record as necessary, issues a commit, and then disconnects from the database after your program completes.

Note:

While your COBOL program runs, it can access and return values to the state record.

Shared Values in Application Engine and COBOL

The following options are available for sharing values between the Application Engine program and a called COBOL program:

  • Use state records.

    If you add field names, Application Engine enables you to pass state record values to the called COBOL program and to get changes passed back to the calling PeopleCode program. If you pass the state record values in this way, use PTPECACH to retrieve and update values just as PTPEFCNV does.

  • Code custom SQL.

    If you do not pass initial values using state record fields, you need to insert the appropriate SQL in your called COBOL module to retrieve the appropriate values. Then, to return any updated values to the calling Application Engine program, you must insert the appropriate SQL into a PeopleCode program.

    If your COBOL program needs values that do not appear in a state record field, then you can pass PeopleCode variables and values. These variables and values are then retrieved and updated by calling PTPNETRT from within your COBOL program.

  • Create a custom executable file.

    If you include extra SQL processing and use non-state record values, for consistency purposes, creating a custom executable file might be a better approach. It enables you to call your program directly and have it perform all the PTPNETRT processing. Remember that a RemoteCall command can only call an executable program, not a GNT file.

Syntax and Parameters

This example shows a sample RemoteCall function issued from an Application Engine PeopleCode action to a COBOL module:

RemoteCall ("PSRCCBL",?
 "PSCOBOLPROG", "PTPECOBL",?
 "AECOBOLPROG", "MY_GNT",?
 "STATERECORD", "MY_AET",?
 "PRCSINST", MY_AET.PROCESS_INSTANCE,?
 "RETCODE", &RC,?
 "ERRMSG", &ERR_MSG,?
 "FIELD1", MY_AET.FIELD1,?
 "FIELD2", MY_AET.FIELD2);

This table describes each parameter in the RemoteCall function:

Parameters Description

PSRCCBL

The Remote Call dispatcher, which runs the specified COBOL program using the connect information of the current operator.

PSCOBOLPROG

Specify the name of the COBOL program to run, which in this case is PTPECOBL.

This parameter makes the remote call from Application Engine distinct from a normal remote call. When you enter this parameter, in effect you enable the following parameters, some of which are required.

AECOBOLPROG

Specify the name of the COBOL module you are calling; for example, MY_GNT.

STATERECORD

Specify the appropriate state record that your Application Engine program will share with your COBOL module; for example, MY_AET. PTPECOBL then reserves space in memory for all of the fields in the state record, regardless of whether they will ultimately store values for processing.

PRCSINST

Specify the state record and Process Instance field; for example, MY_AET.PROCESS_INSTANCE. This setting retrieves the current process instance value that appears on the state record and submits it to your COBOL module using PTPECOBL.

RETCODE and ERRMSG

(Optional) Include RETCODE if you need to return information about any potential problems that the COBOL processing encountered, or use it if your Application Engine program must know whether it completed successfully.

Fieldnames and Values

Specify any fields in the state record that contain initial values for your COBOL module. The quoted field names you specify must exist in the specified state record. The corresponding value can be a PeopleCode variable, a record.field reference, or a hard-coded value.

Commit and RemoteCall

When using RemoteCall and an Application Engine program:

  • The called COBOL module runs as a separate unit of work.

  • Run a commit in the step immediately preceding the step containing the RemoteCall PeopleCode action and also in the step containing the Remote Call PeopleCode action.

    These two actions enable the COBOL process to recognize the data changes made up to the point that it was called, and minimizes the time when the process might be in a non-restartable state.

  • If you insert SQL processing into your COBOL module, your module makes commit updates.

    PTPECOBL does not issue any commits.

  • If the intent of your COBOL process is to update the value of a passed state record field, then the calling Application Engine PeopleCode is responsible for ensuring that the state record field is modified, and the Application Engine program is responsible for committing the state record updates.

  • Consider how your COBOL module will react in the event of a restart.

    Because the work in COBOL will have already completed and been committed, will your module ignore a duplicate call or be able to undo or redo the work multiple times? You face similar issues when you run a remote call from PeopleCode.

  • Typically, when a COBOL program updates the database and then disconnects or terminates without having issued an explicit commit or rollback, an implicit rollback occurs.

    Without an explicit commit, the database does not retain any updates.

Note:

By default, RemoteCall does not generate any log files after the program completes. To generate and retain the .out and .err log files, you must set the RCCBL Redirect parameter in the PeopleSoft Process Scheduler configuration file to a value of1.

See PeopleCode Language Reference: RemoteCall function.

Related Topics