Application Engine Indetail

8/3/2019 Application Engine Indetail

1/25

Application Engine

What is Application Engine?

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

In the realm of AppEngine, aprogram is a set of SQL statements, PeopleCode, and ProgramControl Actions (that allow looping and conditional logic) defined in AppDesigner thatperforms 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 youprovide. 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 withthe operating environment used.

Develop your entire program from scratch, including table definitions, all withinAppDesigner and then run and debug the application without exiting PeopleTools.

Data Dictionary Integration

AppEngine works in harmony within the PeopleSoft system and references the datadictionary for object definitions; changes to meta-data in the database have no impacton 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 thisproblem using PeopleSoft meta-SQL, which AppEngine supports. This language is

designed to replace RDBMS-specific SQL syntax with a standard syntax, calledmeta-strings.

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

Application Engine July 2005 Page 1 of 25


2/25

Effective-Dating

Application sections are effective-dated meaning you can activate/deactivate a sectionof the program as of a particular date. This enables you to archive sections as youmodify 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 becomesa checkpoint that AppEngine uses to locate where within a program to restart after anabend.

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



3/25

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 Actions

Applicationprogram

Callable block oflogic

Logical groupings ofactions

Line of Code

Composed of one ormore Sections

Composed of one ormore Steps

First Section isalways MAIN

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

Composed of one ormore actions

Smallest unit ofwork COMMITED

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

Starts with MAIN

12 character limitfor applicationprogram name

Executed only whencalled (exceptMAIN Section)

Executed from topto bottom within theSection

Must be uniquewithin Step

Executed in specificorder



4/25

Program Properties (Advanced tab)

Item Description

Disable Restart Select this to disable the AppEngine built-in restart capabilities useful when testing

Application Library In some cases, you may want a program to contain only acollection, or library or common routines (callable sections)that will not run as a standalone program. When Sections aredefined as Public, other programs can call the Sections that existin the library at runtime. Because this type of program is notdesigned to run as a standalone program, it does not require theMAIN Section.

Upgrade Only(rel 8.2)

This option is for programs intended to be used for upgradepurposes only. PeopleSoft delivers some Application Engineprograms for upgrade-only uses. Unless you are responsible forthe 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() PeopleCodefunction. Any dedicated temporary table used for Batch Onlyprograms do not have online instances created.

Message Set Specify the message set value assigned as the default message setnumber for this AppEngine program. The system uses thismessage set value for all log messages where the message set isntspecified.

Program Type(rel 8.4)

Select the appropriate program type from the list: Standard (whichis a normal entry-point program), Upgrade Only (which is used in

PeopleSoft Upgrade utilities), Import Only (which is used byPeopleSoft Import utilities like File Layout), Daemon Only (aspecial type of program used as a daemon) or Transform Only(another special program type used to support XSLT).



5/25

PSDaemon (rel 8.4)

PSDAEMON is a process that runs continuously when the Process Scheduler isrunning and is intended for recurrent jobs. It polls the system checking for certainconditions to be true for events and when true, it schedules a process to handle theevent. 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 DaemonGroup. The Daemon Group is attached to a Process Scheduler Server and daemon isenabled.

Steps involved in setting up PSDAEMON

Create AppEngine program with program type of Daemon Only (Programproperties)

Add Daemon program to a Daemon Group (contains all the daemonprograms 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 oneanother by transforming messages into appropriate formats. When you specify anApplication Engine as a Transform Only program, you must specify an Action Typeof XSLT.

You can use transform programs to do any of the following:

Apply a transformation to a message to make its structure comply with thetarget systems requirements.

Perform a data translation on a message so its data is representedaccording to the target systems conventions.

Determine whether to pass a message through to its target, byfilteringitbased on its content.



6/25

AppEngine Program Structures

Sections Steps Actions

One One One

One One Multiple

One Multiple One per Step toMany per Step

Multiple One per Section toMany per Section

One per Step toMany per Step

Inserting Sections and Steps

Sections

Control Description

Section Name Be as descriptive as possible 8 character limit

Description Descriptive name for the Section 30 character limit

Market The market for which the Section is intended. If a particular marketis irrelevant to your batch program, leave as GBL

Platform Used to specify Section is to be run on a particular platform. Enablesyou to take advantage of any RDBMS-specific optimizations or tochange section logic because of RDBMS limitations.

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

effective-datedEffective Status Used to activate/inactivate a Section

Section Type In case of abend, the value of this system field specifies whether ornot the Section will need to be restarted. If a section controls aprocedure that, if not run to completion, could corrupt ordesynchronize your data, select Critical Updates. Otherwise, use thedefault value ofPreparation Only.

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



7/25

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

Access This property controls the Call Section Action. Specify that a Sectioncan or cant be called from another program

Comments Use the comments section to document the Section

Steps

Control Description

Step Name Consecutively numbered based on the last step name 8 char limit

Step Description Descriptive name for the Step 30 character limit

Commit 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 settingFrequency Only available in loops

On 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 componentsof a batch program. Selecting this means the database engine only needs to compilethe SQL once, which reduces SQL overhead. Choices are Yes, No, and Bulk Insert.



8/25

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, orRestartable.

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

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 thatApplication 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 controlreturns to the calling Step

Continue: the program continues processing

Skip Step: AppEngine exits the current Step immediately and moves on to thenext Step. When using Skip Step, keep the following in mind:

AppEngine ignores the commit for the current Step at runtimeIf 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 programidentified 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 thatexist 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 containsall 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.



9/25

Application Engine Execution Batch

Most typical mode of execution

Invoke programs using Process Scheduler (requires a Process Definition) or theAppEngine 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 needto 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 whichserves 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 DebuggingAs with any program you develop, writing the code represents just half of your developmenteffort. The other half consists of testing your program to make sure it successfully executes thelogic 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 yourprograms.

Testing AppEngine Programs

Execute directly from AppDesigner in 2-tier

SelectEdit, 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 atexecution time.



10/25

AppEngine programs executed in 2-tier are not displayed on the Process Monitor

If program does not completed successfully andDisable Restartwas not set on theAppEngine program Advanced tab, you will have to restart the program through theCommand Line (see next section)

Run Control ID Enter the run control ID of the program you are testing. Ifyour program requires run control parameters, you willneed to populate the fields on the run control and specifythe run control when executing from AppDesigner.

Run Minimized Select this to have the window of the requested processminimized 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 Doesnt do anything

Through the Process Scheduler (rel 8.4 Developers Shortcut - Generic ApplicationEngine Test Type)

Rel 8.4 system is delivered with a page designed for developers to test AppEngineprograms. The Request AE page allows you to enter parameters associated with theAppEngine program. This page should not be used in Production to executeAppEngine 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



11/25

Application Engine Trace File

Generates a trace at your request

Can specify Steps to see a sequence of messages tracking the Step execution of yourAppEngine program

Can also trace more detailed execution of your programs 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 includingCOMMITs, 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 AETrace file.

Statement Timings (table) Writes the Statement Timings traces to a table so you can

store historical data in the database and do custom reportingDB Optimizer (file) Reveals the execution/query plan for the SQL that theAppEngine program generates



12/25

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 Required. Corresponds to the type of the database to which youare connecting. Values are MICROSFT, ORACLE, SYBASE,

INFORMIX, DB2UNIX, and DB2.-CS Required for Sybase, Informix. For those platforms that require

a server name as part of sign on, enter the appropriate servername. This affects Sybase, Informix, and Microsoft SQLServer. However, for Microsoft SQL Server, this option is validbut not required.

-CD Required. Enter the name of the database to which the programwill connect.

-CO Required. Enter the Operator ID that is running the program.

-CP Required. Enter the password associated with the specifiedOperator ID/User ID.

-R Required. Enter the Run Control ID to use for this run of theprogram.

-AI Required. Specify the Application Engine program to run.

-I Required for Restart. Enter the Process Instance for the programrun. The default is 0, which means PeopleSoft ApplicationEngine uses the next available Process Instance.

-DEBUG This parameter controls the Debug utility. EnterYto indicate



13/25

that you want the program to run in debugging mode, or enterNto indicate that you do not.

-DR This parameter controls Restart. EnterYto disable Restart, orenterNto enable Restart. (DR represents Disable Restart).

-TRACE This parameter turns on the Application Engine trace. To enable

tracing from the command line, enter this parameter and aspecific Trace value. The value you enter is the sum of thespecific traces that you want to enable. The current traces andvalues are:1Initiates the Application Engine Step trace.2Initiates the Application Engine SQL trace.128Initiates the Application Engine timings file trace, whichis similar to the COBOL timings trace.256Includes the PeopleCode Detail Timings in the 128 trace.1024Initiates the Application Engine timings table trace thatstores the results in database tables.

2048Initiates the database optimizer "explain", writing theresults to the trace file. This option is supported only on Oracle,Informix, and Microsoft SQL Server.4096Initiates the database optimizer "explain", storing theresults in the Explain Plan Table of the current database. Thisoption is supported only on Oracle, DB2, and Microsoft SQLServer.So, if you wanted to enable the 1, 2, and 128 traces, enter131the sum of 1, 2, and 128. To indicate that you do not want anytraces, enter0. If you don't explicitly enter0, ApplicationEngine 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 Use this parameter to enable the SQL Trace.

-TOOLSTRACEPC Use this parameter to enable the PeopleCode Trace.

psae If you submit a file to PeopleSoft Application Engine as the firstparameter in the command line, Application Engine reads thecontents of the file and interprets the contents as if it wereparameters entered on the command line. This option isintended mainly for the Windows NT or UNIX Process

Scheduler Server environment. For example,psae $temp/myparmfile.txtNote. For security reasons, after Application Engine interpretsthe contents of the , it immediately deletes the.

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



14/25

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

AppEngine Restarts

By default, AppEngine does not perform a COMMIT until the entire programsuccessfully completes. You must design and set up individual Program level COMMITswhere 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 orn iterations for looping Actions

Check Points

If Restart is enabled, a Program level COMMIT causes AppEngine to perform acheckpoint beforehand

If a failure occurs at any point in the process, the end user can restart the program andexpect 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 theApplication Engine executable (PSAE.EXE) followed by the required parameters, asshown in the following example:psae -CT -CS -CD -CO

-CP -R -AI -I



15/25

-DEBUG -DR -TRACE -DBFLAGS -TOOLSTRACESQL -TOOLSTRACEPC -OT -OF -FP

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

State Records and Program Structure

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

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

A State record may be a derived work record or an SQL table. Derived State records can nothave 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 asyou 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 inprogram properties.



16/25

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

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

%SELECT %BIND

A %SELECT is required at the beginning ofany and all SELECT statements

The %BIND function can be used anywhere ina 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)



17/25

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 datareturned 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 matchingthe criteria in the Select statement. The first row is loaded into the State record then theprogram 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 thedatabase. 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 toretrieve 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 andhas the potential to be undone. If and when a COMMIT statement is issued to thedatabase (which automatically happens at a successful completion of the AppEngineprogram) this conditional work is now permanent and cannot be undone. Within anAppEngine program, COMMIT can also be issued during the middle of theprograms run. When a COMMIT is issued, it will be issued across ALL cursorsopened by the AppEngine program. Once work is COMMITed it cannotbe undone.

A ROLLBACK is simply taking all the data that all the cursors have accomplishedfor your program and undoing it. When issued, a ROLLBACK is done back to thelast COMMIT issued. Once a ROLLBACK is issued, a COMMIT that immediatelyfollows 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 memorybuffer 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 restof the Actions.

Once the Do Select does not retrieve any rows (False), it will skip the subsequentactions 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 (forexample, COMMITs on Called Sections) are ignored. Disabling restart is a



18/25

simple way of telling the application that you are freeing it up of theresponsibilities of knowing where to restart. The reason these COMMITs areignored is because of limitations of the checkpoint written to thePS_AERUNCONTROL table. The checkpoint has no way of recording whereinside 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 eachiteration of the loop.

Opens a cursor to the database

Selects all rows that meet the SQL condition in the Do Select into the memorybuffer 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 inthe Do Select and opens a cursor again

Essentially, it will be reselecting the same row of data. To prevent being caughtin an endless loop, you need to make the SQL (in the current Step or a CalledSection) such that it will be changing the status of the rows in the table the DoSelect is selecting. This way you will be reducing the result set of the Do Selectuntil it returns nothing (or a False), thus ending the Do Select loop.

COMMITs are notignored and will be committed in a Reselect loop. Because therows being selected are begin changed by your code, provided you COMMITthose changes, the program will have a way to know where in the loop it left offmaking 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 youhave NOT disabled restart) a checkpoint is also COMMITed to thePS_AERUNCONTROL table. The last section and step COMMITed will belisted 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 theprogram in case of abend

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

Program level



19/25

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

Program properties on the Advanced tab, make sure thatDisable Restartis not checked

Configuration Manager make sure thatDisable Restartis not selected onthe 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 Sectiontype should bePrepare Only

Critical Updates if a Section is updating permanent application tables inthe database, you should select Critical Updates

Step level you need to have some conditions that reduce the answer setreturned 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 Restartable

Definition Opens the cursoronce and performs a

fetch for eachiteration of the loop.

Opens a new cursorfor each iterationand selects the 1st

row that meets theselect criteria.

Opens the cursoronce and performs a

fetch for eachiteration of the loop.

Restartable from inside

the DO SELECT loop No Yes (provided youcode it that way)

Yes (provided youcode 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



20/25

Do Actions

Do When

SELECT statement that allows subsequent Actions to be executed if any rows of dataare 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 arow of data is returned, the subsequent actions within the Step will be performed. Ifthere 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 aftereach action within a Step.

Used if you want the processing actions to execute at least once, and to executeover 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 aTrue 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 equalto or greater than 1000.

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



21/25

DO Process Program Flow

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

SANTAMAIN STEP01 Do When Is it Dec 25?

Do While Cookies on the table?Do Select Pick empty stockingsCALL SECTION LEAVE_GIFT

Do Until Someone wakes up?STEP02 SQL Turn off lights

LEAVE_GIFT STEP01 SQL Leave giftSTEP02 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 orExecute 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


22/25

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 thats 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. Thesetting of the Exit can cause the next AppEngine Step to conditionally be skipped.

If &Test = 10 ThenExit(0);

ElseExit(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 thecalling Step

Skip Step: The program exits the current Step and continues processing at the nextStep in the Section. If this is the last Step in the Section, the call in Step resumescontrol of the processing.

Dynamic Calls

Rather than calling one specific Section, you can take advantage of the AE_APPLIDand AE_SECTION fields in the State record to execute different Sections dependingon the conditions a program encounters during runtime.



23/25

If you are using the section within one AppEngine program, then only theAE_SECTION field must be included on the State record. If you want to call asection in other AppEngine programs, you will need to define both AE_APPLID andAE_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 Action

MAIN STEPM01 Pcode If AE_STATEREC_AET.NBR = 5 ThenAE_STATEREC_AET.AE_SECTION =

MESSAGE1;ElseAE_STATEREC_AET.AE_SECTION =MESSAGE2;End-If;

CallSection

Dynamic Call (checkbox)

MESSAGE1 STEPMM1 LogMessage

Number equal to 5

MESSAGE2 STEPMM2 LogMessage

Number not equal to 5

Set ProcessingSQL was designed to let you specify sets of data in which you are interested. Set Processingtakes advantage of this SQL characteristic to process groups, or sets, of rows at one time ratherthan 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 rowindividually

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 thedatabase engine as opposed to in the AppEngine program. Since the data never leavesthe database engine, you effectively eliminate the network round trip and database APIoverhead required to pull the data into the AppEngine program and then insert the resultsback into the database.

Set Processing and Temporary Tables

Set Processing makes use of temporary tables to preselect data that can then be handledvia a single SQL statement.

Temporary tables are unofficial temporary tables marked as SQL table record type(naming convention _TMP)



24/25

Temporary tables are designed to accomplish the following:Hold transaction data for the current run or iteration of the programContain only those rows of data affected by the business rulePresent 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 adifferent 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 sameprogram often execute in parallel. When this happens, there is a significant risk of datacontention and deadlocks on tables. To avoid this PeopleTools has a feature that enablesyou to dedicate specific instances oftemporary tables for each program run.

You can also use temporary tables to improve performance. For example, if you find thatmultiple 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 initializationtask. Then the program accesses the data residing in the smaller temporary table ratherthan the large application table. This technique is similar to reading the data into an arrayin memory, except that the data never leaves the database, which is an importantconsideration when the program employs a set-based processing algorithm.

There is no simple switch or checkbox that enables you to turn parallel processing on andoff. To implement parallel processing, you need to complete a set of tasks in the orderthat they are listed:

Set the Temporary Table Online pool. This will set the basic Temporary TableOnline pool based on the PeopleTools Options specifications (this is done one timefor the installationif the PeopleTools Options for the temp table online pool are

changed ALL temporary tables must be rebuiltnot 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 andkey; 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 programproperties (Ask yourselfhow many tables does this program need?)

Build/Rebuild your Temporary Table record. This will build the necessary Batchtemporary tables into that records Temporary Table pool for use at execution time.

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



25/25

Runtime Allocation and Behavior

Online Batch

Allocation meta-SQL %Table(temp-tbl) %Table(temp-tbl)

Runtime Table Allocation PSAE.EXE randomlyassigns an Instance Number

from the number range onyour Online Temp Tables.Uses that number for allTemp Tables for that runsTemp Tables.

Individually allocates BatchTemp Table instance

number based onavailability on a record-by-record bases. PSAE.EXEbegins with the lowestinstance number availablefor each Temporary Tableuntil all of the TemporaryTables instances are in use.

No Temp Tables Free For a particular record, ifthe instance is currently inuse, then the PSAE.EXE

queues the program until theassigned Instance numberbecomes free.

If out of free TemporaryTables and Continue set used shared Base table.

If an assignment cannot bemade and the program is settoAbort, then execution willterminate.

Never queues for a table.

Initially Clear Temp

Table

Yes, when program Instancecomes available.

Yes, when assigned.

Locked Lock on when AE programis loading into memory.

Lock on when the AEprogram is loading into

memory.Un-lock Unlock on completion of

program.

On crash, free from ManageAbends.

If Restartable, stays lockedacross Restarts untilcompletes successfully.

If not Restartable, unlockedon program completion.Kill program requiresmanually freeing tables.

Cancel from Process

Monitor frees tables.

A li ti E i J l 2005 P 25 f 25

Application Engine Indetail

Documents

Transcript of Application Engine Indetail