Running Application Engine Programmes

1. Thru Peoplecode on one of the events
1. Synchronously using CallAppEngine.
Commits in the AE program are ignored.


2. Async/thru process scheduler : Using CreateProcessRequest.

Since the AE runs in its own session, commits in the AE are fired.

2. Thru Process Scheduler:
1. Submitting a request using a specials page created for the purpose.
2. Using the AE request Page. ( Used only for testing. ) However, you can indicate the MARKET. Helpful if you have a single application engine with sections catering to different markets.

3. In 2 Tier thru Application Designer. ( Cannot set values for staterecords. )

4. Command line:
1. When developing and testing.
2. For restarting.
3. Debugging

How can values be passed between a Page and a AE called thru Application engine

While a state record can be initialized with values before calling the application engine program, the parameters passed by value and not reference.

This means that values of the state record set in the AE will not be available to the calling peoplecode on the page..
Use global variables instead.

Restartable Application engine and Global Variables in Peopleocode

In addition to state record, variables defined in Peoplecode as Global variables are also saved in the database.

Application Engine Commits

At my work, I realized that while application engines were being created, people did not know exactly how commits work in application engine.

I therefore set out to undertand application engine commits better. Here is what I have figured out so far:


If you create a new App. Engine program and do nothing for handling commits, the ae is automatically configured to commit after the application engine completes. This means that if the program aborts, everything is rolled back. It also means that there is additional burden on the database to keep track of uncommitted data.

However, there are settings at the section and step level that can be used to commit at specific points in time in the program.

An understanding of the commits is helpful.


1. At Section Level :
1. Turn on commit after step to get AE to commit after every step in that section.
2. Commit even n rows: Foe sections that contain do while, do until and do select, set the
commit frequency to commit after every n rows. The commit fired here is in addition to
commits fired in the loop.

Restriction: For Action of Do Select of type select/fetch where the restart is enabled, the
commits within the loop is ignored.

2. At Step
1. Default: based on the setting at the section.
2. After Step : To override the setting at section and commit after the step completes.
3. Later: To override the setting at section and not commit after step. ( when at section, you
have defined for commit after step. )

How do you get an AE program to abort?

In certain situation, you want to stop processing and fail the program ?

There are certain places where you can accomplish this:

1. SQL Action with On Error set to Abort.
Other values are
Continue: Continue processing. It will continue processing the next action within the step.

Skip step: Skip this step and go to the next.
Section break: Stop processing the current section and pass control back to calling section.


2. Peoplecode Action with OnReturn set to abort and exit(1) fired within the peoplecode on encuntering the error condition.
3. SQL Action which returns no rows can be flagged to Abort.


Other possible value for Peoplecode On Return are Skip Step, Break.
With break, subsequent steps in section are not processed and control is returned to calling section.
With skip step, the existing step and ( subsequent actions ) are skipped and control is passed on to the subsequent step.

AE State Record

A state record used to store values to e shared across sections/steps can be a
1. Record ( with an underlying database table)
2. derived work record

If you do decide to use a derived work record always disable restart. If not so disabled, after every commit the derived work record will be reinitialized resulting in unexpected behaviour.

An AE program can have multiple state records. In this case only one can be defined as a default state record. The fields of the default state record can be accessed w/o prefixing the record name. For non default state records, you have to prefix the record name.


To set a value of a state record's field use %SELECT ( FIELD name or RECORD.FIELDNAME)
To retrieve values, use %BIND(fieldname/ recordname.FIELDNAME )

AE Tables

This is an attemp to track all the tables used in Application engine programs


1. PS_MESAGE_LOG: ( Messages logs are inserted into this table)
2. PS_MESAGE_LOGPARM: ( Messages logs are inserted into this table)
3. PS_AERUNCONTROL: This table stores the point upto which a restartable AE program has completed.

If there is a dedicated temporary table that has been locked, you can unlock it by going to PeopleTools, Application Engine, Manage Abends and clear the locks.

Application Engine Commit/Controlling flow of program.

One common issue faces by developers as they create an application engine program is committing of data.

Unlike Sqr, where you can fire the commit yourself, it is also possible to define commit strategy in an App engine program and let that do the work for you. In fact, in app engine, to take benefit of restartability, that is what you should do.


CONTROLLIING COMMITS
=====================

First of by default, ( if you do not explicity change the settings and simply create your section, steps and actions ), the default behaviour is to commit at the completion of the AE program.

While this may seem to be the best alternative. Consider a very long running program which runs for 5 hours. If the program aborts everything is rolled back and you have to run again after rectifying your problem.

In this respect, it makes sense to understand how you can control commits in an AE progam.


Here are the different places where you can configure commit:

At Section: You can specify that the commit will happen after every step.

This will control the behaviour of commits after each step in that section is executed.
However, since each step can have its own unique requirement, you can overide this behaviour at a specific step.



At Step:

Various options include:
1. After Step: ( After the step completes. )
2. Later: Do not commit now. If you have flagged the Section to commit after step, use this to override and not commit after this specific step.
3. Default: use the value supplied at the section level. ( If at section not checked. Commit will occur for the AE at the end of the progam. If checked, commit will be after the step completes.
You can set the frquency option which is handy if you had do select, do while or do until action.


Exceptions
=======
When the program is restartable ( AE program is flagged as restartable ), the commits defined within a DO Select of type Select/Fetch are ignored.

For e.g. if there is an action wich calls a section with commit after step defined, the commit is ignored.




CONTROLLING FLOW ( when errors are encountered )


1. Step's On error property:

Depending on whether the above property is set to Abort, Ignore or suppress, the AE program will behave:
If Abort is selected, AE program will terminate. It will also rollback uncommitted changes.
If Ignore: Error will be logged but program will continue. No rollback issued.
If suppress: AE will not log and will continue. No rollback issued.

There is no property at the Section level that can control program flow when errror are encountered.

2. SQL Action:

You can control behaviour when No Rows are affected:
1. Set to Abort to rollback and terminate the AE progam.
2. Section Break: Break execution of the existing section.l Any subsequent steps in the section that sql action is part of are not executed. Returns control to the calling section.
3. Continue: Continue processing.
4. Skip Step: Seusequent actions in th step are skipped and control goes back to the next step.


Finally, if the application engine program is called synchronously on an event during component rocessing, all commits are ignored and the commit occurs after save psot change as part of the component commit.

%SelectInit

The Meta SQL %SelectInit ia used in App engine programs to assign values to the state record. But there is a slight difference when rows are not retrieved by the select statement.

While %Select will retain the existin value is no rows are returned, %SelectInit intialized those state record fields to defaults if the select statement does not return any rows.