Oracle 10g Forms Lesson 15

Editor's Notes

• #3: Introduction Overview This lesson shows you how to create triggers. You specifically learn how to use built-in subprograms in Oracle Forms Developer applications.
• #4: Defining Triggers in Forms Builder Using Smart Triggers When you right-click an object in the Object Navigator or Layout Editor, a pop-up menu displays that includes the selection Smart Triggers. The Smart Triggers item expands to an LOV of common triggers that are appropriate for the selected object. When you click one of these triggers, Forms Builder creates the trigger. Using the Trigger LOV Using Smart Triggers is the easiest way to create a new trigger, but you can also do it by displaying the Trigger LOV, a list of all Forms Builder triggers. You can invoke the Trigger LOV from the Object Navigator, the Layout Editor, the PL/SQL Editor, or the Smart Triggers LOV. How to Create a Trigger Use the steps on the following pages to create a trigger.
• #5: Creating a Trigger Step One: Select Trigger Scope In the Object Navigator, select the Triggers node of the form, block, or item that will own the trigger. Alternatively, you can select an item in the Layout Editor if you are defining an item level trigger. A mistake often made by inexperienced Forms developers is to define a trigger at the wrong scope. For example, if you want a message to display when the cursor enters an item, you should code a When-New-Item-Instance trigger at the item level for that item. If you mistakenly put the trigger at the block or form level, the trigger will fire whenever the operator navigates to any item in the block or form.
• #6: Creating a Trigger (continued) Step Two: Invoke the Trigger LOV Once the trigger scope is selected, there are several ways to invoke the Trigger LOV: Smart Triggers: Right-click to display the pop-up menu. Select Smart Triggers. This invokes the Smart Triggers LOV displaying a list of common triggers for the selected object. If you do not see the desired trigger, select Other to display the Trigger LOV with a full list of triggers. Create: If you are in the Object Navigator with a Triggers node highlighted, select Edit > Create from the menu, or click Create in the toolbar. This invokes the Trigger LOV. PL/SQL Editor: Right click to display the pop-up menu. Select PL/SQL Editor. If there is no trigger defined for the object, this invokes the Trigger LOV. If there are already triggers defined for the object, the name and code of the first one appear in the editor. To define an additional trigger for the item, click Create in the Object Navigator toolbar to invoke the Trigger LOV. Once the Trigger LOV is invoked, select the trigger type.
• #7: Creating a Trigger (continued) Step Three: Use the PL/SQL Editor to Define the Trigger Code The trigger type and scope are now set in the PL/SQL Editor. You can enter the code for the trigger in the source pane of the editor. In Forms Builder, the PL/SQL Editor has the following specific trigger components: Name: Trigger name; pop-up list enables you to switch to a different trigger. Type: The type is set to Trigger. (The other types are Program Unit and Menu Item Code, but these are not valid for triggers.) Object: Enables you to set the scope to either Form Level, or a specific block Item: Enables you to change between specific items (at item level) to access other triggers. The Item trigger component is not labeled. Source pane: Where trigger code is entered or modified Toolbar: Buttons to compile, revert, undo, redo, indent, or outdent the code Step Four: Compile Click the Compile icon in the PL/SQL Editor to compile the trigger. This displays immediate feedback in the form of compilation error messages, which you can correct. If the trigger compiles correctly, a message displays in the lower right corner of the editor.
• #8: Setting Trigger Properties You can set the following trigger properties to affect the behavior of triggers: General Name: Specifies the internal name of the trigger Functional Fire in Enter Query Mode: Specify whether the trigger can fire when an event occurs in Enter Query as well as Normal mode. Execution Hierarchy: Use to change the default order of trigger firing when multiple triggers of the same name are defined at different levels. Help (these properties valid only for Key triggers) Display in “Keyboard Help”: Specify whether you want the name or description to appear in the Show Keys window. “ Keyboard Help” Text: Description to replace the default key description.
• #9: PL/SQL Editor Features The PL/SQL Editor provides the following features: Automatic Formatting and Coloring of PL/SQL Code Automatic Indenting and Color Syntax highlighting Drag and Drop text Manipulation Unlimited Undo/Redo Multiple Split Views You can create up to four separate views of the current program unit in the PL/SQL Editor by using split bars. Place the cursor over the split bar; it changes to a double-headed arrow. Left-click and drag the split bar to the desired location. To remove the split, drag it back to its original location. Trigger Components of the PL/SQL Editor 1. Type: Set to Trigger 2. Object: Enables you to set scope to Form Level or a specified block 3. Item: Enables you to switch between items (if item-level trigger) to access other triggers 4. Name: Trigger name; enables you to switch to another existing trigger 5. Source Pane: Where trigger code is entered or modified
• #10: PL/SQL Editor Features (continued) Syntax Palette: Enables you to display and copy the constructs of PL/SQL language elements and build packages into an editor. To invoke the Syntax Palette, select Tools > Syntax Palette from the menu system. Global search and replace: Enables you to search for text across multiple program units without opening individual instances of the Program Unit Editor. Replace every occurrence of the search string or selected occurrences only. Invoke the Find and Replace in Program Units dialog box by selecting Edit > Find and Replace PL/SQL from the menu system. Things to Remember About the PL/SQL Editor New or changed text in triggers remains uncompiled until you click Compile. Compiling triggers that contain SQL require connection to the database. All uncompiled triggers are compiled when the form module is compiled. The Block and Item pop-up lists do not change the current trigger scope. They enable you to switch to another trigger.
• #11: The Database Trigger Editor The logical grouping of items within the Database Trigger Editor enables developers to create row and statement triggers easily. An error message box displays an error when you try to retrieve, store, or drop an invalid trigger. To create a database trigger by using the Database Trigger Editor, perform the following steps: 1. In the Object Navigator, expand the Database Objects node to display the schema nodes. 2. Expand a schema node to display the database objects. 3. Expand the Tables node to display the schema’s database tables. 4. Select and expand the desired table. 5. Select the Triggers node and choose Edit > Create, or click Create on the toolbar. The Database Trigger Editor appears. 6. In the Database Trigger Editor, click New. 7. Define and save the desired program units.
• #12: Writing Trigger Code The code text of a Forms Builder trigger is a PL/SQL block that consists of three sections: A declaration section for variables, constants, and exceptions (optional) An executable statements section (required) An exception handlers section (optional) If your trigger code does not require defined variables, you do not need to include the BEGIN and END keywords; they are added implicitly.
• #13: Writing Trigger Code (continued) Examples 1. If the trigger does not require declarative statements, the BEGIN and END keywords are optional. When-Validate-Item trigger: IF :ORDER_ITEMS.unit_price IS NULL THEN :ORDER_ITEMS.unit_price := :PRODUCTS.list_price; END IF; calculate_total; -- User-named procedure 2. If the trigger requires declarative statements, the BEGIN and END keywords are required. When-Button-Pressed trigger: DECLARE vn_discount NUMBER; BEGIN vn_discount:=calculate_discount (:ORDER_ITEMS.product_id,:ORDER_ITEMS.quantity); MESSAGE(’Discount: ’||TO_CHAR(vn_discount)); END; 3. To handle exceptions, include EXCEPTION section in trigger. Post-Insert trigger: INSERT INTO LOG_TAB (LOG_VAL, LOG_USER) VALUES(:DEPARTMENTS.department_id,:GLOBAL.username); EXCEPTION WHEN OTHERS THEN MESSAGE(’Error! ’,||SQLERRM);
• #14: Using Variables in Triggers In triggers and subprograms, Forms Builder generally accepts two types of variables for storing values: PL/SQL variables: These must be declared in a DECLARE section, and remain available until the end of the declaring block. They are not prefixed by a colon. If declared in a PL/SQL package, a variable is accessible across all triggers that access this package. Forms Builder variables: Variable types maintained by the Forms Builder. These are seen by PL/SQL as external variables, and require a colon (:) prefix to distinguish them from PL/SQL objects (except when their name is passed as a character string to a subprogram). Forms Builder variables are not formally declared in a DECLARE section, and can exist outside the scope of a PL/SQL block.
• #15: Forms Builder Variables
• #16: Forms Builder Variables (continued) In each of the following examples of using Forms Builder variables, note that a colon (:) prefixes Forms Builder variables, and a period (.) separates the components of their name. The examples are not complete triggers. Examples 1. References to items should be prefixed by the name of the owning Forms Builder block, which prevents ambiguity when items of the same name exist in different blocks. This is also more efficient than the item name alone: :BLOCK3.product_id := :BLOCK2.product_id; 2. References to global variables must be prefixed by the word global. They may be created as the result of an assignment: :GLOBAL.customer_id := :BLOCK1.id; 3. References to system variables must be prefixed by the word System, and the contents must be in uppercase ( ’NORMAL’ , not ’normal’ ): IF :SYSTEM.MODE = ’NORMAL’ THEN ok_to_leave_block := TRUE; END IF; 4. Parameters defined at design-time have the prefix parameter: IF :PARAMETER.starting_point = 2 THEN GO_BLOCK(’BLOCK2’); -- built-in procedure END IF; Initializing Global Variables with Default Value You can use the DEFAULT_VALUE built-in to assign a value to a global variable. Forms Builder creates the global variable if it does not exist. If the value of the indicated variable is not null, DEFAULT_VALUE does nothing. The following example creates a global variable named country and initializes it with the value TURKEY: Default_Value(’TURKEY’,’GLOBAL.country’); Removing Global Variables You can use the ERASE built-in to remove a global variable. Globals always allocate 255 bytes of storage. To ensure that performance is not impacted more than necessary, always erase any global variable when it is no longer needed.
• #17: Adding Functionality with Built-In Subprograms Forms Builder provides a set of predefined subprograms as part of the product. These subprograms are defined within built-in packages as either a procedure or function. Forms Builder built-in subprograms belong to one of the following: Standard Extensions package: These built-ins are integrated into the Standard PL/SQL command set in Forms Builder. You can call them directly, without any package prefix. You can use more than one hundred standard built-ins. Example: EXECUTE_QUERY; Other Forms Builder packages: Subprograms in other built-in packages provide functionality related to a particular supported feature. These require the package name as a prefix when called. Example: ORA_JAVA.CLEAR_EXCEPTION; All the built-in subprograms used in this lesson are part of the Standard Extensions package.
• #18: Adding Functionality with Built-In Subprograms (continued) In addition to the standard extensions, Forms Builder provides the following packages: Note: Some of these packages, such as OLE2 , ORA_FFI , and TEXT_IO , function on the application server side, not on the client side. For example, TOOL_ENV enables you to get and set environment variables on the application server. To interact with the client, you would need to provide similar functionality in a JavaBean.
• #19: Limits of Use You can call built-ins in any trigger or user-named subprogram in which you use PL/SQL. However, some built-ins provide functionality that is not allowed in certain trigger types. Built-ins are therefore divided into two groups: Unrestricted built-ins: Unrestricted built-ins do not affect logical or physical navigation and can be called from any trigger, or from any subprogram. Restricted built-ins: Restricted built-ins affect navigation in your form, either external screen navigation, or internal navigation. You can call these built-ins only from triggers while no internal navigation is occurring. The online Help specifies which groups of built-ins can be used in each trigger. Calling a restricted built-in from a navigational trigger compiles successfully but causes a run-time error. For example, you can compile a Pre-Text-Item trigger that calls the restricted GO_ITEM built-in, but when the trigger fires at run-time it produces the FRM-40737 error.
• #20: Using Built-In Definitions When you are writing a trigger or a program unit, the Forms Builder enables you to look up built-in definitions, and optionally copy their names and argument prototypes into your code. 1. Place the cursor at the point in your PL/SQL code (in the PL/SQL Editor) where a built-in subprogram is to be called. 2. Expand the Built-in Packages node in the Navigator, and select the procedure or function that you need to use (usually from Standard Extensions). 3. If you want to copy the built-in prototype arguments or name, or both, select Edit > Paste Name or Edit > Paste Arguments from the menus (Paste Arguments includes both the built-in name and its arguments). 4. The definition of the built-in is copied to the cursor position in the PL/SQL Editor, where you can insert your own values for arguments, as required.
• #21: Using Built-In Definitions (continued) Note: A subprogram can be either a procedure or a function. Built-in subprograms are therefore called in two distinct ways: Built-in procedures: Called as a complete statement in a trigger or program unit with mandatory arguments. Built-in functions: Called as part of a statement, in a trigger or program unit, at a position where the function’s return value will be used. Again, the function call must include any mandatory arguments. Example The SHOW_LOV built-in is a function that returns a Boolean value (indicating whether the user has chosen a value from the LOV). It might be called as part of an assignment to a boolean variable. This is not a complete trigger. DECLARE customer_chosen BOOLEAN; BEGIN customer_chosen := SHOW_LOV(’customer_list’); . . .
• #22: Useful Built-Ins The table on the next page describes some built-ins that you can use in triggers to add functionality to items. They are discussed in later lessons.
• #23: Useful Built-Ins (continued)
• #24: Using Triggers When-Button-Pressed Trigger This trigger fires when the user clicks a button. You can define the trigger on an individual item or at higher levels if required. When-Button-Pressed accepts both restricted and unrestricted built-ins. You can use buttons to provide a wide range of functions for users. These functions include: Navigation Displaying LOVs Invoking calculations and other functions Example The Stock_Button in the CONTROL block is situated on the TOOLBAR canvas of the ORDERS form. When pressed, the button activates the When-Button-Pressed trigger. The trigger code results in navigation to the INVENTORIES block and execution of a query on the INVENTORIES block. GO_BLOCK(’INVENTORIES’); EXECUTE_QUERY;
• #25: Using Triggers When-Window-Closed Trigger This trigger fires when you close a window by using a window manager-specific close command. You define this trigger at the form level. The When-Window-Closed trigger accepts both restricted and unrestricted built-ins. Use this trigger to close a window programmatically when the operator issues the window manager Close command. Forms Builder does not close the window when the operator issues a window manager-specific close command; it only fires the When-Window-Closed trigger. It is the developer’s responsibility to write the required functionality in this trigger. You can close a window with the HIDE_WINDOW , SET_WINDOW_PROPERTY , and EXIT_FORM built-in subprograms. You cannot hide the window that contains the current item. Example When the operator issues the window manager-specific Close command, the following code in a When-Window-Closed trigger closes the WIN_INVENTORY window by setting the VISIBLE property to FALSE . GO_ITEM(’ORDERS.ORDER_ID’); SET_WINDOW_PROPERTY(’WIN_INVENTORY’,VISIBLE,PROPERTY_FALSE);
• #26: Summary To produce a trigger: Select a scope in the Object Navigator. Create a trigger and select a Name from the LOV, or use the SmartTriggers menu option. Define code in the PL/SQL Editor. Compile. Find built-ins in the Navigator under Built-in Packages: Paste built-in name and arguments to your code by using the Paste Name and Arguments option. Refer to online Help.
• #27: Summary (continued) The When-Button-Pressed trigger provides a wide range of functionality to users. Use the When-Window-Closed trigger to provide functionality when the user issues a window manager-specific close command.
• #28: Practice 14 Overview This practice focuses on how to use When-Button-Pressed and When-Window-Closed triggers. Using built-ins to display LOVs Using When-Button-Pressed and When-Window-Closed triggers to add functionality to the application Using built-ins to display and hide the Help stacked canvas Note: For solutions to this practice, see Practice 14 in Appendix A, “Practice Solutions.”
• #29: Practice 14 1. In the CUSTG XX form, write a trigger to display the Account_Mgr_Lov when the Account_Mgr_Lov_Button is selected. To create the When-Button-Pressed trigger, use the Smart Triggers feature. Find the relevant built-in in the Object Navigator under built-in packages, and use the “Paste Name and Arguments” feature. 2. Create a When-Window-Closed trigger at the form level in order to exit form. 3. Save, compile, and run the form. Test to see that the LOV is invoked when you press the Account_Mgr_Lov_Button and that the form exits when you close the Customer Information window. 4. In the ORDG XX form, write a trigger to display the Products_Lov when the Product_Lov_Button is selected and that the form exits when you press the Exit_Button. 5. Write a trigger that exits the form when the Exit_Button is selected. 6. Save, compile, and run the form. Test to see that the LOV is invoked when you press the Product_Lov_Button. 7. Create a When-Button-Pressed trigger on CONTROL.Show_Help_Button that uses the SHOW_VIEW built-in to display the CV_HELP. 8. Create a When-Button-Pressed trigger on CONTROL.Hide_Help_Button that hides the CV_HELP. Use the HIDE_VIEW built-in to achieve this. 9. Create a When-Button-Pressed trigger on CONTROL.Stock_Button that uses the GO_BLOCK built-in to display the INVENTORIES block, and EXECUTE_QUERY to automatically execute a query. 10. Write a form-level When-Window-Closed trigger to hide the WIN_INVENTORY window if the user attempts to close it, and to exit the form if the user attempts to close the WIN_ORDER window. Hint: Use the system variable :SYSTEM.TRIGGER_BLOCK to determine what block the cursor is in when the trigger fires. 11. Save and compile the form. Click Run Form to run the form and test the changes. The stacked canvas, CV_HELP, is displayed only if the current item will not be obscured. Ensure, at least, that the first entered item in the form is one that will not be obscured by CV_HELP. You might decide to advertise Help only while the cursor is in certain items, or move the stacked canvas to a position that does not overlay enterable items. The CV_HELP canvas, of course, could also be shown in its own window, if appropriate.