Application Engine

Application Engine

Application Engine programs are PeopleSoft's batch processing technology. They are developed in application designer and consist of blocks of PeopleCode and SQL. Application engine programs can also use application classes, compoonent interfaces, XML publisher reports, and call SQRs and COBOLs through PeopleCode.

Program Structure

Application engine programs are have very structured hierarchy (loosely based on COBOL). They consist of a single application (application engine program) that can consist of one or more sections. Each section can contain one or more steps, and each step can contain one or more actions. The actions in a step can include:

SQL actions

Do actions

PeopleCode actions

Call Section actions

Log Message actions

Program Properties

There are number of properties associated with an application engine program. These include:

General PeopleSoft object properties

State records

Temporary Tables

Advanced program properties

There several different types of application engine programs:

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.

Daemon Only, a type of program used as a daemon process.

Transform Only, a program type used to support Extensible Stylesheet Language Transformations (XSLT).

State Records

A state record is a PeopleSoft record object that contains one or fields used by the program to pass values between steps and actions. Essentially it is a work record for your application to store common variables that can then be used throughout the program. A state record can either be a database table or a PeopleSoft work record. If you make a state record a database table it must be keyed by process instance. Otherwise the state record will not work properly.

Because state records contain process instance, you can use the following SQL action to ge tthe operator ID and run control ID of the person who triggerred the application engine program.

%Select(OPRID,RUN_CNTL_ID)

 SELECT OPRID ,RUN_CNTL_ID

 FROM PS_AE_REQUEST

 WHERE PROCESS_INSTANCE = %Bind(PROCESS_INSTANCE)

Note %Select and %Bind are special Meta-SQL elements for working with application engine state records. {{%Select}} puts data in the state record and %Bind gets data from the state record. Think Select-In and Bind-Out.

Logging to the Message Log

The PeopleSoft Process Scheduler provides access to the message log. The message log is part of the PROCESSMONITOR component - it is defined in the page object PMN_BAT_MSGLOG. You can use log message actions in application engine programs to write to the message log - essentially the PS_MESSAGE_LOG table behind the scenes.

Call Sections

Call sections can be dynamic. To use a dynamic call section:

Add the fields {{AE_APPLID}} and {{AE_SECTION}} to your state record

In a PeopleCode step, set the value of {{AE_APPLID}} to the application engine program name that you are calling. If it is a section in the same application engine program, you can leave this blank and it will default to the current running application engine program

In a PeopleCode step, set the value of {{AE_SECTION}} to the section of the application engine program you are calling

Set the dynamic flag check box on the call section step

For a good delivered example, look at the Data Archive application engine program, ARCH_PROCESS. The relevant parts are:

ARCH_PROCESS.MAIN.Step001b

ARCH_PROCESS.MAIN.Step003b

The data archive process application engine can dynamically call application engine programs specified by the user in the data archive configuration template.

Migrating in a Project

One of the problems with application engines is getting all the relevant parts of the application engine into a project.

I've found the following to be the best approach (repeat for each program):

Develop away until you have the application design in place. Don't worry about putting it all into a project at this point. The reason is that you will make mistakes and remove/add/update sections, SQL, PeopleCode etc. Obviously you should have a project that you are doing all this in, just don't worry about getting everything related to the application engine(s) into this project at this point.

When you're satisfied with the final design, do a validate project on your working project. This will clear out all invalid definitions that may have been placed in the project over the time you were working out the design. To do this in application designer, select Tools -> Validate Project.

In application designer select Insert -> Definitions into Project or press CTRL + F7. Select the Application Engine Programs definition type, find your application engine program and select all the related definitions. Press insert. Now check in the upgrade tab to verify that the program, sections, PeopleCode, SQL, records and XSLT are all shown in the upgrade tab.

Make sure that the action flag is set to copy for all relevant definitions and that the upgrade flags are checked.

Migrate your app engine to another environment and confirm everything was copied over and works.

Retain Temp Table Data

If you've ever worked on a complicated app engine program that uses temp tables, then you'll know how useful it can be to retain the temp table data for analysis. Unfortunately, by design app engine programs truncate the temp table instance they are going to use at the start and end of the program when they finish successfully. However, just because an app engine runs successfully does not mean it did what was expected!

In these situations, there is a way to keep this data. I call it a FOP step (short for Fail On Purpose). Basically, it involves a step with a SQL action added at the very end of an application engine program that deliberately fails. This stops the app engine program from performing the final truncate of temp tables, allowing you to view the data in them.

Here's a screenshot of the step and action:

Hopefully the table FOP! doesn't exist in your database so this will throw an error. The selects are the useful part. In this format, they will display the instances of the temp tables being used in your .stdout file.

Basically, something that looks like this:

SELECT PS_ATEMP_TBL4, PS_BTEMP_TBL2, PS_CTEMP_TBL1 FROM FOP!

Which tells you exactly which tables to go searching for your data.

For this to work, make you add the FOP as the very last step in your application engine program.

Also, I'd suggest adding a step like this and making it inactive if you are developing a new app engine program that uses temp tables. That way, when debugging is required, it can be made active. Of course, doing all of the above will cause your app engine to go to No Success in the process monitor (which is what we expect), and if restart is enabled, you will need to restart the abended instance (and not start a new one).

Keep in mind that the temporary tables may be cleared when you re-run or restart the application engine. So be careful if you want to keep data between runs.State Records

This article goes through a basic example of how to populate data in an application state record. State records are used in Application Engine programs to keep track of useful information through the life of a program. PeopleSoft uses the concept of a record (table) to store this information. The scope of data in a state record is global to an application engine program (and other programs that share the state record).

The naming convention of state records is to end with the suffix _AET.

They can either be a derived/work record or a SQL table. The difference is one of persistence. A derived/work state record will lose its value when the application engine is restarted or after database commits, while a table will not as state data is committed to the database. So if you are developing a restartable application engine program, the state record should be a table (and built in the database). Since Derived/work state records can also lose information between commits in your application engine, its safest to use a SQL table as the default type for your state records.

Creating the State Record

All state records must have at least one field PROCESS_INSTANCE as their first field. This is also the only key field. Other commonly used fields are OPRID and RUN_CNTL_ID. This lets you track who is running the application engine program and what run control ID they are using.

Additional state record fields that are common to include are AE_APPLID and AE_SECTION. These are required on Application Engine Programs which have a dynamic Call Section Actions, as the values in these fields will control what Application Engine Step is called next — either in the current program or something outside.

All other fields are a matter of your requirements; what information do you need to track through the execution of your program?

 Remember the naming convention: state records end with the suffix _AET.

Assigning the State Record to your App Engine

Once you've created the state record, you need to assign it to your application engine program. You do this through the application engine properties in the state records tab.

Use the search to find your state record and then add it.

 NOTE: if you only have one state record it will be the default. 

If you have more than one, you should nominate one as the default. You can supposedly have up to 200 state records associated with one application engine program, but I'm not sure I would like to see a program that does!

Adding a SQL action to populate the State Record

I generally have an INIT step at the start of an application engine program that populates state records. This includes a SQL action that populates the state record.

Here's a basic example assuming a state record with the fields:

PROCESS_INSTANCE (key)

OPRID

RUN_CNTL_ID

%Select(OPRID, RUN_CNTL_ID) 

 SELECT OPRID 

 , RUN_CNTL_ID 

 FROM PS_AE_REQUEST 

 WHERE PROCESS_INSTANCE = %Bind(PROCESS_INSTANCE)

Notice that you don't need to select in the PROCESS_INSTANCE field. It is automatically populated and available for use as a bind, which is how we get the operator ID and run control ID.Tracing and Debugging

You can use the -TRACE option to trace the SQL executed by an application engine program. This can be added either through the command line debugger or in the override parameters of the process definition.

To trace the PeopleCode executed by an application engine program use the -TOOLSTRACEPC option.

These are the various tracing options and what they do. Like all other PeopleSoft trace flags these are bit fields so if you want trace values 1, 2 and 4, you would set the trace to 1 + 2 + 4 = 7 (-TRACE 7).

Value

 Trace Setting

 

0

 Disables tracing.

 

1

 Initiates the Application Engine step trace.

 

2

 Initiates the Application Engine SQL trace.

 

4

 Initiates the trace for dedicated temporary table allocation to an Application Engine trace (AET) file. You can trace how the system allocates, locks, and releases temporary tables during program runs.

 

128

 Initiates the statement timings trace to a file, which is similar to the COBOL timings trace to a file.

 

256

 Initiates the PeopleCode detail to the file for the timings trace.

 

1024

 Initiates the statement timings trace, but stores the results in the PS_BAT_TIMINGS_LOG and PS_BAT_TIMINGS_DTL tables.

 

2048

 Requests a database optimizer trace file.

 

4096

 Requests a database optimizer to be inserted in the Explain Plan table of the current database.

 

8192

 Sets a trace for PeopleSoft Integration Broker transform programs.

 

Note that output from the -TRACE flag goes to the application engine trace (.AET) file. Output from the -TOOLSTRACEPC output goes to the PeopleTools trace file (.TRC).

To run application engine in debug mode, run the following from the command line of %PS_HOME%/bin/client/winx86.

psae.exe -CT DatabaseType -CD DatabaseInstance -CO OperatorID -CP OperatorPassword 

-R RunControl -I ProcessInstance -AI ApplicationEngineProgramName -DEBUG Y

You may need to install peopletools locally first.

The app engine will log into the database and present you with the following prompt:

PeopleTools 8.48.12 - Application Engine

Copyright (c) 1988-2007 PeopleSoft, Inc.

All Rights Reserved

Application Engine Debugger - enter command or type ? for help.

{APPENGINENAME}.{SECTION}.{FIRST_STEP}>

If you get an error about the environment variable PS_SERVER_CFG not being set, you will need to set up the following environment variables:

PS_SERVDIR pointing to your process scheduler location (e.g. %PS_HOME%\appserv\prcs\CS90)

PS_SERVER_CFG pointing to your process scheduler configuration file (e.g. %PS_SERVDIR%\psprcs.cfg)

You can view the current values in the state record, step into code - which will take you into app designer if it is a PeopleCode step. But the best feature is that it allows you to modify the contents of a state record.

Note that the following commands are available in the debugger:

Debug Commands:

 (Q)uit Rollback work and end program

 E(X)it Commit work and end program (valid between steps)

 (C)ommit 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