Using PeopleCode to Invoke Application Engine Programs

To call a specific Application Engine program from a page using PeopleCode, use the CallAppEngine function in SavePreChange or SavePostChange PeopleCode. The basic syntax for CallAppEngine is:

CallAppEngine(applid[, statereclist, processinstance, allowcommit]

Note:

The RemoteCall function is no longer valid for invoking Application Engine programs in PeopleCode. However, the RemoteCall function still applies to calling other COBOL functions. If you do not convert the RemoteCall PeopleCode that previously called an Application Engine program to use the new function, an error message appears.

Use CallAppEngine if the program you are invoking is a quick process. Because the process is synchronous, users must wait for any process invoked by CallAppEngine to complete before starting another process. If the called program causes an unreasonable delay, then use another alternative, such as the ScheduleProcess PeopleCode function.

Use CallAppEngine when you have a complex, SQL-intensive business process that must run in batch and online, or the process requires the use of dedicated temporary tables. If this is not the case, you are usually better off writing the entire program in native PeopleCode. If you have written logic in PeopleCode, presumably for online execution, and you want to reuse it in a batch program, you may be forced into row-by-row processing. Design the batch logic first and then decide whether to have a separate online version or reuse the batch code using CallAppEngine. Consider the trade-off between code reuse and performance. It is inherently more difficult, but not impossible, to develop a common solution that performs adequately in both batch and online environments.

If you use CallAppEngine within an Application Engine PeopleCode step, you must do so carefully and selectively. See the “Application Engine Considerations” section in PeopleCode Language Reference: CallAppEngine function. If you need to call an Application Engine program from another Application Engine program, you can also use the Call Section action.

Do not use CallAppEngine to control the commit operation. Programs called with CallAppEngine are embedded within a larger unit of work defined by the page trigger, such as a page save.

However, the allowcommit option allows you to specify whether intermediate commits should be allowed in an online Application Engine program. Online Application Engine programs run in the context of application server. When the intermediate commits are enabled, the transactions that are in the context of the Application Engine program up to that commit are committed. None of the other transactions that are in the same Jolt request and are outside the context of the Application Engine program are committed. This is achieved by the use of a secondary connection to the database. Therefore, secondary connection must be enabled for this application server domain using the database flags (DbFlags) in the application server configuration file. Note that the secondary connections are enabled by default. If the secondary connection to the database is disabled and CallAppEngine is invoked with allowcommit set to True, the functionality will fall back to the default where all transactions are committed only at the end of an Application Engine program.

Important:

There is no mechanism to rollback or clear the transactions that have been committed on behalf of online Application Engine programs. In case of an error or unexpected program termination, you are responsible for rolling back transactions if necessary.

Note:

Online PeopleCode that calls CallAppEngine should be set to run on the application server. You encounter performance issues if you run PeopleCode on the client in a three-tier configuration because every SQL statement that Application Engine issues must be serialized and then sent to the application server to be run.