Managing Application Engine Programs

This chapter discusses how to:

Click to jump to parent topicRunning Application Engine Programs

This section provides an overview of program execution options and discusses how to:

Click to jump to top of pageClick to jump to parent topicUnderstanding Program Execution Options

You execute Application Engine programs in one of the following modes: batch using PeopleSoft Process Scheduler, online using a PeopleCode function, and manually using the command line. The following table lists some differences between online and batch programs:

Online Execution

Batch Execution

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

Can be designed for parallel execution for performance.

Uses the online temporary table pool.

Uses the batch/dedicated temporary table pool.

Batch Programs Using PeopleSoft Process Scheduler

This is the most typical mode of execution. 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 asynchronous execution, meaning that it runs independently in the background. Application Engine runs on any operating system that PeopleSoft 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 applies to both UNIX and to 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 execute online are typically executed from a page with the CallAppEngine PeopleCode function. Such online processes are synchronous, meaning that subsequent processes wait on the results. For instance, a page may be frozen until the online process returns the necessary results. With the CallAppEngine function, there are no Commit statements 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 technique only during testing or if you need to manually restart a program.

Click to jump to top of pageClick to jump to parent topicCreating Process Definitions

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 very 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 exactly match your Application Engine program name.

Click to jump to top of pageClick to jump to parent topicListing Process Definition Parameters

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:

Click to jump to top of pageClick to jump to parent topicStarting Programs with the Application Engine Process Request Page

You can also start an Application Engine program by using the Application Engine Process Request page. Using this request page enables you to specify additional values and parameters than 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. This is an example of where you might use the Application Engine process request page.

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

Note. Inserting a row in either of the Application Engine request tables is not required to run an Application Engine program. This is a key difference from versions of Application Engine 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.

Application Engine Requests

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

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.


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.


Enter the initial value that you want to set for the specified field.

Click to jump to top of pageClick to jump to parent topicUsing PeopleCode to Invoke Application Engine Programs

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

CallAppEngine(applid [, ​statereclist ]);

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 don’t 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, a user must wait for any process invoked by CallAppEngine to complete before doing anything else. 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’ve 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 just 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.

Do not use CallAppEngine within an Application Engine PeopleCode step. If you need to call an Application Engine program from another Application Engine program, you must 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.

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 for execution.

Click to jump to top of pageClick to jump to parent topicUsing the Command Line to Invoke Application Engine Programs

You might invoke an Application Engine program through the command line in the following situations:

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 the following 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 -DBFLAGS ​flagsvalue -TOOLSTRACESQL ​value? -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


Specify the type of database to which you are connecting. Values are ORACLE, MICROSFT, SYBASE, INFORMIX, DB2UNIX, and DB2ODBC.


Required for Sybase and Informix. For platforms that require a server name as part of sign-on, enter the appropriate server name. This affects Sybase, Informix, and 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.


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 enter N to indicate that you do not.


This parameter controls restart disabling. Enter Y to disable restart, or enter N 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, Informix, 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, enter 0. If you do not explicitly enter 0, 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 following tables: PS_AE_TIMINGS_LG and PS_AE_TIMINGS_DT.


To disable %UpdateStats meta-SQL construct, enter 1.


Enable the SQL trace.


Enable the 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.

Click to jump to parent topicDebugging Application Engine Programs

This section discusses how to:

Click to jump to top of pageClick to jump to parent topicEnabling the Application Engine Debugger

To run a program in debug mode:

  1. Set the debug option.

    You can set the debug option in the following locations:

  2. Execute the Application Engine program to debug.

  3. At the Application Engine Debugger prompt, enter a command to enables a debugging option.

    Each command is represented by a single letter, such as X, L, or M. Enter the letter that corresponds to the option you want to engage. To see a list of the available debugging options, enter ? at the prompt.

To enable the PeopleCode debugger for Application Engine:

  1. Sign on to PeopleTools using the same user ID that you are going to use to invoke the Application Engine program.

  2. Open Application Designer.

  3. Select Debug, PeopleCode Debugger Mode.

    Your Application Engine program can be open on the desktop, but you do not need to open the Application Engine program or the PeopleCode action that you want to debug.

  4. Select Debug, Break at Start.

    This causes the Application Engine program to break prior to executing any PeopleCode programs within it.

Click to jump to top of pageClick to jump to parent topicSetting Debugging Options

Each debugger option is represented by a single letter that you specify at the prompt. To engage the option you select, press Enter.

Debugging Tips

Note the following tips about debugging programs:

Debugging Options




Enter Q. This option performs a rollback on the current unit of work in the debugging run, and it ends the debugging session. It effectively terminates your Application Engine program.

Quit is useful for testing restart. Have some work committed and some uncommitted. Then, terminate the program at that point and roll back the pending work. You want to make sure the program restarts from the point of the last successful commit.


This option is valid only after one step has completed and another has not already begun. It is not valid once you reach the action level.

Use this option as an alternative to Quit. Exit ends the program run and the debugging session, but it also commits the current unit of that the program has already completed. This option can be helpful when testing your restart logic.


Enter C. To commit the current unit of work in your program, use this option. It is valid only after a step has completed and before another has already begun. It is not valid once you reach the action level.

You can use this option, for example, to use your database query tool to check the data in your database.


Enter B. Sets a breakpoint. When the program reaches the breakpoint, it temporarily halts execution to enable you to observe the state of the current process.

Breakpoint options include:

Set: Enter S to set a breakpoint location.

The breakpoint location defaults to the current location in the program, but you can specify other sections or steps by overriding the default values that appear in the brackets.

Unset: Enter U to remove breakpoints previously set.

List: Enter L to list breakpoints. When you enter this command, make sure that you have entered B first to specify the break option. If you just enter L from the main command prompt, you engage the Look option.


Enter L. Enables you to observe the values currently in the state record associated with the program you are debugging. You must specify the state record at the Record Name prompt. By default, the default state record as specified in your program properties appears with the brackets.

You can also specify a specific field name on the state record in the Field Name prompt. To look at all the fields in the state record, leave the asterisk (*) within the brackets unchanged.


Enter M. Enables you to modify the value of a state record value for debugging purposes. Suppose the previous steps did not set a value correctly. However, you may want to see how the rest of the program would perform if the appropriate value existed in the state record. This enables you to give your program some help in the debugging or testing phase.

As with the Look command, you must specify the appropriate state record (if you are using multiple state records), and you must specify one field. You can modify only one field at time.


Enter W. When you specify a field as a watch field, the program stops when the value of the field changes.

Similar to the Break command, you can specify options for Set, Unset, and List.

Step Over

Enter S. Executes the current step to completion and stop at the next step in the current section.

The behavior depends on the current level or the program. You start at the step level, and then can step into the action level. If you are at the step level and use step over, you go to the next step in the current section, skipping over all actions (including any call sections). If you are at the action level, step over executes the current action and stops at the next action in the current step, or at the next step in the current section.

Step Into

Enter I. Use this option to observe a step or called section in a more granular level. For instance, you can check each SQL statement and stop. By using this option and checking the state record at each stop, you can easily isolate problem SQL or PeopleCode.

As with Step Over, the behavior depends on the level. At the step level, you can step into the action level and stop before the first action in the step. At the action level, if the current action is a call section, Step Into takes you to the first step in the called section. For other action types, Step Into acts the same as Step Over, because there is no deeper level in which to step.

Step Out of

Enter O. After you’ve stepped into a step or called section, use the Step Out of option to run the rest of the current step or called section and stop. As with the previous step options, the behavior of Step Out of depends on the current level of the program.

At the step level, Step Out of completes the remaining steps in the current section, returns to the calling section or step, and stops at the next action in that step. If the section is MAIN and is not called by another section or step, then Step Out of behaves the same as the Go option.

At the action level, Step Out of completes the current step and stops at the next step in the current section, or if the program is at the end of a section, Step Out of returns to the calling section or step.


Enter G. After the program has stopped at a specific location, and you’ve examined its current state, you can use the Go command to resume the execution of the program. This is a helpful command when you have breakpoints set. With this command, the program won’t stop at a step or action; it only stops at the next breakpoint or watch field, or when the program runs to completion.

Run to commit

Enter R. Resumes execution of your program after it has stopped. This command forces the program to stop again after the next commit. This is a good option to use when observing your commit strategy and how it will affect a restart.

Example of the Look Option

To view the value stored in a specific field of the state record after a step or action, enter the appropriate field name at the Field Name prompt. For example, if you entered AE_TESTAPPL_AET at the Record Name prompt and AE_INT_6 at the Field Name prompt, you would see the value of the AE_INT_6 field in the AE_TESTAPPL_AET record.

You can also use an asterisk (*) as a wildcard to get a partial list. For example, if you enter AE_INT* at the Field Name prompt, you see only the fields that start with AE_INT. This is also true for the Record Name prompt. This is useful both to list multiple fields across multiple records or as a shortcut. If you know there is only one state record that starts with XXX, you don’t have to type the full name—just enter XXX.

Example of the Modify Option

If you wanted to set the AE_INT_15 field in the AETESTPROG to 10, you would enter the record (AE_TESTAPPL_AET) at the Record Name prompt and the field (AE_INT_15) at the Field Name prompt.

You then see the current value of the field. At the prompt, you can enter a new value.

Using the Look command, you can check to see that the value you specified now exists in the state record.

Example of the Watch Option

Enter S to set a watch field. After you enter S, you enter the record name (such as AE_TESTAPPL_AET) and field name (such as AE_INT_7) at the appropriate prompts.

Enter U to unset, or remove, a watch field from the list. After you enter U, you see a list of active watch fields. You enter the watch field ID number to remove a field. For example, if the field AE_INT_7 were second in the watch field list, you would enter 2 to remove it.

After the completion of a step or action, enter L to list, or view, the values of all the fields that you have included in the watch list.

Note. You cannot set a watch on a long text field.

Click to jump to parent topicRestarting Application Engine Programs

One key feature of Application Engine is its built-in checkpoint and restart capabilities. If there is an abnormal termination or failure on a step in the program, you can restart the request from the last successful checkpoint, or the step immediately preceding the step that failed. You restart the program from the process request page.

This section provides an overview of restart and discusses how to:

Click to jump to top of pageClick to jump to parent topicUnderstanding Restart

Application Engine programs save to the database (perform a commit) only when an entire program successfully completes. You must set any individual commits where appropriate.

At the section level, you can set a commit after each step in that section. At the step level, you can require or defer commits for individual steps, or you can increase the commit frequency within a step to N iterations of a looping action within a step, such as a Do Select or Do While action.

The commit level that you select plays a major role in how restart works in a program. Each time that Application Engine issues a commit with restart enabled, it records the current state of the program. The recording of the current state that Application Engine performs is referred to as a checkpoint.

Using the restart feature enables you to perform commits more often in a program. Restart reduces the overall impact on other users and processes while the background program is running, because it reduces the amount of rows that are locked by the program, allowing multiple instances of the program to run concurrently (parallel processing), which may be useful for high-volume solutions.

With restart, if a failure occurs at any point in the process, the user can restart the program and expect the program to behave in the following manner:

The ability for Application Engine to remember completed steps depends on a record called AERUNCONTROL, which is keyed by process instance.

When a program runs, each time Application Engine issues a commit it also saves all of the information required for a program restart in the AERUNCONTROL record.

Click to jump to top of pageClick to jump to parent topicDetermining When to Use Restart

Usually, you want to develop programs to take advantage of Application Engine restart capabilities. Programs that are good candidates for restart do a lot of preparation work up front, like joining tables and loading data into temporary work tables. Also, programs that might put data in an unstable state if they terminate abnormally during a run should be considered to take advantage of restart. As a general rule, restart is essential for programs that primarily do set-based processing.

However, if your program has one the following characteristics, you may want to disable restart:

When developing for restart, consider the consequences if a program fails and you can’t restart the program. Given the commit structure that you’ve defined for your Application Engine program, would your data remain in an usual state if a failure were to occur after any of the commits? Would it be easy to recover from such a case?

Using Restart at the Program Level

Application Engine automatically performs all state record updates. When an Application Engine program starts, it inserts a row in the state record for the assigned process instance. Then the system updates the state record whenever the program performs a commit to store changed values into the database. Finally, the state record row is deleted upon successful completion of the application.

However, if the state record the program uses is a work record, no database updates can be made to the record. Consequently, if you restart the program, you might get unexpected results, because the memory was lost when the program terminated. In fact, the system reinitializes any state records that are work records at each commit, to ensure consistent behavior during a normal run and a restarted run. Therefore, you may need to make at least one of your state records a SQL table to contain values that must be retained across commits or in case of termination.

Finally, the other consideration for programming for restart at the program level is to check both the Application Engine Program Properties dialog box and PeopleSoft Configuration Manager to make sure that Disable Restart check box is not selected.

Using Restart at the Section Level

The section level property associated with restart is section type, which has the options Prepare Only and Critical Updates.

If a section is only preparing data, as in selecting it, populating temporary tables, or updating temporary tables, then set the section type to Prepare Only. However, if the section updates permanent application tables in the database, set the option to Critical Updates.

During runtime, when the system arrives at the first section set to Critical Updates, it sets the AE_CRITICAL_PHASE value in the AERUNCONTROL record to Y. Once set, the value of AE_CRITICAL_PHASE remains Y until the program completes successfully. When the program completes, the corresponding row in AERUNCONTROL is deleted. Therefore, a Prepare Only section following the Critical Updates section won’t reset the AE_CRITICAL_PHASE value to N.

If your program terminates, the user can check the AE_CRITICAL_PHASE value. If it’s Y. the user knows that the section that failed is critical and that the program should be restarted to ensure data integrity. If AE_CRITICAL_PHASE is N, restarting may not be necessary; however, as a general rule, you should restart even if AE_CRITICAL_PHASE is set to N.

Using Restart at the Step Level

In your program’s Where clause of a Do Select action, you should include conditions that reduce the answer set returned from the Select statement.

For example,


If you ran this Select statement as part of a Do Select action with Restartable selected as the Do Select type, the system might process some of the rows twice after a restart. Also, if you have specified Reselect, the program could execute in an infinite loop, because there’s nothing to reduce the answer set. However, if you modified the Select statement to look more like the following, you could make it Restartable.


A Do Select action that has been coded for Restartable can be converted to Select/Fetch, but the opposite is not true.

The previous example shows the use of a key column to reduce the answer set. This can be convenient if your record has only one or two key fields. However, if your record has three or four keys, your SQL would become overly complex.

Instead of matching key fields, you could add a switch to the selected table, and then have the processing of the called section modify the switch as it processes the row. In this example, your Select statement could look like the following:


Click to jump to top of pageClick to jump to parent topicControlling Abnormal Terminations

A controlled abnormal termination (sometimes called an abend) means that Application Engine exits gracefully because of a calculated error condition. Some examples of controlled abends are:

In these situations (when Application Engine is in control) the Run Status field in Process Monitor reads Error.

An uncontrolled termination occurs when there is a memory violation or a user terminates a process. In these cases, the Run Status field in Process Monitor shows Processing.

Click to jump to top of pageClick to jump to parent topicRestarting Application Engine Programs

You can restart an Application Engine program in one of these ways:

Note. The following procedures for restarting a failed Application Engine program assume that you have rectified the error that caused the program to fail in the first place. For instance, suppose the name of a referenced table has changed. Regardless of how many times you restart the program, it will continue to fail until you’ve modified references to the old table name.

Restarting from the Command Line

Normally, only developers and system administrators use the command line for restarting Application Engine programs. Users, in most cases, should not be expected to use this method.

You can use the command line option to restart programs that run on the client or the server. Application Engine references only the process instance of the failed process. Therefore, if you run a process on the client and it fails, you can restart it from the server using the server command line. Likewise, if you run a process from the server and it fails, you could restart it from the client using the command line.

To restart an Application Engine program from the command line:

  1. Collect the command line values associated with the failed program.

    These values include database type, database name, user ID and password, run control ID, program name, and the process instance. You can find these variables on the Process Details dialog box, the corresponding state record, or the Application Engine Run Control table. Where the values reside depends on how you invoked the program. For instance, if you invoked the program using the command line, or outside of PeopleSoft Process Scheduler, then you cannot view details associated with the program run on the Process Details dialog box.

  2. Enter the following command line syntax at the command prompt substituting the values from the previous step:


    Note. Some database platforms, such as Sybase, also require that you include a server name in the argument list.

Restarting from the Process Request Page

You can restart programs from a process request page only for those programs that run on the server.

To restart an Application Engine program from a process requests page:

  1. Open PeopleSoft Process Scheduler by selecting PeopleTools, Process Scheduler, System Process Requests.

  2. Locate the run control ID number of the program to restart.

  3. To display the details of the failed process, click the Process Detail link.

  4. On the Process Request Details page, select Restart Request, and click OK.

Bad Restart Error

If you attempt to restart what Application Engine believes to be a process that completed successfully, you receive a bad restart message. You can also get this message if your Application Engine application is defined with restart disabled.

Click to jump to top of pageClick to jump to parent topicStarting Application Engine Programs from the Beginning

When an Application Engine program ends abnormally, you may have to decide whether you should restart the process or just start it from the beginning. As your Application Engine program ran at least part way through, starting over may leave your data in an unknown state. Also, application logic might need to be undone, depending on what stage the program was at when it failed, what data the program had committed, and so on.

However, if restart is enabled and you attempt to start a new process that matches the run control ID and user ID for another process, you receive a suspend error. Because the process instance for these two processes is different, the new request fails. This usually occurs when a user tries to run the program again after receiving an error on the previous attempt.

To start the program over from the beginning, you can use SQL to delete the row that corresponds to the failed program from the Application Engine run control table and your state record.

To restart an Application Engine program from the beginning:

  1. Open your native SQL editor and manually delete the row in PS_AERUNCONTROL that corresponds to the program you want to start from the beginning.

    Use the following SQL to accomplish this step:


  2. Delete from your state record the row that corresponds to the failed program run.

    Use the following SQL to accomplish this step:


Note. To restart the program, you can also select Restart Request from the Process Request Details dialog box.

Click to jump to top of pageClick to jump to parent topicEnabling and Disabling Restart

To disable restart, use any of these methods:

If you disabled restart in any of these three places, restart is disabled.

Therefore, if you want the program to restart in a production environment while still keeping a restart condition from getting in the way during development and testing, you can deselect the Disable Restart check box in the Application Engine program properties. Then, during development, you can select the Disable Restart check box in Configuration Manager or invoke your program from the command line with the -DR Y option, without having to reconfigure the program for testing.

Click to jump to parent topicCaching the Application Engine Server

Application Engine caches metadata, just like the application server. This caching enhances performance, because a program can refer to the local cache for any objects that it uses.

Cache Directory Location

Application Engine programs that run on a Microsoft Windows NT or UNIX server each lock their own cache directory for the duration of the run. These directories are found under the master cache directory. The master directory is created under the directory specified by the CacheBaseDir variable in the PeopleSoft Process Scheduler configuration file. If all existing cache directories are locked, a new one is created. Cache subdirectories are named sequentially, starting at 1.

If you do not enter a fully qualified path for the CacheBaseDir variable, then Application Engine creates the cache directory within the directory in which the program is set to run.

Note. Do not share the CacheBaseDir variable with application servers, and do not use environment variables when specifying CacheBaseDir, because the system does not resolve them. For example, do not set CacheBaseDir to $PS_CFG_HOME.

Cache Parameters

The PSPRCS.CFG (PS_SERVER_CFG) file has two additional cache parameters. They are:

Do not alter these settings from the delivered defaults. These settings are reserved for future use.

Click to jump to parent topicFreeing Locked Temporary Tables

If you use dedicated temporary tables for Application Engine programs, then you might need to free, or unlock, a temporary table if the program running against it terminates abnormally. Because most Application Engine programs run through PeopleSoft Process Scheduler, typically you use Process Monitor to unlock the temporary tables. Deleting or restarting a process using Process Monitor automatically frees the locked temporary tables.

For the programs that you invoke outside of PeopleSoft Process Scheduler, use the Manage Abends page. Programs running outside of Process Scheduler include those invoked from CallAppEngine PeopleCode and the command line.

To free locked temporary tables using the Manage Abends page:

  1. Select PeopleTools, Application Engine, Manage Abends.

  2. Identify the program that has the particular temporary tables locked.

    You can uniquely identify programs using the process instance, run control ID, program name, user ID, and run date and time columns.

  3. Click the Temp Tables link.

  4. On the Temporary Tables page, click the Release button to unlock the temporary tables associated with the program.