Creating Application Engine Programs

An Application Engine program includes a logically ordered set of sections, steps, and actions. An executable program must contain at least one section, called MAIN, used to identify the starting point of the program. Also, it should contain at least one step, and each step should contain at least one action.

This chapter discusses how to:

• View Application Engine programs.

• Filter view contents.

• Print program and flow definitions.

• Create, open, and rename programs.

• Copy or move program elements.

• Test Application Engine programs.

• Set program properties.

• Add sections.

• Add steps.

• Specify actions.

Viewing Application Engine Programs

This section discusses how to:

• Use Definition view.

• Use Program Flow view.

• Switch between Definition and Program Flow views.

• Use the Refresh option.

Using Definition View

You use Definition view to create definitions within a defined hierarchical structure, in which nodes represent the definitions. A node is the visual representation of a section, step, or action that you can select, collapse, modify, and so on.

The sections that appear in Definition view do not necessarily appear in the order that they execute. To see the actual order in which the sections execute, switch to Program Flow view.

In addition to using a mouse, you can navigate in this view using the following keyboard combinations:

• Press Ctrl+Home to scroll to the top of the program definition and select the first node.

• Press Ctrl+End to scroll to the end of the program definition and select the last visible node.

• Press Tab to move from the currently selected field to the next updateable field.

• Press Ctrl+Down Arrow to move from the currently selected node to the next node.

• Press Ctrl+Up Arrow to move from the currently selected node to the previous node.

The following example shows the Definition view:

Definition View Pop-up Menu

The following table describes each item you see when you right-click a Definition view window. Certain menu items are enabled only when a particular definition is selected.

Using Program Flow View

Program Flow view is a read-only view that shows the expected sequence of steps to execute for the program you are developing. The following example shows the Program Flow view:

You can control the amount of detail that appears for each definition by clicking it to expand to the next level. You also can view the SQL or PeopleCode in the lower (splitter) window area by clicking the lower window.

If a primary step node (one that is not the result of a section call) is selected, the Print Options dialog box permits printing to begin either at that step node or the entire program prints. However, if a secondary step node (one that is the result of a section call), a secondary action node, a call section action node, a SQL node, or a PeopleCode node is selected in the Program Flow view, then the Print Options dialog box only permits the entire program to be printed.

To display the pop-up menu for a node, right-click the node. You do not have to select the node first.

You also can display the comments associated with definitions by selecting View, Show All Comments or, for a particular node, right-click and select Show Comment.

You can double-click SQL or PeopleCode statements to launch the editors.

Program Flow Pop-up Menu

The following table describes each pop-up menu item in the Program Flow view:

Switching Between Definition and Program Flow Views

By default, navigation within either view does not affect the currently active row in the other view. This functionality enables you to retain your place in one view while scrolling through the other.

To switch between the two views, use any of the following methods:

• View tabs

  As with any tabbed interface, if you select a tab, the associated view interface becomes active. When you return to the previous view, it remains positioned on the current or last selected node within the program when you switched. This positioning is true whether you selected the item or just placed the cursor within an edit box.

• View menu

  Select a section or step in the current view (note that selecting an action does not enable this functionality; you can jump only from parent nodes). Then select View, Jump to Program Flow or View, Jump to Definition, depending on the currently active view. When you select one of these commands, the focus of the target view depends on what you selected in the previous view. For example, if you selected Section C, Step 4 in Definition view and you select View, Jump to Program Flow, then Section C, Step 4 is the focus of the Program Flow window. If the selected item is in a program that is not open already, then Application Engine opens the appropriate program and navigates to the requested node in the view window.

• Pop-up menu

  The same commands as the View menu are also available from the pop-up menu.

Switching Within Program Flow View

While you are in Program Flow view, you can select these options from the pop-up menu:

• Go to Next Reference

  Select to switch to the next reference of a particular definition object. This option helps you navigate quickly through a program. For instance, if references to Section C, Step 4 appear three times because of multiple calls to this object at runtime, then you can select Go to Next Reference to navigate quickly and easily to each reference or call.

• Jump to this Definition

  Select to go directly to the definition node in the Definition view that pertains to the current selection in the Program Flow view.

Using the Refresh Option

As you develop an Application Engine program, you may be inserting, renaming, and deleting definitions. In a large program, you can easily lose your place or become disoriented. The Refresh option reorders all the nodes for the current definition according to the following logic:

• For standard program definitions, the MAIN section always appears first (Library program types do not contain a MAIN section because they contain only callable sections).

  The remaining sections appear alphabetically by name, which makes it easy to locate a section within the program definition. At runtime, the system runs sections through Call Section actions within steps, not by the order in which the sections are defined.

• Steps are never automatically reordered in the Definition view; at runtime, they run in the sequence in which you defined them.

• Actions are always logically reordered within a step based on their action type, which defines their runtime sequence.

Note. When you save a modified definition, the system automatically refreshes the view.

Application Engine inserts any delete requests for a given section into the current project, regardless of the Tools, Options setting in Application Designer.

For example, suppose you delete a section node from the current Application Engine program and then you reinsert a section node and rename it the same name as the section you just deleted. The section object is not inserted into the project, regardless of your Tools, Options setting, because a delete action already exists for this object. To resolve this situation, either remove the delete request manually before inserting the new copy request or reset the proper flags manually in the upgrade project that changes the action type from Delete to Copy.

Filtering View Contents

Section filtering options enable you to filter the current view so that you see only sections and steps based on specified criteria.

To enable or modify the filtering options, select View, Section Filtering. You can select from the filtering options described in this table:

Behavior of Section Filtering Options

When using the section filtering options, keep in mind that:

• The default is No Filtering; therefore, all section definitions are included in this view.

• If you select Custom filtering, the default filtering options appear while you are in the current session of Application Designer.

  If you modify these filtering options and click OK, the new options are stored as the currently active options and the view is updated accordingly.

• If you select the Default filter option, the original default options appear in the dialog box.

  After clicking OK, the view reappears with only those sections that qualify. However, if you change the default options and do not click OK, then these options are stored as a custom filtering request and the view reappears as necessary.

• If no platform-specific section is defined for the target filter value, then the default (base platform) is always included because it represents the Application Engine runtime behavior more accurately.

If you select Section Filtering, Default, or Section Filtering, Custom, then the following dialog box appears:

In this example, only definitions that represent the following criteria appear in the Definition and Program Flow views.

Note. All filtering options pertain only to section-level nodes.

Printing Program and Flow Definitions

You can print the program definition or program flow, depending on which view you are in when you select Print.

To print an Application Engine program definition:

1. Right-click and select Print in either the Program Flow or Definition view or select File, Print.

2. Select print options.

   Program ID	Select to print the whole program.
   All Sections	Select for all sections to be expanded in the printed report but only for the primary Application Engine program that is being printed and only if that program is an application library. Otherwise, only the MAIN section, first section, or called section is printed.
   All Steps	Select to print all the steps in the section.
   All Attributes	Select to print all detail level attributes for the specified node and its children.
   SQL Statements	Select to print, for every SQL type action, the text of each SQL statement.
   PeopleCode Statements	Select to print the text of the PeopleCode statements for every PeopleCode action.
   Comments	Select to print the long description comments for the selected node and its children.
   Include External Calls	Select to print the section detail of all external calls.
   Max No. of Levels (maximum number of levels)	Specify the maximum number of recursive levels to print for the specified call sections, including both external section calls and internal section calls. This edit box is always enabled. You can only set the maximum number of levels to a value greater than or equal to 1.

Creating, Opening, and Renaming Programs

This section discusses how to:

• Create new programs.

• Open existing programs.

• Rename programs.

Creating New Programs

To create a new program definition:

1. Select File, New or press Ctrl + N.

2. In the New dialog box, select App Engine Program from the Definition Type drop-down list and click OK.

3. Save and name your program.

   Select File, Save As, enter the name of your program in the Save Name As edit box, and click OK.

Note. You should also provide a program description and specify its owner in the properties dialog box for the new program.

See Setting Program Properties.

Opening Existing Programs

To open an existing program:

1. Select File, Open.

2. In the Open Definition dialog box, select App Engine Program from the Definition Type drop-down list.

3. Enter your search criteria for the program you want, select your program in the search results list, and click Open to open the program.

Renaming Programs

To rename a program:

1. Select File, Rename.

2. In the Rename dialog box, make sure that App Engine Program appears as the definition type.

3. In the box that contains your search results, click the program that you want to rename.

4. Click Rename.

5. Place the cursor in the box that appears around the highlighted program name.

6. Enter a new name for the program.

7. Click Rename again and respond appropriately in the Confirm Rename dialog box.

   Note. The system automatically modifies all static references in other programs to the renamed program. For instance, if you call the renamed program from another Application Engine program, the Call Section action in the calling program is modified to reflect the new program name. All sections and steps are saved under the new name. Only one occurrence of a program name can exist for a given database.

   Note. If the renamed program is called in a dynamic Do action, then the reference is not modified automatically. You should manually check and modify any embedded references to the new program name in CallAppEngine or other PeopleCode functions.

Copying or Moving Program Elements

The following procedures apply to sections, steps, and actions. Note that when these functions are performed for a given object, the result applies not only to the selected object but also includes its defined children, if they exist. Also note that all references to menu items apply not only to the main menu bar items but also to their related items in the context menu, as applicable.

To copy a definition:

1. Select a definition.

2. Select Edit, Copy.

3. Position the cursor where you want to put the copied definition and select Edit, Paste.

To move a definition:

1. Select a definition object.

2. Select Edit, Cut.

3. Position the cursor at the target location and select Edit, Paste.

Testing Application Engine Programs

After creating or modifying your program, you can test it in two-tier mode while in Application Designer. You use the Run Request dialog box:

To run an Application Engine program in two-tier mode:

1. Select Edit, Run Program from the Application Designer toolbar.

   The Run Request dialog box appears.

2. Enter appropriate values.

   When you click OK, these values are passed as runtime parameters to the initiated Application Engine runtime executable.

   Run Control ID	Enter the run control ID of the program that you are testing.
   Run Minimized	Select to have the window of the requested process minimized when it is submitted to run.
   Output Log to File	Select to write the output log to a file.
   Log File Name	Specify the log file name (enabled only when the Output Log to File check box is selected).
   Process Instance	Specify the process instance for this run request or use the default value of zero if you do not need an instance number.

3. Click OK.

Setting Program Properties

This section discusses how to:

• Access properties.

• Set general properties.

• Set state record properties.

• Specify temporary tables.

• Set advanced properties.

Accessing Properties

When you have an Application Engine program open in Application Designer, you can view and modify the properties assigned to an entire program just as you would a step or a section.

To view or modify the properties associated with a program, click the Properties button or select File, Definition Properties while the program is open. You can also press Alt+Enter. The Program Properties dialog box appears.

Setting General Properties

Access the Program Properties dialog box and select the General tab. You can specify identification values for your Application Engine program.

Setting State Record Properties

Select the State Records tab.

Qualify Search	Enter any wildcard characters or complete table names to limit the results that appear in the record list. By default, the Record List text box contains all record names that end with the extension AET. This extension identifies the record as an Application Engine record.
Get List	Click to populate the Record List text box.
Record List	This text box contains the results of your state record search.
Selected	Select state records for use with a particular program. Click Add to include selected records from the record list into the selected list. Click Remove to remove selected records from the selected list. Indicate which state record will act as the default state record by selecting its check box. For your default state record, you need to reference only field names in your PeopleCode and SQL (for the active program). When you reference a non-default state record, you do so by using recname.fieldname.

Specifying Temporary Tables

Select the Temp Tables tab.

Temporary tables store intermediate results during a program run.

Note. You must have defined required temporary tables in your database before you can associate them with an Application Engine program.

Note. If the table is keyed by PROCESS_INSTANCE and the application SQL includes the process instance in the Where clause, then multiple processes can share the table. The best performance, however, occurs when a program runs against a dedicated temporary table instance.

See Also

Using Temporary Tables

Setting Advanced Properties

Select the Advanced tab.

Disable Restart	Select to disable the built-in restart capabilities for a particular program.
Application Library	In some cases, you may want a program to contain only a collection, or library, of common routines (in the form of callable sections) that you do not want to run as a standalone program. When sections are defined as public, other programs can call the sections, or routines, 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, or initial entry point. Select this check box to rename or remove any existing MAIN section. Note. An application library is the appropriate location to store a collection of shared Application Engine program sections. Libraries are not intended for storing a specific SQL action within a section. To share common SQL, use the SQL repository.
Batch Only	Select for batch-only programs. Batch-only programs are not run from the CallAppEngine PeopleCode function. Any dedicated temporary table used for batch-only programs does not have online instances created.
Message Set	Specify the default message set value for this program. The system uses this message set value for all Log Message actions for which the message set is not specified.
Program Type	Select from: Standard: Used by standard entry-point programs. Upgrade Only: Used by PeopleSoft upgrade utilities only. Import Only: Used by PeopleSoft import utilities only Daemon Only: Use for daemon type programs. Transform Only: Support for XSLT programs.

Adding Sections

This section provides an overview of sections and discusses how to:

• Insert sections.

• Locate sections.

• Set section properties.

Understanding Sections

A section comprises steps and is similar to a COBOL paragraph or a PeopleCode function. You can create sections that are platform-independent or platform-specific, intended for a particular market, and effective-dated.

Whenever you create a new program, you simultaneously create a section called MAIN. The MAIN section identifies the entry point of the program so that it can be called by another program.

Section Execution Order

A section is unique based on program and section names, and based on its intended database platform and effective date. When you execute an Application Engine program, it executes sections based on the following order of precedence:

1. If a section for the current market exists, then run it.

   Otherwise, execute the default GBL (global) market section.

2. If a section for the current platform, or database exists, execute it.

   Otherwise, execute the default database platform section.

3. If multiple effective-dated sections exist, execute the section with the most recent effective date based on the current (run) date.

For example, suppose you have two versions of a particular section, SECT01 for the Public Sector market and SECT01 for the Global market. If you request to run the public sector version of the program, Application Engine executes the Public Sector version of SECT01. If the program is running on Oracle, Application Engine then looks for an Oracle version of SECT01 for Public Sector.

Inserting Sections

To insert a section:

1. Select Insert, Section, or right-click and select Insert Section.

   The default name for a section that you insert is Section N, where N is an incremental number intended to provide a unique name for each section object. Unless you rename sections, the sections you add are named SectionN+1, where N is the last section you inserted. Consequently, the names are Section1, Section2, Section3, and so on.

   The designer inserts the new section directly beneath the subordinate objects within the owning section of the highlighted object. For instance, if Section2 were selected, then Section4 would be inserted between Section2 and Section3 rather than after Section3.

   Note. Sections are always reordered alphabetically by name when you save to make locating a section easier. However, run order depends on internal call section references and is, therefore, independent of the order in which sections are inserted and displayed.

2. Enter the remaining section property values.

3. Save the program.

Locating Sections

Various methods are available for locating references to sections within an entire database as well as within a program.

Finding Call Section References

You can generate a list of all the references to a particular section. The list applies only to Application Engine programs defined within a single database.

To locate section references:

1. Open the program containing the shared, or called, section.

2. Select Edit, Find References.

   The Find Definition References dialog box appears.

3. On the Call Sections tab, select the appropriate section from the Section name drop-down list or enter the name.

   By default, the current program name and MAIN section appear in the dialog box.

4. Click OK.

5. In the output window, view the generated list.

   The output window lists the programs and sections that call a particular program. This list also shows the total call references made to a particular section. Call sections within the current program appear first in the list.

   Double-click an item in the output window list to automatically navigate the definition view to that calling section.

Finding Sections Within the Current Program

Within large and complicated Application Engine programs, such as those upgraded from a previous release, having more than 100 sections is not uncommon. Rather than scrolling through a large program, use the Go To Section feature.

Note. This feature applies only to the current program.

To automatically navigate to a selected section:

1. Select Edit, Go To Section.

   The Find Definition References dialog box appears.

2. On the Go To Section tab, select the appropriate section from the Section name drop-down list or enter the name of the section.

3. Click OK.

   The Definition view scrolls to the first occurrence of the section with the name you selected.

Setting Section Properties

Controls that specify section properties are located in the Definition view. For example, for each section included in your program, a node, as shown in the following example, appears. You specify all of the attributes to associate with a particular section from this node:

The values you specify at the section level generally apply to all the objects contained within that section.

Adding Steps

A step represents the smallest unit of work that can be committed in a program. When you create a program, you have a default MAIN section and step that is initially named Step01.

This section discusses how to:

• Insert steps.

• Set up step properties.

Inserting Steps

To insert a step:

1. Highlight the section or step that you want to precede the new step.

   For example, if you want the new step to be the first step in the section, select the section node. Otherwise, select the existing step that you want the new step to follow.

   Note. The name of the section in which you insert the step appears to the right of the step description. In large programs, this step enables you to determine the section in which a step resides if the section is not in view. Also, note that a sequence number appears on each step (001, 002, 003, and so on) so that you can determine the order of a step within a section. The sequence numbering for steps begins at 001 within each section.

2. Select Insert, Step/Action.

   By default, the steps are given a default name of StepN+1 beginning with Step01. Rename the step to better define the type of action this step contains.

   Note. The designer continues to increment the step name until it has a unique step name within a section. If the designer is unable to create a unique name after 50 attempts, a new step is not inserted.

3. Specify a step name and the remaining values.

   To rename a step, position the cursor in the step name edit box and enter a custom name. Only accept the default name for building quick, simple programs and for training purposes.

Setting Up Step Properties

You set up step properties in Definition view.

Note. The On Error property does not apply to compile errors (for example, specifying erroneous SQL statements). It checks only for execution-type errors. If your program has a syntax error, the program terminates.

Specifying Actions

This section provides an overview of actions and discusses how to:

• Insert actions.

• Set action properties.

• Specify SQL actions.

• Specify Do actions.

• Specify PeopleCode actions.

• Specify Call Section actions.

• Specify Log Message actions.

• Specify XSLT actions.

Understanding Actions

You can include eight types of actions within a step, and a step can contain multiple actions. The actions you define for a step depend on the results that your program requires at each stage of execution.

The only mutually exclusive actions within a single step are Call Section and SQL Statement; you cannot add a Call Section action to a step that already contains a SQL Statement action, and vice versa. You can include only one of each action type within a single step. Because eight types of actions are available and two of these are mutually exclusive, the maximum number of actions a single step can contain is seven.

Action Execution Order

At runtime, the system evaluates actions by type and runs them within a strict hierarchy. For example, if both a Do When and PeopleCode action exist within a given step, then Application Engine always executes the Do When action first.

The following diagram shows the sequence and level of execution for each type of action:

Action execution hierarchy

As you add actions to a step in the Definition view, the actions are initially inserted after the selected definition (the owning step or a previous action). However, following a save request or a refresh of the view, the designer reorders all actions to match the execution hierarchy. This feature helps you visualize the sequence in which each step of your program logic runs.

Note. A SQL action and a Call Section action are interchangeable and mutually exclusive. Only one of these two actions can appear within a step.

When inserting actions, remember that:

• You cannot have more than one action of a specific type within the same step.

• You cannot have a SQL action and a Call Section action within the same step.

• You can define only XSLT type actions for programs defined as Transformation types (see the program properties).

Inserting Actions

To insert an action:

1. Highlight the step in which you want to insert an action.

2. Insert the action.

   You do this using one of the following methods:

   • Select Insert, Step/Action.

   • Right-click the step and select Insert Step/Action.

3. Select the action type from the drop-down list or, when current action type is selected, enter the first one or two characters of the desired action type and then press Tab. The first (or only) type qualified by your entry is updated in this control.

4. Enter a description of the action.

5. Specify the appropriate properties for the action you selected.

Setting Action Properties

To modify action properties, the Definition view must be active. Because you can include a variety of actions within a step, different sets of properties are specific to particular action types. Depending on the action type you select, the properties that appear will change.

For example, you can specify the reuse feature with a SQL action. This feature does not apply to a PeopleCode action; instead, you would need to specify how to respond to the return value of the PeopleCode program.

This example shows how you can select action-specific properties for different action types:

PeopleCode and all SQL action types invoke the related PeopleTools Editor to define or maintain the related text.

ReUse Statement Property

The ReUse Statement property is available for all SQL action types (SQL, Do When, Do While, Do Until, Do Select). You use the ReUse Statement property to optimize the SQL in your batch program. A ReUse Statement converts any %BIND references to state record fields into real bind variables (:1, :2, and so on), enabling the Application Engine runtime process to compile the statement once, dedicate a cursor, and then run it again with new data as often as your program requires. When you use SQL or a Do action to process a large volume of rows one at a time, inside a fetch loop, compiling each statement that you issue can affect performance significantly. ReUse Statement is a way to combat possible performance slowdowns.

Note. You can have Application Engine recompile a reused statement by using the %ClearCursor function.

When setting the ReUse Statement option, choose from these values:

Note. The ReUse Statement property can improve performance significantly. However, do not use it if %BIND variables are building parts of the SQL statement or are in the field list of a Select statement (this note does not apply if you use the Static option in %BIND).

Specifying SQL Actions

This is the default action type for the first action within a given step. Use this action to perform the following SQL commands on multiple rows:

• Update

• Insert

• Delete

• Select

Note. Before you insert SQL (select View, SQL) into a SQL action within a new Application Engine program, you must have saved the program previously. Saving is required because the program name you use to save the definition is used to relate your program with the SQL objects you are about to create. The same is true for inserting PeopleCode.

With a SQL action, you use the SQL Editor to create and modify a SQL statement. Following are some examples of SQL statements:

%Select(AF_PERFM_AET.PREV_ASOF_DT)
SELECT %DateOut(ASOF_DT)
FROM PS_AF_FCST_SCHT%Bind(EPM_CORE_AET.TABLE_APPEND,NOQUOTES)
WHERE AFDEFN_ID = %Bind(AF_CORE_AET.AFDEFN_ID)
AND ASOF_DT = (SELECT MAX(ASOF_DT)
FROM PS_AF_FCST_SCHT%Bind(EPM_CORE_AET.TABLE_APPEND,NOQUOTES)
WHERE AFDEFN_ID = %Bind(AF_CORE_AET.AFDEFN_ID)
AND ASOF_DT < %Bind(AF_PERFM_AET.ASOF_DT))

Note. If you intend to include multiple SQL statements within a single action, you should use the meta-SQL construct %EXECUTE. The previous sample SQL statement sample contains bind variables from a previous Application Engine action.

No Rows Property

In addition to the ReUse Statement property, the No Rows property is available for SQL actions. If the SQL (Insert, Update, or Delete) associated with the SQL action does not return any rows, you must specify what the Application Engine program should do.

For example, you could use the No Rows property when you insert into a temporary table and then intend to perform further operations on the inserted rows (provided that some rows meet the criteria). If the initial combination of Insert and Select statements provides no rows, you could save the program from having to reselect on the temporary table before executing another operation, or you could prevent the program from performing set operations on the table with no qualifying rows.

When you set the No Rows property, choose from the following values:

Note. Using the No Rows property in conjunction with a Truncate Table operation is unreliable. Some database platforms report zero rows affected for truncations, regardless of how many rows were in the table.

Specifying Do Actions

Although distinct from the others, these four types of Application Engine actions can be grouped together:

• Do When

• Do While

• Do Until

• Do Select

Use these actions to control the running of your program. These action types enable you to control the execution of subsequent sections, actions, or SQL statements, depending on the results of a Do SQL statement in the form of a Select statement. If you coded in COBOL, you would perform similar actions using the If and While functions.

Any of the Do actions can control the running of a section, a SQL statement, a PeopleCode program, or a log message. For example, a Do Select can run a SQL statement for each row returned by the included Select statement.

Do When

When using a Do When action, note that:

•  The Do When action is a Select statement that allows subsequent actions to be run if any rows of data are returned.

• This action is similar to a COBOL If statement.

  A Do When statement runs before any other actions in a step. If the Do When statement returns any rows, the next action is executed. If the Do When conditions are not met, the remaining actions within that step are not executed. Your program runs a Do When action only once when the owning step executes.

• The only property that you can specify for a Do When action is the ReUse Statement property, which applies to all SQL-based actions.

Do While

The Do While action is a Select statement that, if present, runs before subsequent actions of the step. If the Do While statement does not return any rows of data, the action terminates. The Do While statement is identical to the COBOL While statement. Subsequent actions within the step are executed in a loop as long as at least one row is returned by the Select statement for the Do While action. If the Do While statement does not return any rows, the step is complete.

The only property that you can specify for a Do While action is the ReUse Statement property, which applies to all SQL-based actions.

Do Until

A Do Until action is a Select statement that runs after each action when a step completes. If the Select statement returns any rows of data, the step terminates. When using a Do Until action, note that:

• You use a Do Until action if you want the processing actions to execute at least once and to execute repeatedly until a certain condition is true, such as a Select statement returns some rows.

• You can use a Do Until action to stop a Do Select action prematurely.

  For example, if a Select statement for a Do Until action does not return any rows, then the actions in the step are repeated (except if a Do When action appears in the step). Normally, a Do Select action continues until no rows are returned. If any rows of data are returned, the Do Select action stops and the step is not repeated.

• The only property that you can specify for a Do Until action is the ReUse Statement property, which applies to all SQL-based actions.

Do Select

The Do Select action is a Select statement that executes subsequent actions once for every row of data that the Do Select statement returns. For instance, a Do Select statement can run a SQL statement for each row returned from the Select statement. The subsequent actions within the step are executed in a loop based on the results of the Select statement. The type of the Do Select determines the specific looping rules.

Like the other Do actions, you can specify the ReUse Statement property for the Do Select action; this property applies to all SQL-based actions.

In addition to the ReUse Statement property, you must also specify this Do Select property: Do Select Type.

Note. Application Engine does not commit a step containing a Do Select action with the Select/Fetch option enabled until the entire step completes successfully, regardless of the other options you have selected.

For example, suppose at the step level you specified to commit every 100 iterations of the step. One of the actions of this step is a Do Select action with Select/Fetch selected. Because Application Engine does not checkpoint or commit while a Do Select action is active, the transaction performed by the actions within a step is not committed until the entire step completes successfully. This note also applies if any sections are called from inside the loop.

Do Select Type Property

When you specify the Do Select Type property in a Do Select action, you select from the following values:

Specifying PeopleCode Actions

Use this action type to insert PeopleCode within your Application Engine program. You can invoke the PeopleCode Editor directly from the designer interface to code your PeopleCode programs.

With a PeopleCode action, you can specify only one property: On Return.

Use the On Return value to determine how your Application Engine program reacts based on the return of your PeopleCode program. The On Return setting takes effect if your PeopleCode program issues a “return 1” or “exit 1.” You can use the True keyword in place of a non-zero numeric return.

When you specify the On Return property, you select from the following values:

Specifying Call Section Actions

Use the Call Section action to call another section defined in an Application Engine program. You can call a local section defined within your current program, and you can make external calls to a section defined in another Application Engine program.

The external section you intend to call must have its access property set to Public. If the access property of a section is set to Private, that section can be called only from within the same program. By default, the access property of a section is Private. If you attempt to make a call to a section that does not allow external calls, you receive an error message at runtime.

Note. You can call only programs that reside within the same database as the calling program.

Program ID Property

Because you can call sections defined in the current program or within external programs, you must first specify the program ID of the program containing the section you intend to call.

The default value is (current). If you call a section defined in another program, make sure that you first select the appropriate external program from the Program ID drop-down list. This drop-down list contains the names of all program definitions that currently exist in the database.

Section Name Property

Select from names defined in the program that appears in the Program ID list. To call a section that is defined in an external program, select the program name in the Program ID edit box before selecting the section name.

Also use the Call Section action to call an entire external program. First select the program ID, and then select section name MAIN. At runtime, this call executes the entire program defined by the value in the Program ID field.

Note. Application Designer does not prevent you from calling the Main section of the current program or the current section. For instance, Section1 can contain a step that has a local call section reference for Section1. This reference enables recursive calls and should, therefore, be used with caution.

Dynamic Property

Use the AE_APPLID and AE_SECTION fields in the state record to run different sections, depending on the conditions a program encounters during runtime.

You must define these two fields in the default state record for the program. If AE_APPLID is not present or is blank (at runtime), the current program is substituted for the AE_APPLID value. If AE_SECTION is not present or is blank, an error occurs.

When issuing a dynamic call, both the section and the program ID must be dynamically set. 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. The values you insert in these fields are normally based on various conditions met within your program. Then you create a Call Section action that calls the section name defined in the state record field by selecting the Dynamic check box.

Selecting Dynamic automatically populates the AE_SECTION field with the symbolic value %Section and the Program ID field with the symbolic value %AEAPPLID. At runtime, the program calls the section name stored in AE_SECTION that belongs to the program name defined by AE_APPLID.

Program Properties of Called Sections

When you call a section defined in an external program, the current program (the program containing the defined call section) defines the properties that apply to the running process. Suppose tracing is enabled for the current program but disabled for the called program section. In this case, the called program has the trace option enabled at runtime because it inherits the properties of the calling program.

For example, if program A calls program B, and program B calls program C, then the properties of A apply to both programs B and C. The calling program always controls the properties for the called program. In this case, program A controls the properties for program B and because program B inherits the properties of program A, when program B calls program C the properties of program A also apply to program C.

Note. Although program properties are inherited, state records do not follow this inheritance model.

State Records of Called Programs

When you call a program from another program, the default state record of the called program becomes active until processing returns to the initial program. However, all of the state records associated with both programs are available. State records that are common between the two programs share values. To communicate between the two programs or share %BIND variables, define the same state records in both programs.

Specifying Log Message Actions

Use this type of action to write a message to the message log. The message log refers to the PeopleTools table (PS_MESSAGE_LOG) where execution messages reside. Any substitution parameters are written to PS_MESSAGE_LOGPARM. The following example shows a Log Message action:

You can use the Log Message action to insert any type of message. Typically, a Log Message action writes error messages to the message log, but you can also write informational or status messages.

Note. You can also use MessageBox PeopleCode to populate PS_MESSAGE_LOG instead of using the Log Message action. Using MessageBox PeopleCode enables you to record errors encountered within Application Engine PeopleCode programs easily.

For example, using message set 1012, number 10, the message reads "The total number of %1 rows exceeds the control count value, %2,” and you need the following parameters:

Invoice, %Bind(CONTROL_CNT)

Suppose you run this program with the CONTROL_CNT field value of 120. When the process ends, the following message would be included on the Process Details dialog box in Process Monitor: “The total number of Invoice rows exceeds the control count value, 120.”

Specifying XSLT Actions

You use XSLT actions only for transform programs.

See Also

Using XSLT for Transformation