Running Application Engine Programs
This section provides an overview of program run options and discusses how to:
Create process definitions.
List process definition parameters.
Start programs with the Application Engine Process Request page.
Use PeopleCode to invoke Application Engine programs.
Use the command line to invoke 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:
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.
Batch Programs Using PeopleSoft Process Scheduler
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.
Online Programs Using PeopleCode
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.
Manual Programs Using the Command Line
Usually, you use this mod only during testing or if you need to restart a program manually.
Selectto 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.
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.
Selectto 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:
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.
Tables Used in the Process Request Page
The Application Engine process request page inserts values into the following tables:
Contains all of the values that appear on the page except those in the Parameters group box.
Includes only initial state record values specified in the Parameters group box, if needed.
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:
Insert initial values into the state records associated with a particular program.
Set an as-of date for the Application Engine program to perform retroactive processing.
Set a non-default market for the program.
Set up a temporary table image to use if you are submitting a PeopleSoft EPM process request that performs parallel processing. Refer to PeopleSoft EPM application documentation for details.
Note: Entries in the AEREQUESTTBL table do not have any effect on Application Engine programs called from PeopleCode using the CallAppEngine function.
Application Engine Requests
Selectto 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
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:
|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.
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.
You might invoke an Application Engine program through the command line to:
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.
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:
Note: For Microsoft Windows NT and UNIX servers, you must set the PS_SERVER_CFG environment variable before you invoke an Application Engine program from the command line. PS_SERVER_CFG must contain the fully qualified name of a correctly configured Process Scheduler PSPRCS.CFG file. When Application Engine runs from the command line, it resolves %PS_SERVDIR% to the value of the environment variable PS_SERVDIR instead of the parent directory of a Process Scheduler configuration.
Command Line Options
Field or Control
Specify the type of database to which you are connecting. Values are ORACLE,MICROSFT,DB2UNIX, and DB2ODBC.
For platforms that require a server name as part of their signon, enter the appropriate server name. This option affects Microsoft SQL Server. However, for Microsoft SQL Server, this option is valid but not required.
Enter the name of the database to which the program will connect.
Enter the user ID of the person who is running the program.
Enter the password associated with the specified user ID.
Note: Password may also be passed in encrypted form.
Enter the run control ID to use for this run of the program.
Specify the Application Engine program to run.
Required for restart, enter the process instance for the program run. The default is 0, which means Application Engine uses the next available process instance.
This parameter controls the Debug utility. Enter Y to indicate that you want the program to run in debugging mode or enterN to indicate that you do not.
This parameter controls restart disabling. Enter Y to disable restart or enterN to enable restart.
To enable tracing from the command line, enter this parameter and a specific trace value. The value you enter is the sum of the specific traces that you want to enable. Traces and values are:
1: Initiates the Application Engine step trace.
2: Initiates the Application Engine SQL trace.
128:: Initiates the Application Engine timings file trace, which is similar to the COBOL timings trace.
256: Includes the PeopleCode detail timings in the 128 trace.
1024: Initiates the Application Engine timings table trace, which stores the results in database tables.
2048: Initiates the database optimizer explain, writing the results to the trace file. This option is supported only on Oracle and Microsoft SQL Server.
4096: Initiates the database optimizer explain, storing the results in the Explain Plan table of the current database. This option is supported only on Oracle, DB2, and Microsoft SQL Server.
For example, to enable the 1, 2, and 128 traces, you would enter 131,the sum of 1, 2, and 128. To indicate that you do not want any traces, enter0. If you do not explicitly enter0, Application Engine uses the trace value set in PeopleSoft Configuration Manager.
8192: Sets a trace for PeopleSoft Integration Broker transform programs.
16384: Initiates the statement timings trace but stores the results in the PS_AE_TIMINGS_LG and PS_AE_TIMINGS_DT tables.
To disable %UpdateStats meta-SQL construct, enter 1.
Enable a SQL trace.
Enable a PeopleCode trace.
(Optional) Initialize the PeopleCode meta-variable %OutDestType (numeric).
PeopleCode example of %OutDestType:
&ProcessRqst.OutDestType = %OutDestType ;
(Optional) Initialize the PeopleCode meta-variable %OutDestFormat (numeric).
PeopleCode example of %OutDestFormat:
Query.RunToFile(Record QryPromptRecord, %OutDestFormat);
(Optional) Initialize the PeopleCode meta-variable %FilePath (string).
PeopleCode example of %FilePath:
If All(%FilePath) Then &FILENAME = %FilePath | &FILENAME; &MYFILE = GetFile(&FILENAME, "E", %FilePath_Absolute); Else &MYFILE = GetFile(&FILENAME, "E", %FilePath_Relative); End-If;
If you submit a file to Application Engine as the first parameter in the command line, Application Engine reads the contents of the file and interprets the contents as if it were parameters entered on the command line. This option is intended mainly for the Microsoft Windows NT or UNIX Process Scheduler server environment. For example, you might enter psae $temp/myparmfile.txt.
Note: For security reasons, after Application Engine interprets the contents of the parameter file, it immediately deletes the file.
(Optional) Set Y/N values for this parameter. If it is set to “Y” then it will not commit any changes to database.
Note: You can only use this parameter in a developer environment. Do not use it in a product environment.