Processing Sequences

Actions and PeopleCode events can occur in various sequences within the Component Processor’s flow of execution. Flow charts represent each sequence. In a flow chart, different shapes and colors represent different concepts.

Field or Control	Definition
	Blue rectangles represent actions taken by the system.

Field or Control	Definition
	Dark rhomboids represent branches (decision points) in the logic.

Field or Control	Definition
	Dark ellipses represent PeopleCode events.

Field or Control	Definition
	Light ellipses are subprocesses.

Most processing sequences correspond to high-level component processor behaviors. However, two important subsequences occur only in the context of a larger sequence. These subsequences are:

• Default processing, which occurs in a number of different contexts.

• Row select processing, which most commonly occurs as a part of component build in any of the update action modes.

  Row select processing also occurs when a ScrollSelect or related function is executed to load data into a scroll area.

See Component Processor Behavior, Default ProcessingDefault Processing.

See Deferred Processing Mode.

In default processing, any blank fields in the component are set to their default values. You can specify the default value either in the record field properties or in FieldDefault PeopleCode. If no default value is specified, the field is left blank.

Default processing is relatively complex. The following two sections describe how default processing works on the level of the individual field, and how default processing works in the broader context of the component.

Field-Level Default Processing

During default processing, the Component Processor examines all fields in all rows of the component. On each field, it performs the following:

1. If the field is set to NULL (blank) for a character field, or set to 0 for a numeric field, the Component Processor sets the field to any default value specified in the record field properties for that field.

2. If no default value for the field is defined in the record field properties, then the Component Processor initiates the FieldDefault event, which triggers any FieldDefault PeopleCode associated with the record field or the component record field.

3. If an error or warning executes in any FieldDefault PeopleCode, a runtime error occurs.

Important! Avoid using error and warning statements in FieldDefault PeopleCode.

Image: Field-level default sequence flow

The following flowchart explains the logic of Field-level default processing where in the Component Processor examines all fields in all rows of the component in a sequence flow.

Default Processing on Component Level

Under normal circumstances, default processing in a component is relatively simple: each field on each row of data undergoes field-level default processing. For typical development tasks, this is all you need to be concerned with. However, the complete context of default processing is somewhat more complex.

See Default Processing.

During component-level default processing, the Component Processor performs these tasks:

1. Field-level default processing is performed on all fields on all rows of data in the component.

2. If any field is still blank and any other field in the component has changed, field-level default processing may be repeated, in case a condition changed that causes default processing to now assign a value to something that was previously left blank.

3. The FieldFormula Event is initiated on all fields on all rows of data in the component.

   This PeopleCode event is often used for FUNCLIB_ (function library) record definitions to store shared functions, so normally no PeopleCode programs execute.

4. If the FieldFormula Event changed anything, field-level default processing is performed again, in case FieldFormula PeopleCode changed a field value to blank, or changed something that causes default processing to now assign a value to a field that was previously left blank.

   Because there should not be any FieldFormula PeopleCode, this is unlikely to affect the development process or performance.

5. If any field is still blank and any other field in the component has changed, field-level default processing is repeated.

Image: Default processing on component level

The following flowchart explains the logic of Default processing on component level.

If a user selects any of the update action modes (Update, Update/Display All, or Correction), the Component Processor begins update mode search processing, which includes the following steps:

1. The SearchInit PeopleCode event is initiated, which triggers any SearchInit PeopleCode associated with the record field or the component search record, on the keys or alternate search keys in the component search record.

   This enables you to control the search page field values or the search page appearance programmatically, or to perform other processing prior to the appearance of the search page.

   Note: Set the search record for the component in the component properties.

   For example, the following program in SearchInit PeopleCode on the component search key record field EMPLID sets the search key page field to the user’s employee ID, makes the page field unavailable for entry, and enables the user to modify the user’s own data in the component:

   EMPLID = %EmployeeId;
   &Field = GetField(EMPLID).Enabled = False;
   AllowEmplIdChg(True);

   Note: Generally, the system search processing displays the search page. You can use the SearchInit event, and the SetSearchDialogBehavior function, to set the behavior of the search page before it is displayed. If SetSearchDialogBehavior is set to Force display, the dialog box is displayed even if all required keys have been provided. You can also set SetSearchDialogBehavior to skip if possible. In addition, you can force search processing to always occur by selecting Force Search Processing in the component definition properties in PeopleSoft Application Designer.

2. The search page and prompt list appear, in which the user can enter search keys or select an advanced search to enter alternate search keys.

   Note: Normally, the values in the search page are not set to default values. However, if the SearchDefault function was executed in SearchInit PeopleCode for any of the search key or alternate search fields, those fields in the dialog box are set to their system default values. No other default processing occurs (that is, the FieldDefault event is not initiated).

3. The user enters a value or partial value in the search page, and then clicks Search.

4. The SearchSave PeopleCode event is initiated, which triggers any SearchSave PeopleCode associated with the record field or the component search record, on the search keys or alternate search keys in the search record.

   This enables you to validate the user entry in the search page by testing the value in the search record field in PeopleCode and, if necessary, issuing an error or warning. If an error is executed in SearchSave, the user is sent back to the search page. If a warning is executed, the user can click OK to continue or click Cancel to return to the search page and enter new values.

   If partial values are entered, such that the Component Processor can select multiple rows, then the prompt list dialog box is filled, and the user can select a value. If key values from the search page are blank, or if the system cannot select any data based on the user entry in the search page, the system displays a message and redisplays the search page. If the values entered produce a unique value, the prompt list is not filled. Instead, the user is taken directly to the page.

   Note: Normally, no system edits are applied when the user changes a field in the search page. However, if the SearchEdit property is executed for specific search page fields in SearchInit PeopleCode, the system edits are applied to those fields after the user changes a field and either leaves the field or clicks Search. In addition, the SearchEdit property can also be set in metadata for the record field definition.

   If the user entry in the field fails the system edits, the system displays a message, highlights the field in question, and returns the user to the dialog box. The FieldEdit and SaveEdit PeopleCode events are not initiated. The SearchSave event is not initiated after values are selected from the search list. To validate data entered in the search page, use the Component PreBuild event.

5. The Component Processor buffers the search key values.

   If the user then opens another component while this component is active, the Component Processor uses the same search key values and bypasses the search page.

Image: Search processing logic in update mode

The following flowchart shows this logic. (It does not show the effects of executing the SearchDefault and SearchEdit Field class properties.)

When a user opens a component in add or data-entry modes, the following actions occur:

1. The Component Processor runs default processing on the high-level keys that appear in the Add or Data Entry dialog box.

2. The Component Processor initiates the RowInit event, which triggers any RowInit PeopleCode associated with the record field or the component record, on the Add or Data Entry dialog box fields.

3. The Component Processor initiates the SearchInit event on dialog fields, which triggers any SearchInit PeopleCode associated with the record field or the component search record.

   This enables you to execute PeopleCode programs before the dialog box appears.

4. The Component Processor displays the Add or Data Entry dialog box.

5. If the user changes a dialog box field, and then leaves the field or clicks OK, the following actions occur:

   • In add mode only, a field modification processing sequence occurs.

     See Field Change Processing.

   • Default processing is run on the Add or Data Entry dialog box fields.

     Normally this does not have any effect, because the fields have a value.

6. When the user clicks OK in the dialog box, the SaveEdit event is initiated, which triggers any PeopleCode associated with the record field or the component record.

7. The Component Processor initiates the SearchSave event, which triggers any SearchSave PeopleCode associated with the record field or the component search record.

   This enables you to validate user entry in the dialog box. If an error is executed in SearchSave, the user is sent back to the Add or Data Entry dialog box. If a warning is executed, the user can click OK to continue or click Cancel to return to the dialog box and enter new values.

8. The Component Processor buffers the search key values and continues processing.

   Note: If you compare the following diagram with search processing in update modes, notice that the add modes are considerably more complex and involve more PeopleCode events. However, in practice, PeopleCode development is similar in both cases. PeopleCode that runs before the dialog box appears (for example, to control dialog box appearance or set values in the dialog box fields) generally is placed in the SearchInit event; PeopleCode that validates user entry in the dialog box is placed in the SearchSave event.

   See Search Processing in Update Modes.

Image: Search processing logic in add and data-entry modes

The following flowchart diagram shows the logic of Search processing in add and data-entry modes.

After the Component Processor has saved the search keys values for the component, it uses the search key values to select rows of data from the database server using a SQL Select statement. After the rows are retrieved, the Component Processor performs these actions:

1. Performs row select processing, in which rows of data that have already been selected from the database server can be filtered before they are added to the component buffer.

   See Row Select Processing.

2. Initiates the PreBuild event, which triggers any PreBuild PeopleCode associated with the component record, enabling you to set global or component scope variables that can be used later by PeopleCode located in other events.

   The PreBuild event is also used to validate data entered in the search page, after a prompt list is displayed.

   Note: If a PreBuild PeopleCode program issues an error or warning, the user is returned to the search page. If there is no search page, that is, the search record has no keys, a blank component page appears.

3. Performs default processing on all the rows and fields in the component.

   See Row Select Processing.

4. Initiates the RowInit event, which triggers any RowInit PeopleCode associated with the record field or the component record.

   The RowInit event enables you to programmatically initialize the values of non-blank fields in the component.

5. Initiates the PostBuild event, which triggers any PostBuild PeopleCode associated with the component record, enabling you to set global or component scope variables that can be used later by PeopleCode located in other events.

6. Initiates the Activate event, which triggers any Activate PeopleCode associated with the page about to be displayed, enabling you to programmatically control the display of that page.

7. Displays the component and waits for end-user action.

Image: Component build processing in update modes

The following flowchart shows the logic of Component build processing in update modes.

Row select processing enables PeopleCode to filter out rows of data after they have been retrieved from the database server and before they are copied to the component buffers. Row select processing uses a SQL Select statement .

Row select processing is a subprocess of component build processing in add modes. It also occurs after a ScrollSelect or related function is executed.

See Component Build Processing in Add Modes.

In row select processing, the following actions occur:

1. The Component Processor checks for more rows to add to the component.

2. The Component Processor initiates the RowSelect event, which triggers any RowSelect PeopleCode associated with the record field or component record.

   This enables PeopleCode to filter rows using the StopFetching and DiscardRow functions. StopFetching causes the system to add the current row to the component, and then to stop adding rows to the component. DiscardRow filters out a current row, and then continues the row select process.

3. If neither the StopFetching nor DiscardRow function is called, the Component Processor adds the rows to the page and checks for the next row.

   The process continues until there are no more rows to add to the component buffers. If both StopFetching and DiscardRow are called, the current row is not added to the page, and no more rows are added to the page.

   Note: In RowSelect PeopleCode, you can refer only to record fields on the record that is currently being processed, because the buffers are in the process of being populated. This means that the data might not be present.

Image: RowSelect processing logic

The following flowchart shows the logic of RowSelect processing in a Page.

After search processing in add or data-entry modes, the Component Processor:

1. Initiates the PreBuild event.

2. Runs default processing on all page fields.

   This enables you to set default fields programmatically using FieldDefault PeopleCode.

3. Initiates the RowInit event on all fields in the component, which triggers any RowInit PeopleCode associated with the record field or component record.

   This enables you to initialize the state of page controls, using RowInit PeopleCode, before the controls are displayed. (RowInit enables you to set the values of non-blank fields programmatically, whereas default processing is used to set blank fields to their default values.)

4. Initiates the PostBuild event, which triggers any PostBuild PeopleCode associated with the component record, enabling you to set global or component scope variables that can be used later by PeopleCode located in other events.

5. Initiates the Activate event, which triggers any Activate PeopleCode associated with the page about to be displayed, enabling you to programmatically control the display of that page.

6. Displays a new component, using the search keys obtained from the Add or Data Entry dialog box, with other fields set to their default values.

Image: Logic of component build processing in add modes

The following flowchart shows the logic of component build processing in add modes.

The field change processing sequence occurs after a user does any of the following:

• Changes the contents of a field, and then leaves the field (changes focus, for example, by tabbing out of the field).

  Note: In certain, limited circumstances, tabbing out of a field is not recognized as a change of focus. This occurs when the next item in the tab order does not have an “on-focus handler.” For example, the embedded help icon does not have an on-focus handler. In these limited circumstances, field change processing will not occur.

• Changes the state of a radio button or check box.

• Clicks a link or a button.

In this sequence, the following actions occur:

1. The Component Processor performs standard system edits.

   To reduce trips to the server, some processing must be done locally on the machine where the browser is located, while some is performed on the server.

   Standard system edits can be done either in the browser, utilizing local JavaScript code, or on the application server. The following table outlines where these system edits are done.

   System Edits	Location of Execution
   Checking data type	Browser
   Formatting	Application server or browser
   Updating current or history record	Application server
   Effective date	Application server
   Effective date or sequence	Application server
   New effective date in range	Application server
   Duplicate key	Application server
   Current level is not effective-dated but one of its child scroll areas is	Application server
   Required field	Browser
   Date range	Browser
   Prompt table	Application server
   Translate table	Browser
   Yes/no table	Depends on the field type. Browser if the field is a check box. Application server if the field is an edit box and the values are Y or N.

   Note: Default processing for the field can be done in the browser only if the default value is specified as a constant in the record field properties. If the field contains a default, these defaults occur only upon component initialization. Then, if a user replaces a default value with a blank, the field is not initialized again. The required fields check is not performed on derived work fields when you press Tab to move out of a field.

   If the data fails the system edits, the Component Processor displays an error message and highlights the field in the system color for errors (usually red).

2. If the field passes the system edits, Component Processor initiates the FieldEdit PeopleCode event, which triggers any FieldEdit PeopleCode associated with the record field or the component record field.

   This enables you to perform additional data validation in PeopleCode. If an Error statement is called in any FieldEdit PeopleCode, the Component Processor treats the error as it does a system edit failure; a message is displayed, and the field is highlighted. If a Warning statement is executed in any FieldEdit PeopleCode, a warning message appears, alerting the user to a possible problem, but the system accepts the change to the field.

3. If the field change is accepted, the Component Processor writes the change to the component buffer, then initiates the FieldChange event, which triggers any FieldChange PeopleCode associated with the record field or the component record field.

   This event enables you to add processes other than validation initiated by the changed field value, such as changes to page appearance or recalculation of values in other page fields. An Error or Warning statement in any FieldChange PeopleCode causes a runtime error.

   Important! Do not use Error or Warning statements in FieldChange PeopleCode. All data validation should be performed in FieldEdit PeopleCode.

   After FieldChange processing, Component Processor runs default processing on all page fields, then redisplays the page. If the user has changed the field value to a blank, or if SetDefault or a related function is executed, and the changed field has a default value specified in the record field definition or any FieldDefault PeopleCode, the field is initialized again to the default value.

Image: Logic of field modification processing

The following flowchart shows the logic of field modification processing in a Page.

Row insert processing occurs when:

• A user requests a row insert in a scroll area by pressing Alt+7, by clicking the Insert Row button, or by clicking the New button.

• A PeopleCode RowInsert function or a InsertRow method requests a row insert.

In either case, the Component Processor performs these actions:

1. Inserts a new row of data into the active scroll area.

   If the scroll area has a dependent scroll area, the system inserts a single new row into the blank scroll area, and the system continues until it reaches the lowest-level scroll area.

2. Initiates the RowInsert PeopleCode event, which triggers any RowInsert PeopleCode associated with the record field or the component record.

   This event processes fields only on the inserted row and any dependent rows that were inserted on lower-level scroll areas.

3. Runs default processing on all component fields.

   Normally this affects only the inserted row fields and fields on dependent rows, because other rows already have undergone default processing.

4. Initiates the RowInit PeopleCode event, which triggers any RowInit PeopleCode associated with the record field or the component record.

   This event affects fields only on the inserted row and any dependent rows that were inserted.

5. Redisplays the page and waits for user action.

   Important! Do not use Error or Warning statements in RowInsert PeopleCode. All data validation should be performed in FieldEdit or SaveEdit PeopleCode.

Image: Logic of row insert processing

The following flowchart shows the logic of row insert processing where in a PeopleCode RowInsert function or a InsertRow method requests a row insert.

Row delete processing occurs when:

• A user requests a row delete in a scroll area by pressing Alt+8, by clicking the Delete Row button, or by clicking the Delete button.

• A PeopleCode RowDelete function or a DeleteRow method requests a row delete.

In either case, these actions occur:

1. The Component Processor initiates the RowDelete PeopleCode event, which triggers RowDelete PeopleCode associated with the record field or the component record.

   This event processes fields on the deleted row and any dependent child scroll areas. RowDelete PeopleCode enables you to check for conditions and control whether a user can delete the row. An Error statement displays a message and prevents the user from deleting the row. A Warning statement displays a message alerting the user about possible consequences of the deletion, but permits deletion of the row.

2. If the deletion is rejected, the page is redisplayed after the error message.

3. If the deletion is accepted, the row, and any child scroll areas dependent on the row, are flagged as deleted.

   The row no longer appears in the page, but it is not physically deleted from the buffer and can be accessed by PeopleCode all the way through the SavePostChange event (note, however, that SaveEdit PeopleCode is not run on deleted rows).

4. The Component Processor runs default processing on all component fields.

5. The Component Processor redisplays the page and waits for a user action

   Note: PeopleCode programs are triggered on rows flagged as deleted in SavePreChange and SavePostChange PeopleCode. Use the IsDeleted row class property to test whether a row has been flagged as deleted. You can also access rows flagged as deleted by looping through the rows of a scroll area using a For loop delimited by the value returned by the RowCount rowset property.

Image: Logic of row delete processing

The following flowchart shows the logic of row delete processing.

When a user presses a button, this initiates the same processing as changing a field. Typically, PeopleCode programs started by button are placed in the FieldChange event.

If the Allow Search Events for Prompt Dialogs checkbox is selected for the Record Field properties for a search key on a prompt table record, the search processing events are enabled for that field. When the user selects the prompt icon, the SearchInit event for that field executes before the search dialog displays. When the user selects the Look Up button on a prompt dialog the SearchSave event for the field executes.

Search event processing on prompt dialogs can affect performance. Oracle recommends that you limit the use of search events in prompt dialogs to simple tasks such as showing and hiding fields or character manipulation. Do not use the search events on prompt dialogs for complex functions such as AddKeyListItem, ClearKeyList, ClearSearchDefault, ClearSearchEdit, IsSearchDialog, SetSearchDefault, SetSearchDialogBehavior, or SetSearchEdit, and so on.

By default, Allow Search Events for Prompt Dialogs is off, in which case no PeopleCode event is initiated as a result of prompts.

No PeopleCode events are initiated as a result of the user returning to the search page or displaying a calendar. This process is controlled automatically by the system.

To display a pop-up menu, a user can click the pop-up button, either next to a field or at the bottom of a page (if the page has a pop-up menu associated with it.) The user can open a standard pop-up menu on a page field if no pop-up menu has been defined by an application developer for that page field.

The PrePopup PeopleCode event initiates only if the user opens a pop-up menu defined by an application developer on a page field. It does not initiate for a pop-up menu attached to the page background.

The PrePopup PeopleCode event enables you to disable, check, or hide menu items in the pop-up menu.

PrePopup PeopleCode menu item operations (such as HideMenuItem, EnableMenuItem, and so on) work with pop-up menus attached to a grid, not a field in a grid, only if the PrePopup PeopleCode meant to operate on that pop-up menu resides in the record field that is attached to the first column in the grid. It does not matter if the first field is visible or hidden.

Image: Logic of PrePopup even processing

The following flowchart shows the logic of PrePopup event processing, which enables the user to disable, check, or hide menu items in the pop-up menu.

Selected item processing occurs when a user selects a menu item from a pop-up menu. This initiates the ItemSelected PeopleCode event, which is a menu PeopleCode event.

Image: Logic of selected item processing

The following flowchart shows the logic of selected item processing, this occurs when a user selects a menu item from a pop-up menu.

A user can direct the system to save a component by clicking Save or by pressing Alt+1.

An application can prompt the user to save a component when the Next or List button is clicked, or when a new action or component is selected. If the user clicks Save after being prompted, save processing begins.

The following actions occur in save processing:

1. The Component Processor initiates the SaveEdit PeopleCode event, which triggers any SaveEdit PeopleCode associated with a record field or a component record.

   This enables you to cross-validate page fields before saving, checking consistency among the page field values. An Error statement in SaveEdit PeopleCode displays a message and then redisplays the page, stopping the save. A Warning statement enables the user to cancel save processing by clicking Cancel, or to continue with save processing by clicking OK.

2. The Component Processor initiates the SavePreChange event, which triggers any SavePreChange PeopleCode associated with a record field, a component record, or a component.

   SavePreChange PeopleCode enables you to process data after validation and before the database is updated.

3. The Component Processor initiates the Workflow event, which triggers any Workflow PeopleCode associated with a record field or a component.

   Workflow PeopleCode should be used only for workflow-related processing (TriggerBusinessEvent and related functions).

4. The Component Processor updates the database with the changed component data, performing any necessary SQL Insert, Update, and Delete statements.

5. The Component Processor initiates the SavePostChange PeopleCode event, which triggers any SavePostChange PeopleCode associated with a record field, a component record, or a component.

   You can use SavePostChange PeopleCode for processing that must occur after the database update, such as updates to other database tables not in the component buffer.

6. The Component Processor issues a SQL Commit statement to the database server.

7. The Component Processor redisplays the component.

Image: Logic of save processing

The following flow chart shows the logic of save processing sequence.