Application Engine

Application Engine

What is Application Engine?

Application Engine is a PeopleTool designed to help you develop background (batch) SQL processing programs. Application Engine offers an alternative to writing COBOL or SQR programs. It is not used for reporting.

In the realm of AppEngine, a program is a set of SQL statements, PeopleCode, and Program Control Actions (that allow looping and conditional logic) defined in AppDesigner that performs a business process. You can use AppEngine for straight, row-by-row processing, but the most efficient AppEngine programs are written to perform set-based processing.

AppEngine does not generate, parse, or understand SQL. It merely executes SQL that you provide. This can be SQL you write as part of an application or SQL that has been generated by tools such as Query.

Advantages: Graphical Developer Interface

Encapsulation AppEngine programs reside completely within the database No need to compile programs, no statements to store, no need to directly interact with

the operating environment used. Develop your entire program from scratch, including table definitions, all within

AppDesigner and then run and debug the application without exiting PeopleTools.

Data Dictionary Integration AppEngine works in harmony within the PeopleSoft system and references the data

dictionary for object definitions; changes to meta-data in the database have no impact on AppEngine programs.

Enhanced SQL/Meta-SQL Support RDBMS platforms have many differing syntax rules, especially in regard to date,

time, and other numeric calculations. For the most part, you can work around this problem using PeopleSoft meta-SQL, which AppEngine supports. This language is designed to replace RDBMS-specific SQL syntax with a standard syntax, called meta-strings.

PeopleSoft meta-SQL has been expanded with functions that let you dynamically generate portions of your SQL statements. This new meta-SQL is not supported in COBOL or SQR.

Application Engine July 2005 Page 1 of 25

Effective-Dating Application sections are effective-dated meaning you can activate/deactivate a section

of the program as of a particular date. This enables you to archive sections as you modify them, instead of destroying them.

Platform Flexibility AppEngine programs have the ability to call different versions of a Section for

different platforms as needed.

Reuse Business Logic Common PeopleCode functions can be called from within an AppEngine program.

Upgrade Support Upgrade AppEngine definitions by project, program, or section.

Build-In Restart Logic Define how frequently the program will issue a COMMIT. Each COMMIT becomes

a checkpoint that AppEngine uses to locate where within a program to restart after an abend.

This type of built-in logic does not exist with COBOL or SQR.


AppEngine Designer

Graphical User Interface Ability to open multiple AppEngine programs concurrently. Ability to work on the entire AppEngine program at once. Easy access to PeopleCode and SQL editors. Two views of your program

Definition view is where you create and modify your program Program Flow view shows a graphical representation of your program execution.

(Do NOT edit SQL in this view!)

Application Components

Program Section Steps ActionsApplication program

Callable block of logic

Logical groupings of actions

Line of Code

Composed of one or more Sections

Composed of one or more Steps

First Section is always MAIN

Can be specified by:- Market- Effective Date- Effective Status- Platform generic or specific

Composed of one or more actions

Smallest unit of work COMMITED

Can execute:- Do When- Do While- Do Select- PeopleCode- Call Section- SQL- Log Message- Do Until- XSLT

Starts with MAIN

12 character limit for application program name

Executed only when “called” (except MAIN Section)

Executed from top to bottom within the Section

Must be unique within Step

Executed in specific order


Program Properties (Advanced tab)

Item DescriptionDisable Restart Select this to disable the AppEngine built-in restart capabilities –

useful when testingApplication Library In some cases, you may want a program to contain only a

collection, or “library” or common routines (“callable” sections) that will not run as a standalone program. When Sections are defined as “Public”, other programs can call the Sections that exist in the “library” at runtime. Because this type of program is not designed to run as a standalone program, it does not require the MAIN Section.

Upgrade Only(rel 8.2)

This option is for programs intended to be used for upgrade purposes only. PeopleSoft delivers some Application Engine programs for upgrade-only uses. Unless you are responsible for the upgrade procedure at your site, you won't need to deal with these programs.

Batch Only (rel 8.4) Select this check box for batch only programs. Batch only programs are not executed from the CallAppEngine() PeopleCode function. Any dedicated temporary table used for Batch Only programs do not have online instances created.

Message Set Specify the message set value assigned as the default message set number for this AppEngine program. The system uses this message set value for all log messages where the message set isn’t specified.

Program Type(rel 8.4)

Select the appropriate program type from the list: Standard (which is a normal entry-point program), Upgrade Only (which is used in PeopleSoft Upgrade utilities), Import Only (which is used by PeopleSoft Import utilities like File Layout), Daemon Only (a special type of program used as a daemon) or Transform Only (another special program type used to support XSLT).


PSDaemon (rel 8.4) PSDAEMON is a process that runs continuously when the Process Scheduler is

running and is intended for recurrent jobs. It polls the system checking for certain conditions to be true for events and when true, it schedules a process to handle the event. The most common usage of the PSDAEMON is the check for files that have been loaded to the server and when found launch a process to import the file.

Once the daemon programs are created, they need to be defined in a Daemon Group. The Daemon Group is attached to a Process Scheduler Server and daemon is enabled.

Steps involved in setting up PSDAEMON Create AppEngine program with program type of Daemon Only (Program

properties) Add Daemon program to a Daemon Group (contains all the daemon programs for

one server) Associate Daemon Group with a Process Scheduler Server Monitor the Daemon program

Transform Only (rel 8.4) These types of programs enable different systems to communicate with one another

by transforming messages into appropriate formats. When you specify an Application Engine as a Transform Only program, you must specify an Action Type of XSLT.

You can use transform programs to do any of the following: Apply a transformation to a message to make its structure comply with the target

system’s requirements. Perform a data translation on a message so its data is represented according to the

target system’s conventions. Determine whether to pass a message through to its target, by filtering it based on

its content.


AppEngine Program Structures

Sections Steps ActionsOne One OneOne One MultipleOne Multiple One per Step to

Many per StepMultiple One per Section to

Many per SectionOne per Step toMany per Step

Inserting Sections and Steps

Sections

Control DescriptionSection Name Be as descriptive as possible – 8 character limitDescription Descriptive name for the Section – 30 character limitMarket The market for which the Section is intended. If a particular market

is irrelevant to your batch program, leave as GBLPlatform Used to specify Section is to be run on a particular platform. Enables

you to take advantage of any RDBMS-specific optimizations or to change section logic because of RDBMS limitations.

Effective Date Default is 01/01/1900. May be used to make a particular Section effective-dated

Effective Status Used to activate/inactivate a SectionSection Type In case of abend, the value of this system field specifies whether or

not the Section will need to be restarted. If a section controls a procedure that, if not run to completion, could corrupt or desynchronize your data, select Critical Updates. Otherwise, use the default value of Preparation Only.

Auto Commit Specify the COMMIT level for the section. Can opt to have not


COMMIT or have AppEngine COMMIT after each Step in the Section successfully completes (not efficient!)

Access This property controls the Call Section Action. Specify that a Section can or can’t be called from another program

Comments Use the comments section to document the Section

Steps

Control DescriptionStep Name Consecutively numbered based on the last step name – 8 char limitStep Description Descriptive name for the Step – 30 character limitCommit After Determines when COMMIT will be executed:

- Default: uses values supplied for the Section- Later: do not COMMIT now- After Step: COMMIT when step completesNote: “Later” and “After Step” override the Section “Auto Commit” setting

Frequency Only available in loopsOn Error Determines the action to take when an error occurs:

- Abort: program will write messages to message log and terminate

- Ignore: program will write messages to message log and continue

- Suppress: no message will be written, but program will continue

Active Determines if the Step is active (checked) or inactive (blank)Comments Add any additional comments to document the program

Action Execution Order1. Do When2. Do While3. Do Select4. PeopleCode5. SQL or Call Section6. Message Log7. Do Until8. XSLT (enabled for transformation programs in rel 8.4)

Notes: SQL and Call Section are mutually exclusiveXSLT not available in LS

Do When , Do While, Do Until (iterative) Action Properties ReUse Statement is an option that can be enabled to optimize the SQL components

of a batch program. Selecting this means the database engine only needs to compile the SQL once, which reduces SQL overhead. Choices are Yes, No, and Bulk Insert.


Do Select (iterative) Action Properties ReUse Statement: (See Do When, Do While, and Do Until above) Do Select Type: You need to specify one of the following: Select/Fetch, Reselect, or

Restartable.

PeopleCode Action Properties On Return: If your PeopleCode program provides a false result, you can have

Application Engine respond by doing one of the following: Abort, Break, or Skip Step.

SQL Action Properties ReUse Statement: (See Do When, Do While, and Do Until above) No Rows: If your SQL statement doesn't affect any rows, you can specify that

Application Engine respond in one of the following ways: Abort, Section Break, Continue, or Skip Step. Abort: the program terminates Section Break: AppEngine exits the current Section immediately and control

returns to the calling Step Continue: the program continues processing Skip Step: AppEngine exits the current Step immediately and moves on to the

next Step. When using Skip Step, keep the following in mind: AppEngine ignores the commit for the current Step at runtime If the current Step contains only one Action, only use Skip Step to bypass the

commit

Call Section Action Properties Section Name: If you are calling another Section, you need to specify the

appropriate Section here. Only the names of Public Sections defined in the program identified in Program ID will appear in the Section Name drop-down list.

Program ID: Since you can call Sections in the current program or Sections that exist within other programs, you need to specify the Program ID, or Program Name, of the program containing the Section you intend to call. The drop-down list contains all of the program definitions that currently exist.

Log Message Action Properties Message Set: Identifies a message set within the Message Catalog. Number: Identifies a particular message within a Message Set. Parameters: A list of comma-delimited values to substitute for %1, %2, and so on

markers in the message text.


Application Engine Execution Batch

Most typical mode of execution Invoke programs using Process Scheduler (requires a Process Definition) or the

AppEngine Process Request Page Asynchronous execution (runs independently in the background)

Online Typically executed from a page with the CallAppEngine PeopleCode function Synchronous execution (subsequent processes wait on the results) No COMMITs are issued until the program completes

Manual Executed via the Command Line Usually used only during testing or if you need to manually restart the program

Application Engine Process Definition Use Process Scheduler Manager to set and create Process Types, Process Definitions, and

Job Definitions to integrate Process Scheduler in PeopleSoft applications from your browser.

For each AppEngine program you want to process via the Process Scheduler, you will need to create a Process Definition and a Component designed to control runtime parameters (PeopleSoft provides standard records and pages from which to clone).

Process Definition For every AppEngine program, you will need to define a Process Definition which

serves four primary purposes: Identify the TYPE of Process to be run (via the Process Type) Identify the PROGRAM name you are running (Process Definition name must be

the same as the Program name) Identify WHERE the Program can be run from (via the Component) Identify WHO has the security access to run it (via the Process Group)

Testing and Debugging As with any program you develop, writing the code represents just half of your development effort. The other half consists of testing your program to make sure it successfully executes the logic you constructed on your whiteboard. With Application Engine you use the Application Engine Trace options and the Application Engine Debugger to monitor the execution of your programs.

Testing AppEngine Programs Execute directly from AppDesigner in 2-tier

Select Edit, Run Program or click on Run Program button (rel 8.4) This method is fast and simple, but does not allow any run control parameters at

execution time.


AppEngine programs executed in 2-tier are not displayed on the Process Monitor If program does not completed successfully and Disable Restart was not set on the

AppEngine program Advanced tab, you will have to restart the program through the Command Line (see next section)

Run Control ID Enter the run control ID of the program you are testing. If your program requires run control parameters, you will need to populate the fields on the run control and specify the run control when executing from AppDesigner.

Run Minimized Select this to have the window of the requested process minimized when it is submitted to run.

Output Log to File Select this is you want the output log to be written to a file.Log File Name Specify the log file name (enabled only when Output Log

to File is checked)Process Instance Defaults to 0 – Doesn’t do anything

Through the Process Scheduler (rel 8.4 Developer’s Shortcut - Generic Application Engine Test Type) Rel 8.4 system is delivered with a page designed for developers to test AppEngine

programs. The Request AE page allows you to enter parameters associated with the AppEngine program. This page should not be used in Production to execute AppEngine programs. Rel 8.1 navigation: PeopleTools, Application Engine, Process, Request Rel 8.4 navigation: PeopleTools, Application Engine, Request AE

Command Line

Process Monitor Has a message log that will tell you if the program executed successfully or not With a failure, you will need to invoke other tools

Application Engine Trace File


Generates a trace at your request Can specify Steps to see a sequence of messages tracking the Step execution of your

AppEngine program Can also trace more detailed execution of your program’s SQL within the Steps Can have performance information logged Trace options may be set in Configuration Manager if running 2-tier or through the

Command Line

Step Reports each step name that is executed, along with a timestamp, the DO level and the statement type

SQL Same as Step, plus report formatted SQL processes including COMMITs, ROLLBACKs, and Restarts

Ded. Temp. Table Writes the details of the temporary tables used to the trace fileStatement Timings (file) – Initiates the AE timings trace which monitors the execution

timing of each statement and is written to the bottom of the AE Trace file.

Statement Timings (table) – Writes the Statement Timings traces to a table so you can store historical data in the database and do custom reporting

DB Optimizer (file) – Reveals the execution/query plan for the SQL that the AppEngine program generates


Application Engine Interactive Debugger Online, interactive, execution-monitoring tool Run application step by step and look at the results of the execution in the State record Can dynamically modify the State record Set Break Points and Watch Fields

Debug Commands: (Q)uit Rollback work and end program E(X)it Commit work and end program (valid between steps) (C)omit Commit work (valid between steps) (B)reak Set or remove a break point (L)ook Examine state record fields (M)odify Change a state record field (W)atch Set or remove a watch field (S)tep over Execute current step or action and stop Step (I)nto Go inside current step or called section and stop Step (O)ut of Execute rest of step or called section and stop (G)o Resume execution (R)un to commit Resume execution and stop after next commit

For more information on the debug commands, please seePeopleBooks Library > PeopleSoft 8.14: Application Engine > Advanced Development

Command Line Parameters (from PeopleBooks rel 8.4)-CT <dbtype> Required. Corresponds to the type of the database to which you

are connecting. Values are MICROSFT, ORACLE, SYBASE, INFORMIX, DB2UNIX, and DB2.

-CS <server> Required for Sybase, Informix. For those 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.

-CD <database name> Required. Enter the name of the database to which the program will connect.

-CO <oprid> Required. Enter the Operator ID that is running the program.-CP <oprpswd> Required. Enter the password associated with the specified

Operator ID/User ID.-R <run control id> Required. Enter the Run Control ID to use for this run of the

program.-AI <application id> Required. Specify the Application Engine program to run.-I <process_instance> Required for Restart. Enter the Process Instance for the

program run. The default is 0, which means PeopleSoft Application Engine uses the next available Process Instance.

-DEBUG <Y|N> 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.-DR <Y|N> This parameter controls Restart. Enter Y to disable Restart, or

enter N to enable Restart. (DR represents Disable Restart).-TRACE <value> This parameter turns on the Application Engine trace. 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. The current 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 that 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.So, if you wanted to enable the 1, 2, and 128 traces, enter 131—the sum of 1, 2, and 128. To indicate that you do not want any traces, enter 0. If you don't explicitly enter 0, Application Engine will use the trace value set in PeopleSoft Configuration Manager.

-DBFLAGS Using this parameter you can disable the %UpdateStats meta-SQL construct. To disable %UpdateStats enter:-DBFLAGS 1

-TOOLSTRACESQL <value> Use this parameter to enable the SQL Trace. -TOOLSTRACEPC <value> Use this parameter to enable the PeopleCode Trace.psae <Parmfile> If you submit a file to PeopleSoft 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 Windows NT or UNIX Process Scheduler Server environment. For example,psae $temp/myparmfile.txtNote. For security reasons, after Application Engine interprets the contents of the <parmfile>, it immediately deletes the <parmfile>.

-OT <value> (Optional) Use to initialize the PeopleCode meta-variable %OutDestType (Numeric).&ProcessRqst.OutDestType = %OutDestType ;


-OT (Optional) Use to initialize the PeopleCode meta-variable %OutDestFormat (Numeric).PeopleCode example of %OutDestFormat:Query.RunToFile(Record QryPromptRecord, %OutDestFormat);

-FP (Optional) Use to 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;

PeopleCode Debugger Used to diagnose errors occurring in AppEngine PeopleCode (see PeopleCode

documentation). Turned on in Application Designer using the “Debug” option on the menubar.

AppEngine Restarts By default, AppEngine does not perform a COMMIT until the entire program

successfully completes. You must design and set up individual Program level COMMITs where appropriate such as: COMMIT after each Step in a Section Require COMMITs after a Step Defer the COMMIT for a Step COMMIT frequency within a Step or n iterations for looping Actions

Check Points If Restart is enabled, a Program level COMMIT causes AppEngine to perform a

checkpoint beforehand If a failure occurs at any point in the process, the end 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

Note: Manual COMMITs will NOT have a checkpoint written for them and are NOT recommended

Restart from the Command Line: Open a Command window (Start, Programs, Run, and type CMD) 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 <value> -DBFLAGS <value> -TOOLSTRACESQL <value> -TOOLSTRACEPC <value> -OT <value> -OF <value> -FP<value>

Or, if your command line parameters are stored in a text file, you can enter:psae <parmfile>

State Records and Program Structure

When you create AppEngine programs, you will need to pass variables; a State record is the method by which you allocate variables in your AppEngine program, and it is also the method by which you pass the values to subsequent program steps.

An AppEngine program may have zero, one, or many State records. Only one State record will be the default.

A State record may be a derived work record or an SQL table. Derived State records can not have their values saved at commit time, therefore the values would be lost during a restart.

A State record is used as a worktable for: Initial values Values to be passed to program Steps from prior Sections, Steps and Actions Results of SQL Selects Values for SQL Updates, Inserts, Deletes Computed values or counters Program range or scope values (Business Units, Pay Groups, Departments, etc.) Program working values Programmable switches or flags

A State record has the following characteristics: A Database Table (necessary for restartability) or Derived Work Record

The State name must end with _AET identifier PROCESS_INSTANCE must be a key All other fields in the State record are inserted to meet the needs of your program as

you have designed it Date fields can not be defined as required fields %SELECT (meta-SQL) stores data into the State record %BIND (meta-SQL) gets data out of the State record

Can have zero, one, or multiple State records Is used in AppEngine Restart

State records are associated to an AppEngine program using the “State Records” tab in program properties.


Values are inserted into the State record, either by the run control or by using %SELECT in your AppEngine program.

Once a value is inserted into the State record, it can be accessed using %BIND(fieldname).

%SELECT %BINDA %SELECT is required at the beginning of any and all SELECT statements

The %BIND function can be used anywhere in a SQL statement

Example:%SELECT(field1, field2, field3)SELECT NAME, ADDRESS, CITYFROM PS_VENDOR_CONTACTWHERE VENDOR_ID = ‘ACME’

Example:SELECT ITEM_CODE, ITEM_DESCRFROM PS_ITEM_TBLWHERE VENDOR_CODE = %BIND(field1)


Conditional Processing with Do Actions

Do Select Action used to populate State record values within an AppEngine program

Will execute any subsequent actions within the same Step once for every row of data returned by the SQL placed in the Do Select. Equivalent to a FOR loop.

When a Do Select executes, it sets a cursor in the database for all of the rows matching the criteria in the Select statement. The first row is loaded into the State record then the program proceeds to the next action in the Step.

So what exactly is a cursor?Anytime a SQL statement is sent to the database, a cursor must be opened on the database. The cursor is the avenue by which the database will communicate the results of that specific request back to the requestor. When a SELECT statement is executed, the row(s) retrieved are placed into a

memory buffer on the database for that cursor. From there, a FETCH is issued to retrieve the row(s) from the memory buffer as needed.

When a cursor is opened and work performed, it is done so on a conditional basis and has the potential to be undone. If and when a COMMIT statement is issued to the database (which automatically happens at a successful completion of the AppEngine program) this conditional work is now permanent and cannot be undone. Within an AppEngine program, COMMIT can also be issued during the middle of the program’s run. When a COMMIT is issued, it will be issued across ALL cursors opened by the AppEngine program. Once work is COMMITed it cannot be undone.

A ROLLBACK is simply taking all the data that all the cursors have accomplished for your program and undoing it. When issued, a ROLLBACK is done back to the last COMMIT issued. Once a ROLLBACK is issued, a COMMIT that immediately follows would have nothing to COMMIT.

Three select types may be used with Do Select Select/Fetch (default)

Opens a cursor to the database Selects all rows that meet the SQL condition in the Do Select into the memory

buffer and inserts the first row into the State record for processing Executes the Actions in the Step (Call Section, SQL, etc.) Once the subsequent Actions are completed, the program returns to the open

cursor from the Do Select, retrieves the next row and continues again with the rest of the Actions.

Once the Do Select does not retrieve any rows (False), it will skip the subsequent actions in the same step and move onto the next Step in the Section.

If restart is not disabled, all COMMITs executed within the Do Select loop (for example, COMMITs on Called Sections) are ignored. Disabling restart is a simple way of telling the application that you are freeing it up of the


responsibilities of knowing where to restart. The reason these COMMITs are ignored is because of limitations of the checkpoint written to the PS_AERUNCONTROL table. The checkpoint has no way of recording where inside a loop the process left off. Therefore, a restart at the exact point (loop) is impossible.

Reselect (note: this is a memory “hog”) - opens a cursor and closes the cursor in each iteration of the loop. Opens a cursor to the database Selects all rows that meet the SQL condition in the Do Select into the memory

buffer and inserts the first row into the State record for processing Closes the cursor Executes the following Actions in the Step (Call Section, SQL, etc.) Once the subsequent Actions are completed, the program returns to the SQL in

the Do Select and opens a cursor again Essentially, it will be reselecting the same row of data. To prevent being caught

in an endless loop, you need to make the SQL (in the current Step or a Called Section) such that it will be changing the status of the rows in the table the Do Select is selecting. This way you will be reducing the result set of the Do Select until it returns nothing (or a False), thus ending the Do Select loop.

COMMITs are not ignored and will be committed in a Reselect loop. Because the rows being selected are begin changed by your code, provided you COMMIT those changes, the program will have a way to know where in the loop it left off making a restart possible. You need to: Identify the rows to be processed

Process flag Delete rows

Order the data values Place COMMITs in the appropriate Sections or Steps

Remember, whenever a COMMIT is issued inside your program (provided you have NOT disabled restart) a checkpoint is also COMMITed to the PS_AERUNCONTROL table. The last section and step COMMITed will be listed in a column called AE_RUN_DATA.

Restartable Acts exactly like the SELECT and FETCH Opens the cursor and leaves it open Major difference is that it WILL COMMIT inside the loop thus allowing a

checkpoint to the PS_AERUNCONTROL table which is used to restart the program in case of abend

If a program is restartable, you need to design for a restart at every level (as in Program, Section, and Step levels) Program level

State record – at least one of your State records must be a SQL table. If a derived work record is used, AppEngine will re-initialize any State records at each COMMIT


Program properties – on the Advanced tab, make sure that Disable Restart is not checked

Configuration Manager – make sure that Disable Restart is not selected on the Process Scheduler tab

Section level Prepare Only – if a Section is only preparing data (as in SELECTing it,

populating temporary tables, or updating temporary tables), the Section type should be Prepare Only

Critical Updates – if a Section is updating permanent application tables in the database, you should select Critical Updates

Step level – you need to have some conditions that reduce the answer set returned by the DO SELECT Add an order by clause

%SELECT FIELD1SELECT FIELD1 FROM PS_SOME_RECORDWHERE FIELD1 > %BIND(FIELD1)ORDER BY FIELD1

Add a switch to the selected tableSELECT COLUMN1, COLUMN2, … FROM PS_SOME_RECORDWHERE PROCESSING_SWITCH = ‘N’ …

Delete processed rows

Select/Fetch ReSelect RestartableDefinition Opens the cursor

once and performs a fetch for each

iteration of the loop.

Opens a new cursor for each iteration and selects the 1st

row that meets the select criteria.

Opens the cursor once and performs a

fetch for each iteration of the loop.

Restartable from inside the DO SELECT loop No Yes (provided you

code it that way)Yes (provided you code it that way)

Are program level commits performed inside the DO SELECT loop for restartable AE programs?

No Yes Yes

Do you need to reduce the result set of the DO SELECT loop by deleting rows or including a “processed flag”?

No Yes Yes

Do Actions Do When

SELECT statement that allows subsequent Actions to be executed if any rows of data are returned.


First in the order of execution order within a step Will contain SQL that tests for a condition. As long as the condition is TRUE and a

row of data is returned, the subsequent actions within the Step will be performed. If there is no row of data returned, the entire Step will terminate.

Similar to COBOL “IF” statement Executed only once when a Step is executed

Do While SELECT statement that runs before subsequent Actions of the Step. Identical to COBOL “WHILE” function. Subsequent Actions within the Step are executed in a loop as long as the SELECT

statement returns at least one row for the Do While Action.

Do Until SELECT statement that runs after each action within a Step. Used if you want the “processing actions” to execute at least once, and to execute

over and over until a certain condition is true In order to test for a condition, you will need to create a SQL statement that returns a

True or False. For example:SELECT ‘X’ FROM PS_INSTALLATIONWHERE %Bind(COUNTER) < 1000; When this SQL statement executes, it will return TRUE if the value of the field

COUNTER in the State record is less than 1000 and FALSE if the value is equal to or greater than 1000.

Since the condition is being tested by the WHERE clause of the SQL statement in some cases it does not matter which table you select from. For instance, if you are checking a condition on your State record using %BIND() to read a value, the FROM table is irrelevant. Since we only need one ‘X’ returned if our condition is true, any one row table in the FROM clause will suffice. A very common technique seen in AppEngine programming is to use the PS_INSTALLATION as the FROM table (PS_INSTALLATION is a one-row-table delivered from PeopleSoft).


DO Process Program Flow

On Dec. 25th, as long as there are cookies on the table for him to eat, SANTA will leave a gift in an empty stocking hanging by the fireplace. When someone wakes up, he stops. Before he leaves, he turns off the lights.

SANTA MAIN STEP01 Do When Is it Dec 25?

Do While Cookies on the table?Do Select Pick empty stockings CALL SECTION LEAVE_GIFTDo Until Someone wakes up?

STEP02 SQL Turn off lights…

LEAVE_GIFT STEP01 SQL Leave gift…STEP02 SQL Eat cookie…


WHEN a SELECT returns a row

WHILE a SELECT returns a row

For every row returned from a SELECT, continue in the following order:

Execute PeopleCode, if any

Execute SQL or Execute the CALL SECTION

Insert message into the Message Log

UNTIL a SELECT returns a row

Loop

T

T

T

T

Next Step

F

F

F

F

PeopleCode and Application Engine

Setting IF, THEN, ELSE logic constructs Performing data “preparation” tasks Building dynamic portions of SQL, while still relying on SQL to complete the bulk of the

actual program processing (do NOT execute SQL within PeopleCode inside AppEngine) Reusing online logic that’s already developed Leveraging new technologies – Business Interlinks, File objects, Component Interfaces

Setting IF, THEN, ELSE logic constructs IF-THEN statement is used to control flow of execution with the EXIT statement. The

setting of the Exit can cause the next AppEngine Step to conditionally be skipped.If &Test = 10 Then Exit(0);Else Exit(1);End-If;

The parameter in the Exit function controls the path the AppEngine program will takeOne (1) indicates that the instruction to be done On Return will be doneZero (0) tells the program to ignore the On Return action (normal processing).

On Return options are: Abort: The program issues an error and exits immediately Break: The program exits the current Step and Section and control returns to the

calling Step Skip Step: The program exits the current Step and continues processing at the next

Step in the Section. If this is the last Step in the Section, the call in Step resumes control of the processing.

Dynamic Calls Rather than calling one specific Section, you can take advantage of the AE_APPLID

and AE_SECTION fields in the State record to execute different Sections depending on the conditions a program encounters during runtime.


If you are using the section within one AppEngine program, then only the AE_SECTION field must be included on the State record. If you want to call a section in other AppEngine programs, you will need to define both AE_APPLID and AE_SECTION on the State record.

You enable a Dynamic Call by first having your program store different Section names in the AE_SECTION field and different program names in AE_APPLID field.For example:Section Step ActionMAIN STEPM01 Pcode If AE_STATEREC_AET.NBR = 5 Then

AE_STATEREC_AET.AE_SECTION = “MESSAGE1”;ElseAE_STATEREC_AET.AE_SECTION = “MESSAGE2”;End-If;

Call Section

Dynamic Call (checkbox)

MESSAGE1 STEPMM1 Log Message

“Number equal to 5”

MESSAGE2 STEPMM2 Log Message

“Number not equal to 5”

Set ProcessingSQL was designed to let you specify sets of data in which you are interested. Set Processing takes advantage of this SQL characteristic to process groups, or sets, of rows at one time rather than processing each row individually. In most cases, Set Processing (if implemented properly) is more efficient that row-by-row processing, especially for high-volume applications

What is Set Processing? Uses SQL to process groups, or sets, of rows at one time rather than processing each row

individually Used for UPDATE or INSERT SQL statements (and SELECT statements used as sub-

queries of an UPDATE or INSERT) The bulk of the performance gain lies in the fact that the processing occurs in the

database engine as opposed to in the AppEngine program. Since the data never leaves the database engine, you effectively eliminate the network round trip and database API overhead required to pull the data into the AppEngine program and then insert the results back into the database.

Set Processing and Temporary Tables Set Processing makes use of temporary tables to preselect data that can then be handled

via a single SQL statement. Temporary tables are “unofficial” temporary tables marked as SQL table record type

(naming convention _TMP)


Temporary tables are designed to accomplish the following: Hold transaction data for the current run or iteration of the program Contain only those rows of data affected by the business rule Present key information in a denormalized or “flattened” form, which provides the

most efficient processing Switch the keys for rows coming from the master tables if needed. A transaction may

use a different key than what appears on the master tables.

Temporary Tables Using Temporary Tables for Parallel Processing

Because Application Engine programs run in batch mode, multiple instances of the same program often execute in parallel. When this happens, there is a significant risk of data contention and deadlocks on tables. To avoid this PeopleTools has a feature that enables you to dedicate specific instances of temporary tables for each program run.

You can also use temporary tables to improve performance. For example, if you find that multiple times during a run the program accesses a small subset of rows from a much larger table, you can insert the necessary rows into a temporary table as an initialization task. Then the program accesses the data residing in the smaller temporary table rather than the large application table. This technique is similar to reading the data into an array in memory, except that the data never leaves the database, which is an important consideration when the program employs a set-based processing algorithm.

There is no simple switch or checkbox that enables you to turn parallel processing on and off. To implement parallel processing, you need to complete a set of tasks in the order that they are listed: Set the Temporary Table Online pool. This will set the basic Temporary Table

Online pool based on the PeopleTools Options specifications (this is done one time for the installation…if the PeopleTools Options for the temp table online pool are changed ALL temporary tables must be rebuilt…not just yours!)

Define your Temporary Tables by defining and saving your Temporary Table records as type “Temporary Table”. Process Instance should be the first field and key; just as for State Records.

Assign Temporary Tables to your AppEngine program in its Program Properties setting the appropriate number of Instance counts and Runtime option.

Set Temporary Table Batch Pool by setting the instance count in the program properties (Ask yourself…how many tables does this program need?)

Build/Rebuild your Temporary Table record. This will build the necessary Batch temporary tables into that record’s Temporary Table pool for use at execution time.

Code %Table meta-SQL as references to Temporary Tables in your AppEngine program so that AppEngine can resolve table references to the assigned Temporary Table instance dynamically at runtime.


Runtime Allocation and BehaviorOnline Batch

Allocation meta-SQL %Table(temp-tbl) %Table(temp-tbl)Runtime Table Allocation PSAE.EXE randomly

assigns an Instance Number from the number range on your Online Temp Tables. Uses that number for all Temp Tables for that run’s Temp Tables.

Individually allocates Batch Temp Table instance number based on availability on a record-by-record bases. PSAE.EXE begins with the lowest instance number available for each Temporary Table until all of the Temporary Tables instances are in use.

No Temp Tables Free For a particular record, if the instance is currently in use, then the PSAE.EXE queues the program until the assigned Instance number becomes free.

If out of free Temporary Tables and Continue set – used shared Base table.

If an assignment cannot be made and the program is set to Abort, then execution will terminate.

Never queues for a table.Initially Clear Temp Table

Yes, when program Instance comes available.

Yes, when assigned.

Locked Lock on when AE program is loading into memory.

Lock on when the AE program is loading into memory.

Un-lock Unlock on completion of program.

On crash, free from Manage Abends.

If Restartable, stays locked across Restarts until completes successfully.

If not Restartable, unlocked on program completion. “Kill” program requires manually freeing tables.

Cancel from Process Monitor frees tables.


Application Engine

Documents

entire appengine program

application engine programs

section sql

program program flow

entire program

type of program

standalone program

multiple appengine programs