This section provides an overview of program run options and discusses how to:
You run Application Engine programs in one of the following modes: batch using PeopleSoft Process Scheduler, online using a PeopleCode function, or manually using the command line. The following table lists some differences between online and batch programs:
Started by the CallAppEngine function from PeopleCode.
Started through PeopleSoft Process Scheduler.
Program runs quickly, synchronously, and at random times.
Programs run for longer amounts of time, asynchronously, and at scheduled times.
Potential for simultaneous runs.
Can be designed for parallel runs for performance.
Uses the online temporary table pool.
Uses the batch/dedicated temporary table pool.
The most typical run mode is batch. You invoke programs that run in this mode using PeopleSoft Process Scheduler or the Application Engine Process Request page. Batch mode is also referred to as an asynchronous run, meaning that it runs independently in the background. Application Engine runs on any operating system that Oracle supports as an application server. If your site uses an operating system that is not supported for Application Engine, you must run Application Engine programs on the application server. The only exception is OS/390 (z/OS).
To run Application Engine programs on the batch server, you must install BEA Tuxedo. This condition applies to both UNIX and Microsoft Windows NT batch servers. If you run your batch server on the same server machine as your application server, then the application server and the batch server can share one BEA Tuxedo installation. If your batch server is separate from your application server, then you must install BEA Tuxedo on your batch server.
The TOOLBINSRV parameter in the PeopleSoft Process Scheduler configuration file determines where PeopleSoft Process Scheduler invokes an Application Engine program. For high-volume batch environments, specify the PS_HOME\bin\server\winx86 directory that exists on the same machine where the Application Engine program runs.
Application Engine programs that run online are typically run from a page with the CallAppEngine PeopleCode function. Such online processes are synchronous, meaning that subsequent processes wait for the results. For instance, a page may be frozen until the online process returns the necessary results. With the CallAppEngine function, no Commit statements are issued. However, if you use the asynchronous online PeopleCode option, ProcessRequest, Commit statements are allowed.
Usually, you use this mod only during testing or if you need to restart a program manually.
Select PeopleTools > Process Scheduler > Processes to access the Processes - Process Definition page.
To use PeopleSoft Process Scheduler for starting Application Engine batch programs, create a process definition for each program. Running Application Engine programs is similar to running any COBOL or Structured Query Report (SQR) program that you typically invoke with PeopleSoft Process Scheduler. Use Application Engine as the generic process type definition. Each Application Engine program that you invoke using PeopleSoft Process Scheduler requires a unique process definition derived from the generic process type definition.
Note: When creating a process definition based on the Application Engine process type definition, the process name you assign must match your Application Engine program name exactly.
Select PeopleTools > Process Scheduler > Processes > Process Definition Options to access the Processes - Process Definition Options page.
Use this page to list parameters. The complete parameter list is:
You also can start an Application Engine program by using the Application Engine Process Request page. Using this request page enables you to specify values and parameters in addition to those that appear within PeopleSoft Process Scheduler process definitions.
Most users start Application Engine programs from an application-specific request page using PeopleSoft Process Scheduler. A systems expert or power user may, at times, need to create custom process requests that require multiple programs to perform parallel processing or that need to set specific, initial values in a state record. You might use the Application Engine process request page for one of these cases.
Note: Generally, if seed data or other Application Engine request settings are required for a particular program, the application-specific request page has SQL executables that do the work that is transparent to the user. Typically, no user should invoke programs from the generic process request page. Use this page for internal testing and as a basis for designing program-specific request pages.
The Application Engine process request page inserts values into the following tables:
Note: Inserting a row in either of the Application Engine request tables is not required to run an Application Engine program. This change is a key difference between Application Engine versions prior to PeopleTools 8, where a row in Application Engine request tables is required to start a program, regardless of how it is invoked. The run control ID is available to your program using %RunControl, whether or not a row is inserted into the AEREQUESTTBL table.
You need to use the Application Engine Request page to invoke Application Engine and insert a row into the Application Engine request records only if you need to perform any of the following tasks:
Note: Entries in the AEREQUESTTBL table do not have any effect on Application Engine programs called from PeopleCode using the CallAppEngine function.
Select PeopleTools > Application Engine > Request AE to access the Application Engine Request page.
Field or Control
Displays where the program was invoked, from PeopleSoft Process Scheduler, from the command line, and so on.
Displays the process instance assigned to the previous program run.
Displays the status of the last program run, whether it is successful, pending, and so on.
Specify how long a particular process request will remain active or valid:
If you are requesting retroactive processing, specify the appropriate as of date.
Enter the appropriate field or bind variable for which you are inserting a value.
Enter the initial value that you want to set for the specified field.
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 CallAppEngine. 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.
