2 Understanding Events, Event Rules, and Runtime Processing
This chapter contains the following topics:
2.1 Events
Events are activities that occur on a form, such as entering a form or exiting a field by using Tab. Events can be initiated by the user or the application. A single control might initiate multiple events. The system also initiates some events, such as Last Grid Record Has Been Read, when certain actions occur.
2.2 Event Rules
-
Event rules
-
Named event rules
-
Embedded event rules
2.2.1 Event Rules Fundamentals
Event rules (ER) are logic statements that you can create and attach to events. ER is initiated when events occur at runtime. Oracle's JD Edwards EnterpriseOne software supports two kinds of event rules: named event rules and embedded event rules.
You can attach multiple event rules to one event. The various kinds of event rules include:
-
Conditional statements, such as If/Else/End If.
-
While loops.
-
Assignments.
-
Calls to business functions.
-
Form or report interconnections.
-
Calls to system functions.
-
Table I/O operations.
2.2.2 Named Event Rules
A named event rule (NER) is a series of regular ER statements (such as assignments, business functions, system function calls, and so forth). A NER encapsulates the series of statements into one reusable component. You can call a NER the same way as calling a business function. Business functions implement customized business logic using C language; NERs implement customized business logic using event rule statements.
2.2.3 Embedded Event Rules
In addition to NERs, the other kind of ER is called embedded event rules, or simply event rules. Embedded ER is specific to a particular table, interactive application, or batch application. Embedded ER for a table is called table event rules or table triggers. Embedded ER for an interactive application or batch application is called application event rules.
2.2.3.1 Application Event Rules
You can add business logic that is specific to a particular application. Interactive applications connect ER using Oracle's JD Edwards EnterpriseOne Form Design Aid (FDA), while batch event rules use Oracle's JD Edwards EnterpriseOne Report Design Aid (RDA).
2.2.3.2 Table Event Rules
You can create table-specific event rules, which are ER that you attach to a table using Table Design Event Rules. This logic runs whenever any JD Edwards EnterpriseOne application accesses that table and uses that ER. For example, to maintain referential integrity, you might attach ER to a master table that deletes all children when a parent is deleted. Any JD Edwards EnterpriseOne application that deletes information from that table does not need to have embedded parent/child logic, because that logic exists in the table.
Note:
Be aware that this functionality applies only to JD Edwards EnterpriseOne applications. Other applications that access the same database table cannot and do not use these ERs.2.3 Runtime Processing of Event Rules
This section discusses:
-
Runtime processing of event rules.
-
Runtime data structures.
-
Form flow.
2.3.1 Fundamentals of Runtime Processing of Event Rules
Runtime processing refers to how, at runtime, the system evaluates various events (such as initializing a form, clicking a button, and using Tab to move between fields) and their attached ER. ER is attached to events, which in turn are attached to controls or forms.
FDA provides several different form types, each of which includes predefined fields and features that are specific to the form type. For example, a find/browse form automatically includes a Find menu option or tool bar button with appropriate functions attached to it. When users enter search text in a filter or query-by-example (QBE) field, and then click the Find button on the tool bar, the runtime engine processes logic to fetch a record.
To avoid generating unnecessary ER, you should understand the different field types and associated capabilities that characterize each form type.
2.3.2 Runtime Data Structures
Runtime data structures are structures or blocks of memory that hold data when user is working with an application. You should know what is happening to each form at runtime. You should know what is in a runtime structure at a given event point in the runtime process.
The runtime system dynamically creates runtime data structures. For example, if a form contains hidden controls, the system allocates memory for those controls even though they are not visible on the form. When you pass processing option (PO) values in a form, the system allocates memory to store the PO value.
2.3.2.1 Available Objects and Runtime Data Structures
A runtime data structure is made of a variety of objects on a form. An available object is represented by a two-character, alphabetical code that characterizes the source of data and determines how the object data is used in an interactive application at runtime. Available objects make up the runtime data structure for a form.
During runtime processing, the system stores data in memory in an internal data structure. Certain fields of the data structure temporarily store data during runtime. When no longer needed, the data is deleted so that the system can process another record.
In ER, you can access and modify available objects in order to implement business logic. For example, you can assign a value to a QBE field to set query criteria for the form.
This table lists the available objects:
| Available Object Code | Description |
|---|---|
| BC | A column in the business view (BV). BCs for both the form view and the grid view appear in this list. The system fills these columns with values from the database when it performs a fetch. The system writes these values to the database during an add or update. |
| GC | A column in the grid. The row that the value references depends on which event is accessing the GC. During the fetch cycle, it is usually the selected row. In some circumstances, CG objects also denote a particular physical column in the grid instead of a value. An example is the Set Grid Font system function. |
| GB | The grid buffer. This buffer is one row of data that is independent of the lines that the system reads from the database and writes to the grid. The GB enables you to manipulate column data for a line that you want to insert or update without affecting the present state of the grid. You access the GB through an available GB object, which appears after the GC objects in the list of available objects in Event Rules Design. Each grid contains only one instance of each GB column. |
| FC | A control on the form. If the control is a database item, this field corresponds to a BC object. Furthermore, if the control is not a filter, the FC object represents the same value as the BC object, and changing one of these results in changing both. |
| FI | A value passed through a form interconnection. You access this object either to read values that are passed into the form or to set values to be passed back. These objects correspond to the elements of the form data structure. |
| PO | A value passed from a PO. These values are passed into the application when a user launches it. Any form in that application can access them. POs can either be entered by the user, or they can be set up in a particular version of an application. |
| QC | A cell from the QBE line in the grid. These objects represent the values in any QBE cell on the grid. They include wild cards, but do not include any comparison operators. Likewise, assignments to these objects can include wild cards, but not comparison operators. To set comparisons, you must use a system function. |
| HC | A hypercontrol item. A hypercontrol item is a menu item or a tool bar item. |
| VA | ER variables. These objects represent any variables that you set up in ER. |
| SV | System variables. These objects represent some environment variables that are accessible to ER. |
| SL | System literals. These objects represent some constant system values that are accessible to ER. |
| TP | Tab page object. |
| TK | A column in the table that contains the table ER. |
| CO | A constant, such as the return code for an error. |
| TV | Text variables. |
| RC | Report constants for a batch application. |
| RV | Report variables (batch application). |
| IC | An input column (table conversion). |
| OC | An output column (table conversion). |
BC and FC share the same internal structure if an FC is associated with a database item; filter fields are an exception.
2.3.2.2 Processing Available Objects
When an available object is changed through ER, these actions occur:
-
The object in the internal runtime structure is changed.
-
If the object is a form control or grid cell, row, or column, the screen is updated with the new value.
A BV form control shares the same value as the corresponding business view item. (Filter fields are an exception to this rule.) This means that:
-
FC data and BC data are always identical.
-
Whenever FC data is changed, BC items are changed to the same value.
-
Whenever BC values are changed, the FC runtime values also changes to the same values. This change may not immediately reflected to the screen.
-
On Control is Exited processing, the value entered into the form control is captured in both the BC and FC item for that control.
2.3.2.3 Control is Exited Processing
Control is Exited processing includes these actions:
-
The value in the control is saved to internal runtime structures.
-
The Control is Exited event is processed.
If the value has changed since the previous time that the control was exited, these steps occur:
-
The system processes the Control Exited/Changed-Inline event.
-
The system processes the Control Exited/Changed-Async event.
-
The system validates the value using edit rules defined for the DD item.
-
The form control data is formatted using format rules defined for the DD item and displayed on the screen.
The Trigger Parallel Event system function is available for the Control Exited/Changed-Inline and the Control Exited/Changed-Async events. This system function will enable a parallel event to run on a separate thread and will not interfere with existing Event Rules. (Release 9.1 Update 5)
2.3.3 Form Flow
Each form type has different properties and event flow. The system provides events for the forms so that you can insert custom logic. These events occur regardless of whether you add event rule logic for that event.
This example represents how values in the runtime structures are stored in memory compared to how they appear on the form. This example uses the find/browse form when it is called directly from a menu. The runtime engine processes events in a certain order. The next sections describe the typical events for the find/browse form and the order in which they are processed. This process flow can vary depending on specific user interaction and the event rule logic that you use.
2.3.3.1 Pre-Dialog Is Initialized
These steps occur before the Dialog is Initialized event is processed and the form appears:
-
Initialize runtime structures (or clear memory) as shown:
-
BC = null.
-
FC = null.
-
GC = null.
-
FI = Values passed from a calling form (if any).
-
PO = Values passed from processing options.
-
-
Initialize form controls.
-
Initialize error handling.
-
Initialize static text.
-
Initialize helps.
-
Create tool bar.
-
Load form interconnect data into corresponding BC columns and filter fields (if any exist).
-
Initialize thread handling.
2.3.3.2 Dialog Is Initialized
The system processes all event rule logic that is attached to the Dialog is Initialized event. When this event starts, the runtime structures contain these values:
-
BC = Any FI values passed.
-
FC = Any FI values passed.
-
GC = null.
-
FI = Values passed from a calling form (if any).
-
PO = Values passed from POs.
This diagram illustrates the information in the runtime structures just before the system fires Dialog is Initialized:
Figure 2-1 Content of runtime structures before Dialog Is Initialized fires
Description of "Figure 2-1 Content of runtime structures before Dialog Is Initialized fires"
The Dialog is Initialized event can be used to initialize the form. After the Dialog is Initialized event is finished, runtime starts the Post Dialog Is Initialized process.
2.3.3.3 Post Dialog Is Initialized
Before the system fires the Post Dialog is Initialized event, the runtime structures contain these values:
-
BC = null (or values already passed in).
-
FC = null (or values already passed in).
-
GC = null (or values already passed in).
-
FI = Values passed from a calling form (if any).
-
PO = Values passed from POs.
This diagram illustrates the information in the runtime structures just before the system fires the Post Dialog Is Initialized event:
Figure 2-2 Content of runtime structures before Post Dialog Is Initialized fires
Description of "Figure 2-2 Content of runtime structures before Post Dialog Is Initialized fires"
The Post Dialog is Initialized event is commonly used to perform these tasks:
2.3.3.4 Building SQL SELECT
After the user clicks Find, the system builds a SELECT statement with a WHERE clause. The SQL SELECT statement includes all columns in the BV. The WHERE clause includes any values in the QBE or filter fields. It can also contain values passed through Set Selection and Set Lower Limit system functions. The WHERE clause is then used to get all records that meet the criteria.
This diagram illustrates the information that appears in the runtime structures just before the system builds the SQL statement:
Figure 2-3 Content of runtime structures before SQL Select statement builds
Description of "Figure 2-3 Content of runtime structures before SQL Select statement builds"
2.3.3.5 Fetching Records
Records are fetched one page at a time (unless page-at-a-time is disabled). The system processes each record fetched one by one and display it in the grid row.
2.3.3.6 Page-at-a-Time Processing
Page-at-a-time processing means that the system fetches only a single page worth of records to display. To see the next page of records, the user clicks the Next button. You can customize the page size for each grid in FDA. A system administrator can also set a global page size for all grids.
Typically, page-at-a-time processing improves performance and scalability. Although it can be disabled, the JD Edwards EnterpriseOne standards state that you should not disable it unless you have a valid business reason to do so.
2.3.3.7 BC Assigned Database Values
After the system fetches each record from the database, it copies the database values to the BC items. Values from each marked column in the table appear in the BC runtime structure elements.
This diagram illustrates the information in the runtime structures when the system reads the first record:
Figure 2-4 Content of runtime structures when first record read
Description of "Figure 2-4 Content of runtime structures when first record read"
2.3.3.8 Grid Record Is Fetched
The engine then fires the Grid Record is Fetched event. At this point, the runtime structures have these values:
-
BC = Values from the database (for the first record read).
-
FC = Values from the database (if the fields are database fields).
-
GC = null.
-
FI = Values passed from a calling form (if any).
-
PO = Values passed from POs.
This diagram illustrates the information in the runtime structures just before the system fires Grid Record is Fetched:
Figure 2-5 Content of runtime structures before Grid Record is Fetched fires
Description of "Figure 2-5 Content of runtime structures before Grid Record is Fetched fires"
The Grid Record is Fetched event is commonly used to perform these actions:
After the Grid Rec Is Fetched event fires, the BC values are copied into the GC runtime structure.
This diagram illustrates the information in the runtime structures when the system reads the first record:
Figure 2-6 Content of runtime structures when first record is read
Description of "Figure 2-6 Content of runtime structures when first record is read"
2.3.3.9 Write Grid Line-Before
The engine then fires the Write Grid Line-Before event. A this point, the runtime structures have these values:
-
BC = Values from the database (from the record just read).
-
FC = Values from the database (if the fields are database fields).
-
GC = Values from the database (from the previous read).
-
FI = Values passed from a calling form (if any).
-
PO = Values passed from POs.
This diagram illustrates the information in the runtime structures just before the system fires Write Grid Line-Before:
Figure 2-7 Content of runtime structures before Write Grid Line–Before fires
Description of "Figure 2-7 Content of runtime structures before Write Grid Line–Before fires"
The Write Grid Line–Before event is commonly used to perform these tasks:
-
Add logic before the user sees a row on the form.
-
Retrieve additional information for the grid row, such as a description, from tables that are not in the BV.
After the system processes Write Grid Line–Before, the GC elements, which now include the database values for the first record, are copied to the grid cells on the form.
This diagram illustrates the information that appears in the runtime structures now:
Figure 2-8 Content of runtime structures after Write Grid Line–Before fires
Description of "Figure 2-8 Content of runtime structures after Write Grid Line–Before fires"
2.3.3.10 Write Grid Line–After
The engine then fires the Write Grid Line-After event. At this point, the runtime structures have these values:
-
BC = Values from the database (from the first record read).
-
FC = Values from database (if the field is a database field).
-
GC = Values from the database (from the first record read).
-
FI = Values passed from a calling form (if any).
-
PO = Values passed from POs.
The system displays the current record in the grid cells.
This diagram illustrates the information in the runtime structures just before the system fires Write Grid Line–After:
Figure 2-9 Content of runtime structures before Write Grid Line–After fires
Description of "Figure 2-9 Content of runtime structures before Write Grid Line–After fires"
You typically use the Write Grid Line–After event to add logic after the user sees a row on the form.
This diagram illustrates the information in the runtime structures after the system processes Write Grid Line–After:
Figure 2-10 Content of runtime structures after Write Grid Line After runs
Description of "Figure 2-10 Content of runtime structures after Write Grid Line After runs"
The system continues to read records from the database and performs the same processing steps. When the system reads the next record, it performs these processing steps:
-
Assign BC values from the database.
-
Process Grid Rec is Fetched ER.
-
Assign BC values to GC.
-
Process Write Grid Line–Before ER.
-
Display values in the grid row on the form.
-
Process Write Grid Line–After ER.
This process is repeated until there are no more records fetched.
2.3.3.11 Last Grid Record Has Been Read
When there are no more records fetched from the database, the engine fires Last Grid Record Has Been Read event. At this point, the runtime structures contain these values:
-
BC = Values from the database (from the last record read).
-
FC = Values from the database (if the field is a database field).
-
GC = Values from the database (from the last record read).
-
FI = Values passed from a calling form (if any).
-
PO = Values passed from POs.
The GC values appear on the last grid row.
This diagram illustrates the information in the runtime structures just before the system runs Last Grid Record Has Been Read:
Figure 2-11 Content of runtime structures before Last Grid Record Has Been Read fires
Description of "Figure 2-11 Content of runtime structures before Last Grid Record Has Been Read fires"
The Last Grid Record Has Been Read event is commonly used to write total lines to the grid and to display totals that are based on grid values.
2.3.3.12 Select Button Processing
When a user selects a grid row and clicks the Select button, the BC structure stays the same, however the GC structure reflects values on the row that is being selected.
This diagram illustrates the information in the runtime structures when the user selects a grid row that is other than the last fetched row. Note that the BC and GC structures do not contain the same values:
Figure 2-12 Content of runtime structures when user selects grid row that is other than the last fetched row
Description of "Figure 2-12 Content of runtime structures when user selects grid row that is other than the last fetched row"
2.3.3.13 Button Clicked
The engine then fires the Button Clicked event for the Select button. At this point, the runtime structures have these values:
-
BC = Values from the database (from the last record read).
-
FC = Values from the database (if the field is a database field).
-
GC = Values from the selected grid row.
-
FI = Values passed from a calling form (if any).
-
PO = Values passed from processing options.
This diagram illustrates the information in the runtime structures just before the system fires Button Clicked:
Figure 2-13 Content of runtime structures before Button Clicked fires
Description of "Figure 2-13 Content of runtime structures before Button Clicked fires"
The Button Clicked event is commonly used to connect to another form.
Use Repeat Business Rules for Grid to repeat ER when multiple rows are selected.
2.3.3.14 Add Button Processing
Normally, the user does not select a row before an add action, but if a row is highlighted, the system updates the GC values to reflect the selected row values. The system does not update the database just because the user clicks the row.
The engine pauses for the Button Clicked event to be processed. At this point, the runtime structures have these values:
-
BC = Values from the database (from the last record read).
-
FC = Values from the database (if the field is a database field).
-
GC = Values from the database (from the selected row).
-
FI = Values passed from a calling form (if any).
-
PO = Values passed from POs.
Because this is an add action, the content of GC is irrelevant at this point. BC and GC do not contain the same values.
This diagram illustrates the information that is in the runtime structures just before the system fires Button Clicked:
Figure 2-14 Content of runtime structures before Button Clicked for Add Button fires
Description of "Figure 2-14 Content of runtime structures before Button Clicked for Add Button fires"
You typically use the Button Clicked event for the Add button to interconnect to another form, such as a fix/inspect or headerless detail form on which the system actually performs the add action.
2.3.3.15 Delete Button Processing
When the user selects a grid row and clicks the Delete button, the system does not update the database immediately. The engine first fires the Button Clicked event for the Delete button. At this point, the runtime structures have these values:
-
BC = Values from the database (from the last record read).
-
FC = Values from the database (if the field is a database field).
-
GC = Values from the database (from the selected row).
-
FI = Values passed from a calling form (if any).
-
PO = Values passed from POs.
This diagram illustrates the information in the runtime structures just before the system fires Button Clicked for the Delete button:
Figure 2-15 Content of runtime structures before delete Button Clicked fires
Description of "Figure 2-15 Content of runtime structures before delete Button Clicked fires"
Next, the Delete Grid Rec Verify–Before event fires.
2.3.3.16 Delete Grid Rec Verify–Before
This diagram illustrates how the engine fires the Delete Grid Rec Verify–Before event:
Figure 2-16 Content of runtime structure when Delete Grid Rec Verify–Before fires
Description of "Figure 2-16 Content of runtime structure when Delete Grid Rec Verify–Before fires"
Next, the system displays a pop up window for user to confirm the delete. If the delete is confirmed, the Delete Grid Rec Verify–After event fires.
2.3.3.17 Delete Grid Rec Verify–After
In the Delete Grid Rec Verify-After event, you might want to perform custom logic to verify that the delete is valid. For example, other tables might contain dependant records that prevent this record from being deleted as long as they exist.
The system processes the logic that is attached to this event after the user clicks the OK button in the Verify confirmation form. If the user clicks the Cancel button in the Verify confirmation form, the logic attached to this event does not occur.
Next, the Delete Grid Rec From DB–Before event occurs.
2.3.3.18 Delete Grid Rec From DB–Before
At this point, the runtime structure FC is blank. The system has not yet deleted the record from the database. You can use the Suppress Delete system function in this event to prevent the system from deleting the record :
After the system processes the Delete Grid Rec From DB–Before event, it builds a SQL DELETE statement. Then the system deletes the current record. When user selects multiple records, all selected records are deleted.
2.3.3.19 Delete Grid Rec From DB–After
After the records are deleted from the database, the system fires the Delete Grid Rec From DB After event You might use this event to call a business function to delete information from related tables that are not in the current BV.