Restarting Application Engine Programs

A key feature of Application Engine is its built-in checkpoint and restart capabilities. If a program step terminates abnormally or fails, you can restart the request from the last successful checkpoint or from 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:

  • Determine when to use restart.

  • Control abnormal terminations.

  • Restart Application Engine programs.

  • Start Application Engine programs from the beginning.

  • Enable and disable restart.

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

At the section level, you can set a commit after each step in a 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, such as a Do Select of Do While, within a step.

The commit level that you select affects how restart works in a program. Each time 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 effect on other users and processes while the background program is running because it reduces the number of rows that are locked by the program. Fewer rows allows 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 as follows:

  • Ignore the steps that have already completed up to the last successful commit.

  • Begin processing at the next step after the last successful commit.

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.

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 initially, such as joining tables and loading data into temporary work tables. Also, you should consider restart capabilities for programs that might put data in an unstable state if they terminate abnormally during a run. As a general rule, restart is essential for programs that primarily do set-based processing.

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

  • It is mainly row-by-row processing.

  • The overhead involved with Application Engine performing a checkpoint during the program run is not desirable.

  • The program commits after N iterations of a looping construct within a step, and the Select statement driving the loop is composed in such a way that if the program terminated and then started again it would ignore transactions that were already processed in the previous program run. In a sense, the program processes the restart internally: Application Engine treats each start of a program as a fresh start, instead of restarting a previous instance.

When developing for restart, consider the consequences if a program fails and you cannot restart the program. Given the commit structure that you 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 updates all state records. 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 system deletes the state record row upon successful completion of the application.

However, if the state record the program uses is a work record, you cannot make any database updates 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 re-initializes any state records that are work records at each commit in order 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 the 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 only prepares 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, then 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 remainsY 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 will not reset the AE_CRITICAL_PHASE value toN.

If your program terminates, the user can check the AE_CRITICAL_PHASE value. If it is Y,then 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 isN, restarting may not be necessary; however, as a general rule you should restart even if AE_CRITICAL_PHASE is set toN.

Using Restart at the Step Level

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

For example:

SELECT RECNAME, FIELDNAME
   FROM PS_AE_RECFIELD
   ORDER BY RECNAME, FIELDNAME

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 specifiedReselect, the program could execute in an infinite loop because no code exists to reduce the answer set. However, if you modified the Select statement as follows, you could make itRestartable:

SELECT RECNAME, FIELDNAME
FROM PS_AE_RECFIELD
WHERE RECNAME > %Bind(RECNAME)
OR (RECNAME = %Bind(RECNAME) AND FIELDNAME > %Bind(FIELDNAME))
ORDER BY RECNAME, FIELDNAME

You can convert a Do Select action that was coded for Restartable toSelect/Fetch, but the opposite is not true.

The previous example shows the use of a key column to reduce the answer set. A key column 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 might look like this:

SELECT COLUMN1, COLUMN2, . . .
   FROM PS_TABLE1
   WHERE PROCESSING_SWITCH=’N’. . .

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

  • SQL errors while On Error is set to Abort.

  • A PeopleCode return value when On Return is set to Abort.

  • A SQL statement that affects no rows when On No Rows is set to Abort.

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

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

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

  • From the command line.

  • From a process request page.

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 modify all 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 can 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 process instance. You can find these variables in 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 from outside of PeopleSoft Process Scheduler, then you cannot view details associated with the program run in the Process Details dialog box.

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

    PSAE.EXE −CT DB_TYPE -CD DB_NAME -CO OPRID -CP PASSWORD -R RUN_CONTROL -AI PROGRAM_NAME -I PROCESS_INSTANCE

    Note: Some database platforms also require that you include a server name in the argument list.

Restarting from a Process Request Page

The only programs you can restart from a process request page are those that run on the server.

To restart an Application Engine program from a process request 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 Errors

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

When an Application Engine program ends abnormally, you may have to decide whether you should restart the process or 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 the stage of the program 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, then you receive a suspend error. Because the process instance for these two processes is different, the new request fails. This event 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:

    DELETE FROM PS_AERUNCONTROL
    WHERE OPRID=OPRID
    AND RUN_CNTL_ID=Run_Control_ID
  2. Delete from your state record the row that corresponds to the failed program run.

    Use the following SQL to accomplish this step:

    DELETE FROM PS_MY_AET
    WHERE PROCESS_INSTANCE=Process_Instance

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

To disable restart, use any of these methods:

  • Select the Disable Restart check box in the Application Engine Program Properties dialog box.

    To access program properties, select File, Definition properties and select the Advanced tab.

  • Select the Disable Restart check box in the Configuration Manager profile.

    To access the profile, start Configuration Manager, select the Profile tab, and click Edit. Then select the Process Scheduler tab.

  • Include the -DR Y option in the command line of PSAE.EXE.

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

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