Running Application Engine Programs

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:

Select PeopleTools > Process Scheduler > Processes to access the Processes - Process Definition page.

Image: Processes - Process Definition page

This example illustrates the fields and controls on 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.

Select PeopleTools > Process Scheduler > Processes > Process Definition Options to access the Processes - Process Definition Options page.

Image: Processes - Process Definition Options page

This screenshot shows the Processes - Process Definition Options page.

Use this page to list parameters. The complete parameter list is:

• -ct %%DBTYPE%%

• -cd %%DBNAME%%

• -co %%OPRID%%

• -cp %%OPRPSWD%%

• -r %%RUNCNTLID%%

• -i %%INSTANCE%%

• -ai %%PRCSNAME%

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.

Application Engine Requests

Select PeopleTools > Application Engine > Request AE to access the Application Engine Request page.

Image: Application Engine Request page

This example illustrates the fields and controls on the Application Engine Request page. You can find definitions for the fields and controls later on this page.

Field or Control	Definition
Process Origin	Displays where the program was invoked, from PeopleSoft Process Scheduler, from the command line, and so on.
Process Instance	Displays the process instance assigned to the previous program run.
Status	Displays the status of the last program run, whether it is successful, pending, and so on.
Process Frequency	Specify how long a particular process request will remain active or valid: Always: Select to run the process request as needed. Once: Select if a process request is a one-time-only request. Don’t: Select to disable a process request so that no one invokes it and potentially corrupts data.
As Of Date	If you are requesting retroactive processing, specify the appropriate as of date.
Bind Variable Name	Enter the appropriate field or bind variable for which you are inserting a value.
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]

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.

You might invoke an Application Engine program through the command line to:

• Restart

  When a program abends, a system administrator might restart the program using the command line. If needed, you can locate all of the specific program and process information from Process Monitor in the Process Request Detail dialog box. Normally, users or system administrators perform a restart from the Process Monitor.

• Develop or test

  Many developers include the command line in a batch file to launch a program they are developing or testing. This way, they can quickly execute the batch file as needed. This method also enables separation of development of the application program from its associated pages.

• Debug

  To debug a program running on the server, you can sign into the server (using telnet, for example) and invoke the program from the command line.

To start an Application Engine program from the command line, you must specify the Application Engine executable (PSAE.EXE) followed by the required parameters, as shown in this example:

psae -CT dbtype -CS server -CD database_name -CO oprid -CP oprpswd?
 -R run_control_id -AI program_id -I process_instance -DEBUG (Y|N)?
 -DR (Y|N) -TRACE tracevalue -DBFLAGSflagsvalue -TOOLSTRACESQLvalue?
 -TOOLSTRACEPC value -OT outtype -OF outformat -FP filepath

Or, if your command line options are stored in a text file, you can enter:

psaeoptfilename

&ProcessRqst.OutDestType = %OutDestType ;

Query.RunToFile(Record QryPromptRecord, %OutDestFormat);

If All(%FilePath) Then
   &FILENAME = %FilePath | &FILENAME;
&MYFILE = GetFile(&FILENAME, "E", %FilePath_Absolute);
Else
  &MYFILE = GetFile(&FILENAME, "E", %FilePath_Relative);
End-If;