Application Engine

Exercise #2: Using a State Record to Accept User Input

In this exercise, you will modify the AppEngine program you created in Exercise #1 that
increases the hourly pay rate for the employees in your department. The percentage
used to increase the hourly pay rate will be accepted from the user.
Table name: PS_GBUT_AETRN1_TBL
Field name: AMT
Web navigation: Tool Training > AE Training > AE Objects > Employees
To open an existing project:
1. Click on File, Open or click on

2. In the Open Object window first choose an Object Type of Project, then either
a. Type the entire name of the project in the Name box and click on Open,
or
b. Type a partial name in the Name box and press ENTER to get a list to
choose from. Then either double-click the project you want to open or
click on it once to highlight and click on Open.

Page 1 of 18

Your project should be named

GBUT_TRNTECHxx

Note: If you need to create a new project, please refer to Exercise #1.
Now that you have opened your project, you are ready to modify the AppEngine
program created in Exercise #1 to accept input from the user.
In order to accept runtime parameters from the user a state record is required. The
state record will be used to pass variable information from the process scheduler run
control record and your AppEngine program as well as passing the variable information
between steps in your AppEngine program.
The first thing you should do is create the state record to be used in this exercise.
1. Click on File, New or click on

2. Click on Record and then click OK

3. The key field (and the only key field) for a state record should be the field called
PROCESS_INSTANCE (do not use the field PROCESSINSTANCE). To
insert the field into your record, on the menu bar click on Insert, then on Field
4. Type the entire name of the field in the Name box and click on Insert, or

Page 2 of 18

type a partial name in the Name box and press ENTER to get a list to choose
from. Then either double-click the field you want to insert or click on it once to
highlight and click on Insert.

5. Now your record has one field in itPROCESS_INSTANCE.

Page 3 of 18

You will also need a field on your state record in which to store the percentage
value input by the user. You can create a new field for this purpose or use an
existing field that is the correct type and size for your needs. Use the field
GBUT_PCT_INCREASE, which already exists in the LSTRA database.
6. Insert the field GBUT_PCT_INCREASE into your state record. Follow the steps
outlined in Steps 3 and 4 above.
7. Add the field COUNTER to your state record definition.
Your state record should now look like this:

8. Now you need to save your state record definition. Click on File, Save As or
Click on
. Type a name for your state record (please follow established
naming conventions explained in UNTSP Standards document found in the
Shared Documents section of the EIS Developer Forum website), and then click
on OK (or press ENTER). For this exercise use, GBUT_xx_AET. When
prompted, use UNTUSER for the Space Name.

GBUT_00_AET

Page 4 of 18

9. You must build the record since this will be a physical SQL table. With the
record definition open on the screen, click on Build, then on Current Object.
10. Verify that the boxes for Create Tables is checked and the radio button for
Execute and build script is selected, then click on the button labeled Build.
11. Once the build process has completed, verify that you received no errors and no
warnings in the Build messages window at the bottom of the screen. It should
look something like this:

Now you are ready to open the program you created in Exercise #1 so that it can be
modified to accept the percent increase from the user (inserted into the state record by
the Process Scheduler when the program is executed) rather than using a hard-coded
value of 10%.
1. Click on File, Open or click on
2. In the Open Object window first choose an Object Type of App Engine
Program, then either
a. Type the entire name of the project in the Name box and click on Open,
or
b. Type a partial name in the Name box and press ENTER to get a list to
choose from. Then either double-click the project you want to open or
click on it once to highlight and click on Open.

Your program name should

be GBUT_xx_EX1

Page 5 of 18

3. You should now see the program you created in Exercise #1.

4. To see all the Sections, Steps, and Actions

c. Click on the View (on the menu bar) and then click Expand All or
d. Press CNTL-SHIFT-X or
e. Click on the Expand All button on the toolbar

Page 6 of 18

Now the program should be displayed as shown:

5. Now save this AppEngine program with a new unique name. Click on File, Save
As. Type a unique name for your program (please follow established naming
conventions explained in UNTSP Standards document found in the Shared
Documents section of the EIS Developer Forum website), and then click on OK
(or press ENTER).

Save As using the program

name GBUT_xx_EX2.

6. Since you cloned this program (GBUT_xx_EX2) from an existing program

(GBUT_xx_EX1) that already had the Disable Restart box checked, you will not
need to change the Program Properties at this time. For information on Disable
Restart, please refer to Exercise #1.
7. You need to make three changes to the AppEngine program you just cloned.
a. Modify the SQL to accept the percentage used from the state record.

Page 7 of 18

b. Change the Log Message used so that the message will contain the percentage
accepted from the user.
c. Link the program to the new state record you have created.
8. Double-click in the area to the left of the SQL Action to open the SQL Editor.

Double-click in this area

to open the SQL Editor

9. The SQL currently looks something like this:

UPDATE PS_GBUT_AETRN1_TBL
SET AMT = AMT + (AMT * 10/100)
WHERE DEPARTMENT = 'TRNTECHxx'

This command will increase hourly pay rate (AMT) by 10% for your department.
10. To modify the SQL to use the percent increase entered by the user, change the
code highlighted in bold above so that the SQL looks something like this:
UPDATE PS_GBUT_AETRN1_TBL
SET AMT = AMT + (AMT * (%Bind(GBUT_PCT_INCREASE)/100))
WHERE DEPARTMENT = 'TRNTECHxx'

11. Click on
to check the syntax of the SQL statement. Important note this will
not validate that your SQL is correct (i.e., correct table name, correct field names,
etc). It will basically reformat your SQL the way it wants it to look. Misspelling
names or misplaced commas or parentheses will cause runtime errors.

Page 8 of 18

12. Close the SQL editor window.

13. Now change the Log Message that will be written out when the program
successfully completes. Use Message Set 20101, Number 2. This message
expects two parameters to be passed from the AppEngine program so enter the
following in the Parameters: box:
%AEProgram, %Bind(GBUT_PCT_INCREASE)
This will pass the name of the AppEngine program (%AEProgram is a system
variable) as the first parameter of the message and the value in
GBUT_PCT_INCREASE in the second parameter of the message.
14. Save your program again.
15. The last modification necessary is to link the state record you created to the
AppEngine program. This is done in the Program Properties.
Open the AppEngine Program Properties window:
or
a. Click on
b. Click on File, Object properties or
c. Press ALT-ENTER on your keyboard
16. Click on the State Records tab. In the box labeled Qualify Search, you can
type a partial name or the full name of your state record and click on the button
labeled Get List. DO NOT PRESS ENTERthat will close the Program
Properties window.
17. Click once on your state record to highlight it and click on the button labeled
Add. You will now see your state record listed in the Selected window on the
right. It is automatically selected as the default state record because it is the
only one you are using. If you were using more than one state record with your
AppEngine program, you would continue to add then using the same process just
described.
During batch processing (as opposed to online invocation using CallAppEngine in
PeopleCode), Application Engine automatically performs all State Record
UPDATEs. When a program starts, it INSERTS a row into the State Record that
corresponds to the Process Instance assigned to that program run. Application
Engine updates the record whenever a COMMIT occurs. When Restart is enabled
and a commit occurs, all State Records that have been updated in memory will be
written to the database, except for derived State Records, which are instead
initialized. Then, after the program completes successfully, Application Engine
deletes the corresponding row in the State Record. There is only one row in the
State Record for each Process Instance, or program. Multiple programs can use
the same State Record, and each program has it's own row based on the unique
Process Instance key.
Page 9 of 18

To set values in the State Record, you use the %SELECT construct in a SQL
statement or write PeopleCode that references the State Field with the standard
"record.field" notation. To reference fields in the State Record you use the
%BIND construct.
Now, you are almost ready to test your AppEngine program! In order to run an
AppEngine program, you must first create a custom Run Control Page that will accept
input from the user and a Component to contain the page, add the Component to a
Menu, and set Security for the Component.
Your custom Run Control Page will require a custom Run Control Records. You can
clone the generic Run Control Record delivered from PeopleSoft as a starting point.
1. Open the Record PRCSRUNCNTL by either
a. Click on File, Open or by clicking on
The record will look like this:

The fields OPRID and RUN_CNTL_ID are the record key fields. The
LANGUAGE_CD and LANGUAGE_OPTION fields are used in global
development projects and are not necessary in our application.
2. First, save this record with a new, unique name. Click on File, Save As. Type a
unique name for your program (please follow established naming conventions

Page 10 of 18

explained in UNTSP Standards document found in the Shared Documents

section of the EIS Developer Forum website), and then click on OK (or press
ENTER).

Save As using
GBUT_xx_RNCTL

3. When prompted with the question Do you wish to also save a copy of the
PeopleCode associated with PRCSRUNCNTL.ENG?, click on Yes.
4. Since we have no need for the LANGUAGE_CD and LANGUAGE_OPTION
fields, delete those fields. One method for deleting the fields is to right-click on
the field and then click on Delete. Once the two fields have been deleted, save
your record again.
5. Now you need to add the field for which you will be accepting a parameter from
the user. This field is GBUT_PCT_INCREASE. Add this field to the record as
described previously in this document (see hyperlink Inserting a Field into a
Record).
6. Save your custom run control record again. Then build the SQL table as
described above (see hyperlink Building a Record).
Likewise, even though you will need to modify it to accept additional parameters and to
use the custom run control record you just created, you can still clone the generic Run
Control Page delivered from PeopleSoft as a starting point.
7. Open the Page PRCSRUNCNTL by either
a. Click on File, Open or by clicking on

Page 11 of 18

The Page will look like this:

8. The first thing you should do is save the page with a unique name. Click on File,
Save As to save the Page under a different name (please follow established
naming conventions explained in UNTSP Standards document found in the
Shared Documents section of the EIS Developer Forum website).

Save As using page name of

GBUT_xx_RNCTL

9. When prompted with the question Do you wish to also save a copy of the
PeopleCode associated with PRCSRUNCNTL.ENG?, click on Yes.

Page 12 of 18

10. Next, you need to add the custom field to the page. The easiest way to
accomplish that is to double-click on GB_xx_RNCTL from the project workspace
window so that you can see the individual fields on the record. Then drag-anddrop GBUT_PCT_INCREASE on to the run control page.

11. Save your page again.

To create a Component for your new custom Run Control Page:
1. Click on File, New or click on
2. Click on Component, then click on OK

Page 13 of 18

3. Expand the list of Pages in your project by clicking on the plus sign next to Pages
in the Project workspace.
4. Drag and drop the custom Run Control Page you created onto the Component.

Drag and drop in the Object workspace

5. Before the Component can be saved, a search record must be specified. Click on
to open the Properties window and click on the Use tab. Since you have
created a custom run control record, you should select it (GBUT_xx_RNCTL) as
the search record, and then click on OK.
6. Click on File, Save or click on

7. Type a name for the Component (please follow established naming conventions
explained in UNTSP Standards document found in the Shared Documents
section of the EIS Developer Forum website) and click on OK. For this exercise,
use the name GBUT_xx_EX2.
The instructor will add your component to the menu and grant you
security when youve told them that you are ready.

Page 14 of 18

One more important thing must be done before you can test your program. When you
use a custom run control page, the Process Scheduler will NOT automatically populate
your state record with the value input by the user. You must add the step to do that to
your AppEngine program.
1. Insert a Step/Action before the Step01. The new Step will automatically be
numbered Step03, but the numbering does NOT imply execution order. The
steps will execute in the order they are shown on the screen. So that the order
will make more sense, rename the steps so that they reflect the action being
performed in the Step. Your program should look something like this:

2. The new SQL Action you inserted should contain the following SQL:
%Select(GBUT_PCT_INCREASE)
SELECT GBUT_PCT_INCREASE
FROM PS_GBUT_00_RNCTL
WHERE OPRID = %OperatorId
AND RUN_CNTL_ID = %RunControl

The first command (%Select (GBUT_PCT_INCREASE) populates your state

record with the value retrieved in the SELECT statement following it. The second
line (the SELECT command) retrieves the value of GBUT_PCT_INCREASE from
your custom run control record.
3. Save your AppEngine program again.

Page 15 of 18

The last step before you can run the AppEngine program youve created is to create a
Process Definition for the PeopleSoft Process Scheduler. This step must be completed
whether you are running the AppEngine program two-tier, three-tier, or n-tier.
To create a Process Definition:
1. On the web, navigate to PeopleTools > Process Scheduler Manager > Use >
Process Definitions
2. Click on the hyperlink Add a New Value
and then click on Lookup
3. Click on the lookup icon
4. Click on the hyperlink Application Engine
5. Type in the Process Name This must match your AppEngine program
name!
6. Click on Add
7. Click on the Process Definition Options tab
8. In the Component section of the form, click on the Lookup icon and select your
Component (this will be the Component that contains your Run Control Page)
9. In the Process Groups section of the form, click on the Lookup icon and select the
permission list used with this AppEngine program (in this exercise use
ALLPANLS)
Click on Save
Believe it or not, you are finally ready to run your AppEngine program!
First, check the course contact hours on a few courses in the subject area the program is
set to modify (in this exercise, the SQL references the subject area ACCT). This can be
accomplished either by accessing the records through the web navigation listed at the
top of this document or by writing a simple query through Query Manager.
To execute your AppEngine program via the web:
1. Navigate to the Menu Item you added Tools Training > AE Training >
TRNTECHxx > Input Pay Rate Increase. The Run Control Search Page will be
displayed.
2. If you have an existing Run Control ID you want to use, you can type the name
(or partial name) and click on Find. If you want to add a new one, click on the
hyperlink Add a New Value then type a value for the Run Control ID and click
on Add. This can be any value you wishit does not need to match the
AppEngine program name and can be reused.
3. When the Run Control Page is displayed, click on Run.

Page 16 of 18

Then click here to run AE program

Type in the percent to
increase course contact
hours by here

Page 17 of 18

4. A page containing a list of all Process Definitions linked to this Component (via
Security) is displayed. Since the Process Definition name must match your
AppEngine program name, this provides the link that PeopleSoft will need to
know which program to run. Click on OK to submit the Process Scheduler
Request.
5. The display will return to the Run Control Page and display your Process
Instance. You can now click on the hyperlink Process Monitor to view the
progress of your program execution. For more information on the Process
Monitor, please see Exercise #1.
6. Verify that the message written to the message log contains the value you input
for GBUT_PCT_INCREASE.
7. Lastly, you should verify that your program did what it was supposed to by
checking that the hourly pay rates of the employees in your department increased
by the percentage you input.

Page 18 of 18