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, component interfaces,
XML publisher reports, and call SQRs and COBOLs through PeopleCode.
Program Structure
Program Properties
State Records
Logging to the Message Log
Call Sections
Migrating in a Project

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 more 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:
1. Add the fields AE_APPLID and AE_SECTION to your state record
2. 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
3. In a PeopleCode step, set the value of AE_SECTION to the section of the
application engine program you are calling
4. 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.

Populating a State Record

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. I believe the scope of data in a state record is global to an
application engine program (and other programs that share the state record), however this
could be wrong.
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.
The following steps are involved in populating a state record in an application engine
program:

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

Assign 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 …

Add a SQL action that populates 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
● OPRID
● RUN_CNTL_ID
%Select(OPRID, RUN_CNTL_ID)
SELECT OPRID
, RUN_CNTL_ID
FROM PS_AE_REQUEST
WHERE PROCESS_INSTANCE = %Bind(PROCESS_INSTANCE)
Note 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.

Process Scheduler
This wiki page is dedicated to the PeopleSoft process scheduler - the server process(es)
that are responsible for running and managing batch processes including SQR,
Application Engine, Crystal Reports and Winword.
Processes stuck at Queued
Run status
Suppressing files from the Report Repository
Application Engine programs only stuck at queued
Active Processes
Summary of requested processes by process status
Distribution

Processes stuck at Queued

There are a number of reasons why a process might be stuck at queued. The most obvious
is that the process scheduler is down (check the Servers tab in the process monitor).
Beyond this, there are some useful troubleshooting that apply:
Check the following tables:
● PSPRCSRQST
● PSPRCSQUE
● PSPRCSPARMS
The row count should be the same in both tables. If one is out of sync with the other, then
it can help to remove orphaned instances in of the tables. Restarting the process scheduler
and clearing the process scheduler cache will also fix a number of issues.

Run status
In the PeopleTools 8.4x look at the translates on the field RUNSTATUS or use the query.
select FIELDVALUE, XLATLONGNAME
from PSXLATITEM
where FIELDNAME = 'RUNSTATUS'
Here's a summary of the run status translates (from PeopleTools 8.49). Note that not all
of these are active.
Value Status
1 Cancel
2 Delete
3 Error
4 Hold
5 Queued
6 Initiated
7 Processing
8 Cancelled
9 Success
10 Not Successful
11 Posted
12 Unable to Post
13 resend
14 Posting
15 Content Generated
16 Pending
17 Success with Warning
18 Blocked
19 Restart
The following query will give you a summary of the process run statuses in your process
request table:
select
RUNSTATUS,
(
select XLATSHORTNAME
from PSXLATITEM
where FIELDNAME = 'RUNSTATUS'
and FIELDVALUE = RUNSTATUS
) as RUNSTATUS_DESCR,
count(PRCSINSTANCE)
from
 PSPRCSRQST
group by
RUNSTATUS
order by
RUNSTATUS;

Suppressing files from the Report Repository

I once wrote an application engine to extract photographs from the PeopleSoft database
(BLOBs) and to put the photos into a common location on the application server. This
was an application engine program. However, the only problem was that the photos being
outputted (in .jpg format) were also going to the report repository. This was a hard one to
pick up as the .JPG extension had never been configured in the Process Scheduler system
settings under distribution file options.
PeopleTools > Process Scheduler > Process Scheduler > System Settings >
Distribution File Options
This meant that to the end user, the links were never created to the files on the report
repository but they were indeed going there. It was only when the application engine
batch processed a lot of photos and the report repository came to a grinding halt that this
became apparent.
The fix required suppresing output to the report repository. Here's how:
PeopleTools > Process Scheduler > Processes > [Your Process Name] >
Destination
On the destination page, change the output destination options from the default to:
● Type = File
● Format = Other (or select appropriate file format if available)
● Destination Source = User Specified
Not sure if the destination source has any impact. User specified is apparently the default
(PeopleSoft Process Scheduler PeopleBooks) and means that the output destination is
determined by the process run control designation. SQRs apparently must use this as their
setting and I believe any application engine programs that output files.

Application Engine programs only stuck at queued

You may find that only application engine programs are stuck at queued while other
processes (SQRs, crystals etc) run to success. This typically happens due to processes
blocking the process scheduler queue. Check the process scheduler/master process
scheduler logs. You might see something like this:
Checking Process cancels...
(NET.113): Client ChkAeStatus3 service request succeeded
Process 2319373 is still running as Session ID 19955
(NET.113): Client ChkAeStatus1 service request succeeded
Process 2319395 is still running as Session ID 19946
(NET.113): Client ChkAeStatus2 service request succeeded
Process 2319404 is still running as Session ID 19950
Application Engine : 3:3
Requests found in Process Request table 3
This indicates that the three process instances, 2319373, 2319395 and 2319404 are all
running. As there is a maximum of 3 application engine programs that can run at any one
time and there are currently 3 running, all other application engine programs requested
will remained at queued. However, the three process instances may not actually be
running. If this is the case, these will need to be manually stopped, for example with a
process scheduler restart and perhaps by manually killing the processes on the process
scheduler server if required.

Active Processes
Ever wondered where the active processes value on the server list tab comes from? Well
it actually uses a view - PS_PMN_PRCSACTV_VW. This view uses the underlying records
PS_SERVERMONITOR and PS_SERVERCLASS. It is the ITEMCOUNT field from
PS_SERVERMONITOR that gives you the active processes count by process type (SQR,
COBOL, Application engine etc).

Summary of requested processes by process status

The following query will give you a summary of the requested processes by process
status.
select
RQST.RUNSTATUS,
RQST.PRCSTYPE,
(
select XLAT.XLATLONGNAME
from PSXLATITEM XLAT
where XLAT.EFFDT = (
select max(XLAT_ED.EFFDT)
from PSXLATITEM XLAT_ED
where XLAT_ED.FIELDNAME = XLAT.FIELDNAME
and XLAT_ED.FIELDVALUE = XLAT.FIELDVALUE
) and XLAT.FIELDNAME = 'RUNSTATUS'
and XLAT.FIELDVALUE = RQST.RUNSTATUS
) as RUNSTATUS_XLAT,
count(RQST.PRCSINSTANCE) as TOTAL_PROCESSES,
min(RUNDTTM) as FIRST_OCCURRED,
max(RUNDTTM) as LAST_OCCURRED
from PSPRCSRQST RQST
group by RQST.RUNSTATUS, RQST.PRCSTYPE
order by RUNSTATUS_XLAT, RQST.PRCSTYPE

Distribution
The following tables store information about the distribution of process scheduler output
to users or roles.
PS_PRCSDEFNCNTDIST
Distribution settings for process definitions.
PS_PRCSJOBCNTDIST
Distribution settings for jobs.
PS_PRCSRQSTDIST
Distribution settings by process instance. Join to PS_CDM_FILE_LIST on the process
instance to get the file names.
PS_PRCSRUNCNTLDIST
Distribution by operator ID and run control.