-
Page 1 of 18
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 2 of 18
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
Your project should be named GBUT_TRNTECHxx
-
Page 3 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 4 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 5 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 6 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 7 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).
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.
Save As using the program name GBUT_xx_EX2.
-
Page 8 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.
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.
Double-click in this area to open the SQL Editor
-
Page 9 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:
a. Click on or 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 10 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 11 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).
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
Save As using GBUT_xx_RNCTL
-
Page 12 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).
9. When prompted with the question Do you wish to also save a
copy of the PeopleCode associated with PRCSRUNCNTL.ENG?, click on
Yes.
Save As using page name of GBUT_xx_RNCTL
-
Page 13 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-and-drop
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 14 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.
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.
Drag and drop in the Object workspace
-
Page 15 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 16 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
3. Click on the lookup icon and then click on Lookup 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 17 of 18
Then click here to run AE program
Type in the percent to increase course contact hours by here
-
Page 18 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.
Exercise #2: Using a State Record to Accept User Input