OTHER TRIGGERS 1 User-Named Trigger

A user–named trigger is a trigger that you define yourself in a form, and then call explicitly from other triggers or user–named subprograms. Each user–named trigger defined at the same definition level must have a unique name.

To execute a user–named trigger, you must call the EXECUTE_TRIGGER built–in procedure, as shown here:

Execute_Trigger(’my_user_named_trigger’);

Note: You can write user–named PL/SQL subprograms to perform almost any task for which you might use a user–named trigger.

Usage Notes

User-named PL/SQL subprograms can be written to perform almost any task for which one might use a user-named trigger.

As with all triggers, the scope of a user-named trigger is the definition level and below. When more than one user-named trigger has the same name, the trigger defined at the lowest level has precedence.

It is most practical to define user-named triggers at the form level.

Create a user-named trigger to execute user-named subprograms defined in a form document from menu PL/SQL commands and user-named subprograms. (User-named subprograms defined in a form cannot be called directly from menu PL/SQL, which is defined in a different document.) In the menu PL/SQL, call the EXECUTE_TRIGGER built-in to execute a usernamed trigger, which in turn calls the user-named subprogram defined in the current form.

DO_KEY built-in

Executes the key trigger that corresponds to the specified built-in subprogram. If no such key trigger exists, then the specified subprogram executes. This behavior is analogous to pressing the corresponding function key.

Syntax

PROCEDURE DO_KEY

(built-in_subprogram_name VARCHAR2); DO_KEY restrictions

DO_KEY accepts built-in names only, not key names: DO_KEY(ENTER_QUERY). To accept a specific key name, use the EXECUTE_TRIGGER built-in: EXECUTE_TRIGGER('KEY_F11'). DO_KEY examples

/* ** Built-in: DO_KEY

** Example: Simulate pressing the [Execute Query] key. */ BEGIN

Do_Key('Execute_Query'); END;

2.

On-Savepoint Trigger

Fires when Form Builder would normally issue a Savepoint statement. By default, Form Builder issues savepoints at form startup, and at the start of each Post and Commit Transaction

process. Usage Notes

To perform default Form Builder processing from this trigger, include a call to the ISSUE_SAVEPOINT built-in.

In an On-Savepoint trigger, the Savepoint_Name application property returns the name of the next savepoint that Form Builder would issue by default, if no On-Savepoint trigger were present. In an On-Rollback trigger , Savepoint_Name returns the name of the savepoint to which Form Builder would roll back.

Suppress default savepoint processing by setting the Savepoint Mode form document property to Off. When Savepoint Mode is Off, Form Builder does not issue savepoints and,consequently, the On-Savepoint trigger never fires.

/* ** Built-in: ISSUE_SAVEPOINT

** Example: Perform Form Builder standard savepoint processing.

** Decide whether to use this built-in based on a global flag setup at startup by the form,perhaps based on a parameter.

DECLARE

sp_name VARCHAR2(80); BEGIN

/* Get the name of the savepoint Form Builder needs to issue */ sp_name := Get_Application_Property(SAVEPOINT_NAME);

/* Check the global flag we setup at form startup */ IF :Global.Using_Transactional_Triggers = 'TRUE' THEN

User_Exit('my_savept name='||sp_name); /* Otherwise, do the right thing. */ ELSE

Issue_Savepoint(sp_name); END IF;

END;

3. Post-Change Trigger

Fires when any of the following conditions exist:

• The Validate the Item process determines that an item is marked as Changed and is not NULL.

• An operator returns a value into an item by making a selection from a list of values, and the item is not NULL.

• Form Builder fetches a non-NULL value into an item. In this case, the When-Validate- Item trigger does not fire. If you want to circumvent this situation and effectively get rid of the Post-Change trigger, you must include a Post-Query trigger

in addition to your When-Validate-Item trigger. See "Usage Notes" below. Usage Notes

• The Post-Change trigger is included only for compatibility with previous versions of Form Builder. Its use is not recommended in new applications.

• The Post-Query trigger does not have the restrictions of the Post-Change trigger. You can use Post-Query to make changes to the fetched database values. Given such changes, Form Builder marks the corresponding items and records as changed. 3. On-Lock Trigger

Fires whenever Oracle Forms would normally attempt to lock a row, such as when an operator presses a key to modify data in an item. The trigger fires between the key press and the display of the modified data.

Usage Notes:

• Use an On–Lock trigger to replace the default Oracle Forms processing for locking rows. For example, if you are designing an application for use on a single–user system, you can use the On–Lock trigger to speed processing by bypassing all lock processing. Also, use On–Lock if you are accessing a non–ORACLE data source directly, not by way of Open Gateway.

• When the On–Lock trigger fires as a result of an operator trying to modify data, the trigger fires only the first time the operator tries to modify an item in the record. The trigger does not fire during subsequent modifications to items in the same record. In other words, for every row that is to be locked, the trigger fires once.

• To perform the default Oracle Forms processing from this trigger, include a call to the LOCK_RECORD built–in.

• Use this trigger to lock underlying tables for non–updateable views.

/* ** Built-in: LOCK_RECORD

** Example: Perform Form Builder standard record locking on the queried record which has just been deleted or updated. Decide whether to use default processing or a user exit by consulting a global flag setup at startup by the form,perhaps based on a parameter.

** Trigger: On-Lock */ BEGIN

/* ** Check the global flag we set up at form startup */ IF :Global.Non_Oracle_Datasource = 'TRUE' THEN

User_Exit('my_lockrec block=EMP'); /* ** Otherwise, do the right thing. */ ELSE

Lock_Record; END IF;

END;

5. Pre-Popup-Menu Trigger

This trigger is called when a user causes a pop-up menu to be displayed. (In a Microsoft Windows environment, this occurs when a user presses the right mouse button.) Actions defined for this trigger are performed before the pop-up menu is displayed.

Usage Notes

Use this trigger to enable or disable menu items on a pop-up menu before it is displayed. 6. Query-Procedure Trigger

Automatically created by Form Builder when the query data source is a stored procedure. This trigger is called when a query operation is necessary. Think of this as an On-Query trigger that is called by the system instead of doing default query operations.

Usage Notes

When constructing a query, any of the items may be used, but the Query Data Source Columns property must be set so that those items can be passed to the query stored procedure. Then, the query stored procedure has to use those values to filter the data. This means that the enter query mode does not happen automatically unless you specify it.

7. Update-Procedure Trigger

Automatically created by Form Builder when the update data source is a stored procedure. This trigger is called when a update operation is necessary. Think of this as an On-Update trigger that is called by the system instead of doing default update operations.

8. When-Custom-Item-Event Trigger

Fires whenever a VBX control sends an event to Oracle Forms. Usage Notes:

Use a When–Custom–Item–Event trigger to respond to a selection or change of value for a VBX control. The system variable SYSTEM.CUSTOM_ITEM_EVENT stores the case–sensitive name of the event that occurred, and the system variable

SYSTEM.CUSTOM_ITEM_EVENT_PARAMETERS stores a parameter name that contains the supplementary arguments for an event that is fired by a VBX control.

Example:

This is an example of a procedure that can be called when Oracle Forms fires the When–Custom–Item–Event Trigger. DECLARE

TabEvent varchar2(80); TabNumber Number; BEGIN

TabEvent := :system.custom_item_event;

/* ** After detecting a Click event, identify the ** tab selected, and use the user–defined Goto_Tab_Page procedure to navigate to the selected page. */

IF (UPPER(TabEvent) = ’CLICK’) THEN

TabNumber := VBX.Get_Property(’TABCONTROL’,’CurrTab’); Goto_Tab_Page(TabNumber);

END IF; END;

9. When-Form-Navigate Trigger

Fires whenever any peer form navigation takes place. form

Use a When–Form–Navigate trigger to perform actions when any cross form navigation takes place without relying on window activate and window deactivate events.

This is an example of a procedure that can be called when Oracle Forms fires the When–Form– Navigate Trigger.

DECLARE

win_id WINDOW := FIND_WINDOW(’WINDOW12’); BEGIN

if (GET_WINDOW_PROPERTY(win_id,WINDOW_STATE) = ’MAXIMIZE’ THEN SET_WINDOW_PROPERTY(win_id,WINDOW_STATE,MINIMIZE); else SET_WINDOW_PROPERTY(win_id,WINDOW_STATE,MAXIMIZE); end if; END; 10. When-Tab-Page-Changed

Fires whenever there is explicit item or mouse navigation from one tab page to another in a tab canvas.

Usage Notes

• Use a When-Tab-Page-Changed trigger to perform actions when any tab page is changed during item or mouse navigation.

• When-Tab-Page-Changed fires only when tab page navigation is explicit; it does not respond to implicit navigation. For example, the trigger will fire when the mouse or

keyboard is used to navigate between tab pages, but the trigger will not fire if an end user presses [Next Item] (Tab) to navigate from one field to another field in the same block, but on different tab pages.

• When-Tab-Page-Changed does not fire when the tab page is changed programmatically. Example

/* Use a When-Tab-Page-Changed trigger to dynamically change a tab page's label from lower- to upper- case (to indicate to end users if they already have ** navigated to the tab page): */

DECLARE tp_nm VARCHAR2(30); tp_id TAB_PAGE; tp_lb VARCHAR2(30); BEGIN tp_nm := GET_CANVAS_PROPERTY('emp_cvs', topmost_tab_page); tp_id := FIND_TAB_PAGE(tp_nm); tp_lb := GET_TAB_PAGE_PROPERTY(tp_id, label); IF tp_lb LIKE 'Sa%' THEN

SET_TAB_PAGE_PROPERTY(tp_id, label, 'SALARY'); ELSIF tp_lb LIKE 'Va%' THEN

SET_TAB_PAGE_PROPERTY(tp_id, label, 'VACATION'); ELSE null;

END IF; END;

11. When-Tree-Node-Activated Trigger

Fires when an operator double-clicks a node or presses Enter when a node is selected. Usage Notes

• SYSTEM.TRIGGER_NODE is the node the user clicked on. SYSTEM.TRIGGER_NODE returns a value of type NODE.

• No programmatic action will cause the When-Tree-Node-Activated trigger to fire. Only end-user action will generate an event.

12. When-Tree-Node-Expanded Trigger

Fires when a node is expanded or collapsed. Usage Notes

• SYSTEM.TRIGGER_NODE is the node the user clicked on. SYSTEM.TRIGGER_NODE returns a value of type NODE. • No programmatic action will cause the When-Tree-Node-Expanded trigger to fire. Only end-user action will

generate an event.

13. When-Tree-Node-Selected Trigger

Fires when a node is selected or deselected. Usage Notes

• SYSTEM.TRIGGER_NODE is the node the user clicked on. SYSTEM.TRIGGER_NODE returns a value of type NODE.

• No programmatic action will cause the When-Tree-Node-Selected trigger to fire. Only end- user action will generate an event.