APPLICATION ENGINE

RESTART ABILITY

Agenda
What Is Restart Ability ?

The Concept of Restart Ability

4-6

Restart an AE When To ?

7 - 14

Abending AE Gracefully

15

Handling Abnormal AE Terminations

16 - 19

Restarting AE

20 - 23

I. Programming for Restart Ability

II. Sample Restart Enabled AE

24 - 26

Guidelines to Making an AE Restartable

27 - 28

Conclusion

29

What is Restart Ability ???

PeopleBook defines Restart Ability as follows:

One key feature of PeopleSoft 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.

The Concept of Restart Ability - Commit

By default Application Engine programs save to the database (perform a
commit) only when an entire program successfully completes.
We can over write this at two levels:
Section Level
Step Level
The commit level that you select plays a major role in how restart works in a
program

Note: Commit cannot occur at the Action Level

The Concept of Restart Ability

With restart, if a failure occurs at any point in the process, user can
restart the program and expect the program to behave in the following
manner:
Ignore the steps that have already completed up to the last
successful commit
Begin processing at the next step after the last successful commit
This requires the capturing of the point where the failure occurs.
The recording of the current state that PeopleSoft Application
Engine performs is referred to as a checkpoint. Each time that
PeopleSoft Application Engine issues a commit with restart
enabled, it is check pointed.
Note: The restart feature enables perform commits more often in a
program.
5

The Concept of Restart Ability - Advantage

1] 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)
E.g. Useful for high-volume solutions like Payroll Process

2] With restart, if a failure occurs at any point in the process, the user
can restart the program and expect the program to resume from the
same point.
E.g. An Example where this situation will help is a batch to Send Email
to Vendors

Restart an AE When To ?

Do not Restart when:

Row-by-row processing
The overhead involved with performing a checkpoint undesirable.
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 nutshell, think if at any stage your Application Engine commit
structure leaves the database inconsistent. If so then restart design is
skewed

Note: Restart is essential for programs that primarily do

set-based processing where a lot of preparatory work is
involved.
7

Restart an AE Program Level

First consideration for programming for restart at the program level is to

uncheck both the Disable Restart check box at
PeopleSoft Application Engine Program Properties
PeopleSoft Configuration Manager

Restart an AE Program Level : State Record

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. You might get unexpected
results, because the memory was lost when the program terminated or
committed.

Note: Need to make at least one of the state records a

SQL table to contain values that must be retained across
commits or in case of termination.
9

Restart an AE 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

10

If the section updates permanent

application tables in the
database, set the option to
Critical Updates

Restart an AE Section Level

During runtime, when the system arrives at the first section set to
Critical Updates, it sets the
AERUNCONTROL.AE_CRITICAL_PHASE = Y.
Once set, the value remains Y until the program completes
successfully. When the program completes, the corresponding
row is deleted.
If program terminates, the user can check this value.

The section that failed is critical and that the program should be restarted

Restarting may not be necessary

Note: As a general rule, you should restart even if

AE_CRITICAL_PHASE is set to N.
11

Restart an AE Step Level

Commit : Specify the commit level for the step

Default : Select to inherit whatever commit level you specified for the
parent section.
Later : Select to postpone the commit until a subsequent commit
occurs. Here you can override the section-level commit.
After Step : Select if you have a commit level of None specified at the
section level. This way you can override the section-level commit.

12

Restart an AE Step Level

Frequency : Enabled when a step contains Do While, Do Select, or Do

Until. Enter the numeric frequency with which PeopleSoft Application
Engine should commit. If non-zero, PeopleSoft Application Engine
commits every N iterations, and then again after the last iteration.
On Error : Specify how PeopleSoft Application Engine should respond to
an error at the step level. The program only terminates on errors, not
warnings.
Abort : The application terminates with an error message.
Ignore : The program continues but logs an error message.
Suppress : The program continues and presents no error message.

13

Restart an AE Step Level

No Rows : Available for SQL actions

Abort: The program terminates.
Section Break: PeopleSoft Application Engine exits the current section immediately,
and control returns to the calling step.
Continue: The program continues processing.
Skip Step: PeopleSoft Application Engine exits the current step immediately and
moves on to the next step.

Do Select Type: Specify this property in a Do Select action

Select/Fetch: Opens a cursor, then, within that cursor, PS AE performs a Fetch
statement for each iteration of the loop to get each row from the Select statement. No
Checkpoint hence not restart able.
Re-Select: For each iteration of the loop, PS AE opens a cursor and fetches 1st row.
Restartable: This option is similar to Select/Fetch but is restart able.
14

Abending AE Gracefully

Abend is defined as
A controlled abnormal termination, means that Application Engine exits
gracefully because of a calculated error condition.
SQL errors while you have set On Error to Abort.
A PeopleCode return value, when On Return is set to Abort.
A SQL statement that affects no rows, when you have set On No
Rows to Abort.

Note: In these situations the Run Status field in Process

Monitor reads Error.
15

Handling Abnormal AE Terminations

Freeing Locked Temporary Tables

This applies to Application Engine programs that use Temporary Tables

and terminates abnormally.
Case 1 : Process Run Via Process Scheduler
Deleting or restarting a process using Process Monitor automatically
frees the locked temporary tables.
Case 2 : Invoked outside of PeopleSoft Process Scheduler
Free locked temporary tables using the Manage Abends page.

16

Handling Abnormal AE Terminations

Steps to Manage Abends

Select PeopleTools > Application Engine > Manage Abends.

Identify the program that has the particular temporary tables
locked.
Click the View Locks link.
Click the Delete button to unlock the temporary tables associated
with the program.

17

Handling Abnormal AE Terminations

18

Handling Abnormal AE Terminations

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. 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
Application Engine run control table and your state record.
DELETE FROM PS_AERUNCONTROL
WHERE OPRID=OPRID
AND RUN_CNTL_ID=Run_Control_ID
DELETE FROM <State Record>
WHERE PROCESS_INSTANCE=Process_Instance

19

Restarting AE Enable or Disable

To disable restart, use any of these methods:

Select the Disable Restart check box on the PeopleSoft Application
Engine Program Properties dialog box (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.

Note: If youve disabled restart in any of these three

places, restart is disabled.
20

Restarting AE

There are two ways to restart an Application Engine program:

From the command line.
From a process request page.

Note: If you attempt to restart what PeopleSoft 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.

21

Restarting AE Command Line

1] Collect the command line values associated with the failed program.
database type
database name
user ID and password
run control ID
program name
process instance
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

22

Restarting AE Process Scheduler 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.

23

Programming for Restart Ability - Example

Program Purpose
For the given run control parameters (vendor range, payment date
etc.) we wish to send an email to every vendor that consists of his
payment details

24

Programming for Restart Ability AE Structure

Decide if
require restart
ability
Design for
restart ability
State Record is
SQL Record
Check if restart
enabled at all 2
levels
Set :
No Rows Abort
Frequency 25
Do Select Type Restart able
Commit After Step

25

Programming for Restart Ability Logic

Include a Flag field in the temporary table. Default it to N

At the Do Select looping action, check if the Flag = N only then
proceed
to the PeopleCode action
e.g. : %Select <State Record Field List>
Select <Select List>
From Temp_Table
Where Flag = N

Within the PeopleCode, immediately after the sendmail() happens

successfully (this can be checked via the sendmail() return code)
update the Flag = Y for the row
26

Guidelines to Making an AE Restartable

1] Make a judgment whether restart ability is actually required for your

Application Engine program. Consider the overheads on account of
the commits and the inconsistency if the program were to abort
abnormally
2] Design a commit structure for your Application Engine program
3] Design the Application Engine program in a manner that you do the
preparatory work like setting flags, selecting data, storing them into
temporary / staging tables upfront and then do the manipulations to
the base records
4] Ensure that restart is enabled at all three places mentioned
previously.
27

Guidelines to Making an AE Restartable

5] Set Section Type to Critical Updates at the first instance where a

section updates permanent application tables in the database.
6] Commit after step where required. Take special care to see how the
looping actions like Do Select, Do While and Do Until behave (step
level properties). Program for restart ability.
7] At least one state record, that holds the values passed across steps
and sections and are required after a program resumes is an SQL
table.
8] When running an Application Engine program that is restart enabled,
ensure that given the Run Control ID and Operator ID the entries do
not already exist
28