Calling COBOL Modules

调用COBOL模块

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.

使用PeopleCode RemoteCall函数，可以从PeopleCode操作调用COBOL模块。此选项支持调用COBOL模块的现有应用程序引擎程序。您还可以使用它来升级以前版本的应用程序引擎程序。

PTPECOBL Program

PTPECOBL程序

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.

PTPECOBL接口程序是一个PeopleSoft可执行程序，它使您能够调用所调用的COBOL模块并向其传递所需的值。编写RemoteCall函数来调用PTPECOBL，而PTPECOBL又调用指定的COBOL模块。

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，则不必编写自己的可执行文件来处理此任务。但是，除了检索状态记录值列表之外，PTPECOBL不执行任何SQL处理。因此，如果您当前的逻辑需要以前的SQL处理，您可能需要编写自己的可执行文件来调用您的COBOL模块。在大多数情况下，PTPECOBL使您不必编写自定义可执行文件来处理对生成的动态可加载代码（.GNT）文件的每次调用。

PTPECOBL performs the following tasks:

PTPECOBL执行以下任务:

1. Initializes the specified state record in memory.

初始化内存中的指定状态记录。

1. Invokes the COBOL module specified in your PeopleCode.

调用PeopleCode中指定的COBOL模块。

1. Submits required parameters to the called COBOL module.

向调用的COBOL模块提交所需的参数。

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

注意：当COBOL程序运行时，它可以访问状态记录并返回值。

Shared Values in Application Engine and COBOL

应用程序引擎和COBOL中的共享值

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

下列选项可用于在Application Engine程序和被调用的COBOL程序之间共享值：

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

如果添加字段名，Application Engine允许您将状态记录值传递给被调用的COBOL程序，并将更改传递回调用PeopleCode程序。如果以这种方式传递状态记录值，则使用TP PEC ACH来检索和更新值，就像PTPEF CNV所做的那样。

• Code custom SQL.
• 代码自定义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.

如果不使用状态记录字段传递初始值，则需要在被调用的COBOL模块中插入适当的SQL来检索适当的值。然后，要向调用应用程序引擎程序返回任何更新的值，必须将适当的SQL插入到PeopleCode程序中。

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.

如果您的COBOL程序需要的值没有出现在状态记录字段中，那么您可以传递PeopleCode变量和值。然后通过从COBOL程序中调用PTPNETRT检索和更新这些变量和值。

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

这个示例显示了从应用程序引擎PeopleCode操作向COBOL模块发出的RemoteCall函数示例:

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:

下表描述了RemoteCall函数中的每个参数:

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:

使用RemoteCall和应用程序引擎程序时:

• The called COBOL module runs as a separate unit of work.
• 被调用的COBOL模块作为单独的工作单元运行。
• 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.
• 在包含RemoteCall PeopleCode动作的步骤之前的步骤以及包含RemoteCall PeopleCode动作的步骤中运行提交。

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.

这两个动作使COBOL流程能够识别到调用它之前所做的数据更改，并将流程可能处于不可重新启动状态的时间减到最少。

• If you insert SQL processing into your COBOL module, your module makes commit updates.
• 如果您在COBOL模块中插入SQL处理，那么您的模块将进行提交更新。

PTPECOBL does not issue any commits.

PTPECOBL不发出任何提交。

• 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.
• 如果你的COBOL进程的意图是更新一个传递的状态记录字段的值，那么调用的应用引擎PeopleCode负责确保状态记录字段被修改，应用引擎程序负责提交状态记录更新。
• Consider how your COBOL module will react in the event of a restart.
• 考虑您的COBOL模块在重新启动时的反应。

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.

因为COBOL中的工作已经完成并提交，您的模块是否会忽略重复调用，或者能够多次撤消或重做工作？当您从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.
• 通常，当一个COBOL程序更新数据库，然后断开连接或终止，而没有发出显式的提交或回滚时，就会发生隐式回滚。

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 of 1.

附注：默认情况下，RemoteCall在程序完成后不会生成任何日志文件。生成并保留.out和.err日志文件，则必须将PeopleSoft进程计划程序配置文件中的RCCBL重定向参数设置为值1。

See “RemoteCall” (PeopleCode Language Reference).

见“远程调用”（人代码语言参考）

Related Links

“Editing the PeopleSoft Process Scheduler Configuration File” (Process Scheduler)

相关链接编辑PeopleSoft进程调度器配置文件（进程调度程序）