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.

Application Engine

July 2005

Page 2 of 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 Application program Composed of one or more Sections Section Callable block of logic Composed of one or more Steps First Section is always MAIN Steps Logical groupings of actions Composed of one or more actions Smallest unit of work COMMITED Actions Line of Code Can execute: - Do When - Do While - Do Select - PeopleCode - Call Section - SQL - Log Message - Do Until - XSLT Must be unique within Step Executed in specific order

Starts with MAIN 12 character limit for application program name

Can be specified by: - Market - Effective Date - Effective Status - Platform generic or specific Executed only when Executed from top called (except to bottom within the MAIN Section) Section

Application Engine

July 2005

Page 3 of 25

 Program Properties (Advanced tab) Item Disable Restart Application Library Description Select this to disable the AppEngine built-in restart capabilities useful when testing 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. 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. 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. 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 isnt specified. 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).

Upgrade Only (rel 8.2)

Batch Only (rel 8.4)

Message Set

Program Type (rel 8.4)

Application Engine

July 2005

Page 4 of 25

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 systems requirements. Perform a data translation on a message so its data is represented according to the target systems conventions. Determine whether to pass a message through to its target, by filtering it based on its content.

Application Engine

July 2005

Page 5 of 25

 AppEngine Program Structures Sections One One One Multiple Inserting Sections and Steps Steps One One Multiple One per Section to Many per Section Actions One Multiple One per Step to Many per Step One per Step to Many per Step

Sections Control Section Name Description Market Platform Effective Date Effective Status Section Type Description Be as descriptive as possible 8 character limit Descriptive name for the Section 30 character limit The market for which the Section is intended. If a particular market is irrelevant to your batch program, leave as GBL 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. Default is 01/01/1900. May be used to make a particular Section effective-dated Used to activate/inactivate a Section 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. Specify the COMMIT level for the section. Can opt to have not July 2005 Page 6 of 25

Auto Commit Application Engine

Access Comments Steps Control Step Name Step Description Commit After

COMMIT or have AppEngine COMMIT after each Step in the Section successfully completes (not efficient!) This property controls the Call Section Action. Specify that a Section can or cant be called from another program Use the comments section to document the Section

Frequency On Error

Active Comments

Description Consecutively numbered based on the last step name 8 char limit Descriptive name for the Step 30 character limit Determines when COMMIT will be executed: - Default: uses values supplied for the Section - Later: do not COMMIT now - After Step: COMMIT when step completes Note: Later and After Step override the Section Auto Commit setting Only available in loops 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 Determines if the Step is active (checked) or inactive (blank) Add any additional comments to document the program

Action Execution Order 1. Do When 2. Do While 3. Do Select 4. PeopleCode 5. SQL or Call Section 6. Message Log 7. Do Until 8. XSLT (enabled for transformation programs in rel 8.4) Notes: SQL and Call Section are mutually exclusive XSLT 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. Application Engine July 2005 Page 7 of 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, 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

July 2005

Page 8 of 25

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. Application Engine July 2005 Page 9 of 25

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

Run Minimized Output Log to File Log File Name Process Instance

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. Select this to have the window of the requested process minimized when it is submitted to run. Select this is you want the output log to be written to a file. Specify the log file name (enabled only when Output Log to File is checked) Defaults to 0 Doesnt do anything

Through the Process Scheduler (rel 8.4 Developers 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

July 2005

Page 10 of 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 your AppEngine 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 SQL Ded. Temp. Table Statement Timings Statement Timings DB Optimizer

Reports each step name that is executed, along with a timestamp, the DO level and the statement type Same as Step, plus report formatted SQL processes including COMMITs, ROLLBACKs, and Restarts Writes the details of the temporary tables used to the trace file (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. (table) Writes the Statement Timings traces to a table so you can store historical data in the database and do custom reporting (file) Reveals the execution/query plan for the SQL that the AppEngine program generates

Application Engine

July 2005

Page 11 of 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 E(X)it (C)omit (B)reak (L)ook (M)odify (W)atch (S)tep over Step (I)nto Step (O)ut of (G)o (R)un to commit

Rollback work and end program Commit work and end program (valid between steps) Commit work (valid between steps) Set or remove a break point Examine state record fields Change a state record field Set or remove a watch field Execute current step or action and stop Go inside current step or called section and stop Execute rest of step or called section and stop Resume execution Resume execution and stop after next commit

For more information on the debug commands, please see PeopleBooks 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 Application Engine July 2005 Page 12 of 25

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: 1Initiates the Application Engine Step trace. 2Initiates the Application Engine SQL trace. 128Initiates the Application Engine timings file trace, which is similar to the COBOL timings trace. 256Includes the PeopleCode Detail Timings in the 128 trace. 1024Initiates the Application Engine timings table trace that stores the results in database tables. 2048Initiates the database optimizer "explain", writing the results to the trace file. This option is supported only on Oracle, Informix, and Microsoft SQL Server. 4096Initiates 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 metaSQL 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.txt Note. 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 ; Application Engine July 2005 Page 13 of 25

-OT

-FP

(Optional) Use to initialize the PeopleCode meta-variable %OutDestFormat (Numeric). PeopleCode example of %OutDestFormat: Query.RunToFile(Record QryPromptRecord, %OutDestFormat); (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> Application Engine July 2005 Page 14 of 25

-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. Application Engine July 2005 Page 15 of 25

 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 A %SELECT is required at the beginning of any and all SELECT statements Example: %SELECT(field1, field2, field3) SELECT NAME, ADDRESS, CITY FROM PS_VENDOR_CONTACT WHERE VENDOR_ID = ACME

%BIND The %BIND function can be used anywhere in a SQL statement Example: SELECT ITEM_CODE, ITEM_DESCR FROM PS_ITEM_TBL WHERE VENDOR_CODE = %BIND(field1)

Application Engine

July 2005

Page 16 of 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 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 programs 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 Application Engine July 2005 Page 17 of 25

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 July 2005 Page 18 of 25

Application Engine

 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 FIELD1 SELECT FIELD1 FROM PS_SOME_RECORD WHERE FIELD1 > %BIND(FIELD1) ORDER BY FIELD1 Add a switch to the selected table SELECT COLUMN1, COLUMN2, FROM PS_SOME_RECORD WHERE PROCESSING_SWITCH = N Delete processed rows Definition Select/Fetch Opens the cursor once and performs a fetch for each iteration of the loop. No No ReSelect Opens a new cursor for each iteration and selects the 1st row that meets the select criteria. Yes (provided you code it that way) Yes Restartable Opens the cursor once and performs a fetch for each iteration of the loop. Yes (provided you code it that way) Yes

Restartable from inside the DO SELECT loop Are program level commits performed inside the DO SELECT loop for restartable AE programs? Do you need to reduce the result set of the DO SELECT loop by deleting rows or including a processed flag?

No

Yes

Yes

Application Engine

July 2005

Page 19 of 25

 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_INSTALLATION WHERE %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).

Application Engine

July 2005

Page 20 of 25

DO Process Program Flow WHEN a SELECT returns a row WHILE a SELECT returns a row T T F F

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

Execute PeopleCode, if any Execute SQL or Execute the CALL SECTION Insert message into the Message Log UNTIL a SELECT returns a row

F T

Next Step 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 Do While Do Select CALL SECTION Do Until SQL SQL SQL Is it Dec 25? Cookies on the table? Pick empty stockings LEAVE_GIFT Someone wakes up? Turn off lights Leave gift Eat cookie

STEP02 LEAVE_GIFT STEP01 STEP02

Application Engine

July 2005

Page 21 of 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. 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 take One (1) indicates that the instruction to be done On Return will be done Zero (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. Application Engine July 2005 Page 22 of 25

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 Action If AE_STATEREC_AET.NBR = 5 Then MAIN STEPM01 Pcode
AE_STATEREC_AET.AE_SECTION = MESSAGE1; Else AE_STATEREC_AET.AE_SECTION = MESSAGE2; End-If;

Call Dynamic Call (checkbox) Section MESSAGE1 STEPMM1 Log Number equal to 5 Message MESSAGE2 STEPMM2 Log Number not equal to 5 Message

Set Processing
SQL 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 subqueries 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)

Application Engine

July 2005

Page 23 of 25

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 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 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 yourselfhow many tables does this program need?) Build/Rebuild your Temporary Table record. This will build the necessary Batch temporary tables into that records 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.

Application Engine

July 2005

Page 24 of 25

Runtime Allocation and Behavior Allocation meta-SQL Runtime Table Allocation Online %Table(temp-tbl) 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 runs Temp Tables. Batch %Table(temp-tbl) Individually allocates Batch Temp Table instance number based on availability on a record-byrecord bases. PSAE.EXE begins with the lowest instance number available for each Temporary Table until all of the Temporary Tables instances are in use. If out of free Temporary Tables and Continue set used shared Base table.

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 If an assignment cannot be becomes free. made and the program is set to Abort, then execution will terminate. Never queues for a table. Yes, when program Instance Yes, when assigned. comes available. Lock on when AE program Lock on when the AE is loading into memory. program is loading into memory. Unlock on completion of If Restartable, stays locked program. across Restarts until completes successfully. On crash, free from Manage Abends. If not Restartable, unlocked on program completion. Kill program requires manually freeing tables. Cancel from Process Monitor frees tables.

Initially Clear Temp Table Locked Un-lock

Application Engine

July 2005

Page 25 of 25