Les17

Editor's Notes

• #3: Introduction Overview This lesson shows you how to intercept system messages, and if desired, replace them with ones that are more suitable for your application. You will also learn how to handle errors by using built-in subprograms, and how to build customized alerts for communicating with users.
• #4: Run-Time Messages and Alerts Overview Forms displays messages at run time to inform the operator of events that occur in the session. As the designer, you may want to either suppress or modify some of these messages, depending on the nature of the application. Forms can communicate with the user in the following ways: Informative message: A message tells the user the current state of processing, or gives context-sensitive information. The default display is on the message line. You can suppress its appearance with an On-Message trigger. Error message: This informs the user of an error that prevents the current action. The default display is on the message line. You can suppress message line errors with an On-Error trigger. Working message: This tells the operator that the form is currently processing (for example: Working...). This is shown on the message line. This type of message can be suppressed by setting the system variable SUPPRESS_WORKING to True: :SYSTEM.SUPPRESS_WORKING := ’TRUE’;
• #5: Run-Time Messages and Alerts Overview (continued) System alert: Alerts give information to the operator that require either an acknowledgment or an answer to a question before processing can continue. This is displayed as a modal window. When more than one message is waiting to show on the message line, the current message also displays as an alert. You can also build messages and alerts into your application: Application message: These are messages that you build into your application by using the MESSAGE built-in. The default display is on the message line. Application alert: These are alerts that you design as part of your application, and issue to the operator for a response by using the SHOW_ALERT built-in.
• #6: Built-Ins and Handling Errors When a built-in subprogram fails, it does not directly cause an exception in the calling trigger or program unit. This means that subsequent code continues after a built-in fails, unless you take action to detect a failure. Example A button in the CONTROL block called Stock_Button is situated on the Toolbar canvas of the ORDERS form. When clicked, this When-Button-Pressed trigger navigates to the INVENTORIES block, and performs a query there. GO_BLOCK(‘INVENTORIES’); EXECUTE_QUERY; If the GO_BLOCK built-in procedure fails because the INVENTORIES block does not exist, or because it is nonenterable, then the EXECUTE_QUERY procedure still executes, and attempts a query in the wrong block.
• #7: Built-Ins and Handling Errors (continued) Built-In functions for detecting success and failure Forms Builder supplies some functions that indicate whether the latest action in the form was successful. Note: These built-in functions return success or failure of the latest action in the form. The failing action may occur in a trigger that fired as a result of a built-in from the first trigger. For example, the EXECUTE_QUERY procedure, can cause a Pre-Query trigger to fire, which may itself fail.
• #8: Errors and Built-Ins It is usually most practical to use FORM_SUCCESS , because this returns FALSE if either a fatal or a nonfatal error occurs. You can then code the trigger to take appropriate action. Example of FORM_SUCCESS Here is the same trigger again. This time, the FORM_SUCCESS function is used in a condition to decide if the query should be performed, depending on the success of the GO_BLOCK action. GO_BLOCK(’INVENTORIES’); IF FORM_SUCCESS THEN EXECUTE_QUERY; ELSE MESSAGE(’An error occurred while navigating to Stock’); END IF; Triggers fail only if there is an unhandled exception or you raise the FORM_TRIGGER_FAILURE exception to fail the trigger in a controlled manner.
• #9: Errors and Built-Ins (continued) Note: The program unit CHECK_PACKAGE_FAILURE , which is written when you build master-detail blocks, may be called to fail a trigger if the last action was unsuccessful. Built-in Functions to Determine the Error When you detect an error, you may need to identify it to take a specific action. Three more built-in functions provide this information: These built-ins are explained in detail later in this lesson.
• #10: Controlling System Messages Suppressing messages according to their severity You can prevent system messages from being issued, based on their severity level. Forms Builder classifies every message with a severity level that indicates how critical or trivial the information is; the higher the numbers, the more critical the message. There are six levels that you can affect.
• #11: Controlling System Messages (continued) Suppressing messages according to their severity (continued) In a trigger, you can specify that only messages above a specified severity level are to be issued by the form. You do this by assigning a value to the system variable MESSAGE_LEVEL . Forms then only issues messages that are above the severity level defined in this variable. The default value for MESSAGE_LEVEL (at form startup) is 0. This means that messages of all severities are displayed.
• #12: Example of Suppressing Messages The following When-Button-Pressed trigger moves up one record, using the built-in procedure UP. If the cursor is already on the first record, the built-in fails and the following message usually displays: FRM-40100: At first record . This is a severity level 5 message. However the trigger suppresses this, and outputs its own application message instead. The trigger resets the message level to normal (0) afterwards. :SYSTEM.MESSAGE_LEVEL := ’5’; UP; IF NOT FORM_SUCCESS THEN MESSAGE(’Already at the first Order’); END IF; :SYSTEM.MESSAGE_LEVEL := ’0’;
• #13: Example of Suppressing Messages (continued) Suppressing working messages Working messages are displayed when the Forms is busy processing an action. For example, while querying you receive the message: Working... . You can suppress this message by setting the system variable SUPPRESS_WORKING to True: :SYSTEM.SUPPRESS_WORKING := ’TRUE’; Note: You can set these system variables as soon as the form starts up, if required, by performing the assignments in a When-New-Form-Instance trigger.
• #14: The FORM_TRIGGER_FAILURE Exception Triggers fail only when one of the following occurs: During an Unhandled Exception When you request the trigger to fail by raising the built-in exception FORM_TRIGGER_FAILURE This exception is defined and handled by Forms Builder, beyond the visible trigger text that you write. You can raise this exception: In the executable part of a trigger, to skip remaining actions and fail the trigger In an exception handler, to fail the trigger after your own exception handling actions have been obeyed In either case, Forms Builder has its own exception handler for FORM_TRIGGER_FAILURE , which fails the trigger but does not cause an unhandled exception. This means that you can fail the trigger in a controlled manner.
• #15: The FORM_TRIGGER_FAILURE Exception (continued) Example This example adds an action to the exception handler of the When-Validate-Item trigger for the Customer_ID item. It raises an exception to fail the trigger when the message is sent, and therefore traps the user in the Customer_ID item: SELECT cust_first_name || ‘ ‘ || cust_last_name INTO :ORDERS.customer_name FROM CUSTOMERS WHERE customer_id = :ORDERS.customer_id; EXCEPTION WHEN no_data_found THEN MESSAGE(’Customer with this ID not found’); RAISE form_trigger_failure;
• #16: Triggers for Intercepting System Messages By writing triggers that fire on message events you can intercept system messages before they are displayed on the screen. These triggers are: On-Error: Fires on display of a system error message On-Message: Fires on display of an informative system message These triggers replace the display of a message, so that no message is seen by the operator unless you issue one from the trigger itself. You can define these triggers at any level. For example, an On-Error trigger at item level only intercepts error messages that occur while control is in that item. However, if you define one or both of these triggers at form level, all messages that cause them to fire will be intercepted regardless of which object in the current form causes the error or message. On-Error Trigger Use this trigger to: Detect Forms and Oracle Server errors. This trigger can perform corrective actions based on the error that occurred. Replace the default error message with a customized message for this application.
• #17: Triggers for Intercepting System Messages (continued) Remember that you can use the built-in functions ERROR_CODE , ERROR_TEXT , and ERROR_TYPE to identify the details of the error, and possibly use this information in your own message. Example of an On-Error Trigger This On-Error trigger sends a customized message for error 40202 (field must be entered), but reconstructs the standard system message for all other errors. IF ERROR_CODE = 40202 THEN MESSAGE(’You must fill in this field for an Order’); ELSE MESSAGE(ERROR_TYPE || ’-’ || TO_CHAR(ERROR_CODE) || ’: ’ || ERROR_TEXT); END IF; RAISE FORM_TRIGGER_FAILURE;
• #18: On-Message Trigger Use this trigger to suppress informative messages, replacing them with customized application messages, as appropriate. You can handle messages in On-Message in a similar way to On-Error. However, because this trigger fires due to informative messages, you will use different built-ins to determine the nature of the current message.
• #19: On-Message Trigger (continued) Note: These functions return information about the most recent message that was issued. If your applications must be supported in more than one national language, then use MESSAGE_CODE in preference to MESSAGE_TEXT when checking a message. Example of an On-Message trigger This On-Message trigger modifies the “Query caused no records to be retrieved” message (40350) and the “ Query caused no records to be retrieved. Re-enter.” message (40301):. IF MESSAGE_CODE in (40350,40301) THEN MESSAGE(’No Orders found-check your search values’); ELSE MESSAGE(MESSAGE_TYPE || ’-’ || TO_CHAR(MESSAGE_CODE) ||: ’|| MESSAGE_TEXT); END IF;
• #20: Setting Alert Properties Example The slide shows a generic example of an alert, showing all three icons and buttons that can be defined.
• #21: Creating and Controlling Alerts Alerts are an alternative method for communicating with the operator. Because they display in a modal window, alerts provide an effective way of drawing attention and forcing the operator to answer the message before processing can continue. Use alerts when you need to perform the following: Display a message that the operator cannot ignore, and must acknowledge. Ask the operator a question where up to three answers are appropriate (typically Yes, No, or Cancel). You handle the display and responses to an alert by using built-in subprograms. Alerts are therefore managed in two stages: Create the alert at design-time, and define its properties in the Property palette. Activate the alert at run time by using built-ins, and take action based on the operator’s returned response. How to create an alert Like other objects you create at design-time, alerts are created from the Object Navigator. Select the Alerts node in the Navigator, and then select Create. Define the properties of the alert in the Property Palette. The properties that you can specify for an alert include the following:
• #22: Planning Alerts: How Many Do You Need? Potentially, you can create an alert for every separate alert message that you need to display, but this is usually unnecessary. You can define a message for an alert at run time, before it is displayed to the operator. A single alert can be used for displaying many messages, providing that the available buttons are suitable for responding to the messages. Create an alert for each combination of: Alert style required Set of available buttons (and labels) for operator response For example, an application might require one Note-style alert with a single button (OK) for acknowledgment, one Caution alert with a similar button, and two Stop alerts that each provide a different combination of buttons for a reply. You can then assign a message to the appropriate alert before its display, through the SET_ALERT_PROPERTY built-in procedure.
• #23: Controlling Alerts at Run Time There are built-in subprograms to change an alert message, to change alert button labels, and to display the alert, which returns the operator’s response to the calling trigger. SET_ALERT_PROPERTY procedure Use this built-in to change the message that is currently assigned to an alert. At form startup, the default message (as defined in the Property palette) is initially assigned: SET_ALERT_PROPERTY(’alert_name’,property,’message’)
• #24: Controlling Alerts at Run Time (continued) SET_ALERT_BUTTON_PROPERTY procedure Use this built-in to change the label on one of the alert buttons: SET_ALERT_BUTTON_PROPERTY(’alert_name’, button, property, ’value’)
• #25: SHOW_ALERT Function SHOW_ALERT is how you display an alert at run time, and return the operator’s response to the calling trigger: selected_button := SHOW_ALERT(’alert_name’); . . . Alert_Name is the name of the alert, as defined in the builder. You can alternatively specify an Alert_Id (unquoted) for this argument. SHOW_ALERT returns a NUMBER constant, that indicates which of the three possible buttons the user clicked in response to the alert. These numbers correspond to the values of three PL/SQL constants, which are predefined by the Forms Builder: After displaying an alert that has more than one button, you can determine which button the operator clicked by comparing the returned value against the corresponding constants.
• #26: SHOW_ALERT Function (continued) Example A trigger that fires when the user attempts to delete a record might invoke the alert, shown opposite, to obtain confirmation. If the operator selects Yes, then the DELETE_RECORD built-in is called to delete the current record from the block. IF SHOW_ALERT(’del_check’) = ALERT_BUTTON1 THEN DELETE_RECORD; END IF;
• #27: Directing Errors to an Alert You may want to display errors automatically in an alert, through an On-Error trigger. The built-in functions that return error information, such as ERROR_TEXT , can be used in the SET_ALERT_PROPERTY procedure, to construct the alert message for display. Example: The following user-named procedure can be called when the last form action was unsuccessful. The procedure fails the calling trigger and displays Error_Alert containing the error information. PROCEDURE alert_on_failure IS n NUMBER; BEGIN SET_ALERT_PROPERTY(’error_alert’, ALERT_MESSAGE_TEXT, ERROR_TYPE||’-’||TO_CHAR(ERROR_CODE)||’: ’ || ERROR_TEXT); n := SHOW_ALERT(’error_alert’); END; Note: If you want the trigger to fail, include a call to RAISE form_trigger_failure .
• #28: Handling Errors Raised by the Oracle Database Server Oracle server errors can occur for many different reasons , such as violating a declarative constraint or encountering a stored program unit error. You should know how to handle errors that may occur in different situations. Causes of Oracle Server Errors
• #29: Handling Errors Raised by the Oracle Database Server (continued) Types of DML statements Declarative-constraint violations and firing of database triggers are in turn caused by DML statements. For error-handling purposes, you must distinguish between the following two types of DML statements: FRM-Error messages caused by implicit DML errors If an implicit DML statement causes an Oracle server error, Forms displays one of these FRM-error messages: FRM-40508: ORACLE error: unable to INSERT record. FRM-40509: ORACLE error: unable to UPDATE record. FRM-40510: ORACLE error: unable to DELETE record. You can use ERROR_CODE to trap these errors in an On-Error trigger and then use DBMS_ERROR_CODE and DBMS_ERROR_TEXT to determine the ORA-error code and message. FRM-Error messages with Web-deployed Forms Users may receive a generic FRM-99999 error. You can obtain meaningful information about this error from the JInitiator Control Panel.
• #30: How to Trap Different Types of Oracle Database Server Errors Note: Declarative-constraint violations and database triggers may be caused by both implicit DML and explicit DML. Stored program units are always called explicitly from a trigger or program unit. Technical Note The values of DBMS_ERROR_CODE and DBMS_ERROR_TEXT are the same as what a user would see after selecting Help > Display Error; the values are not automatically reset following successful execution.
• #31: Summary In this lesson, you should have learned how to intercept system messages, and how to replace them with ones that are more suitable for your application. You also learned how to build customized alerts for communicating with operators. Test for failure of built-ins by using the FORM_SUCCESS built-in function or other built-in functions. Forms messages can be either Informative, Error, Working, or Application messages.
• #32: Summary (continued) Set system variables to suppress system messages: Assign a value to MESSAGE_LEVEL to specify that only messages above a specific severity level are to be used by the form. Assign a value of True to SUPPRESS_WORKING to suppress all working messages. On-Error and On-Message triggers intercept system error messages and informative system messages. You can use the built-ins ERROR_CODE , ERROR_TEXT , ERROR_TYPE , MESSAGE_CODE , MESSAGE_TEXT , or MESSAGE_TYPE to obtain information about the number, text, and type of errors and messages. Alert types: Stop, Caution, and Note Up to three buttons are available for response ( NULL indicates no button). Display alerts and change alert messages at run time with SHOW_ALERT and SET_ALERT_PROPERTY .
• #33: Summary (continued) Intercept and handle server-side errors.
• #34: Practice 17 Overview In this practice, you create some alerts. These include a general alert for questions and a specific alert that is customized for credit limit. Using an alert to inform the operator that the customer’s credit limit has been exceeded Using a generic alert to ask the operator to confirm that the form should terminate Note: For solutions to this practice, see Practice 17 in Appendix A, “Practice Solutions.”
• #35: Practice 17 1. Create an alert in CUSTG XX called Credit_Limit_Alert with one OK button. The message should read “This customer's current orders exceed the new credit limit”. 2. Alter the When-Radio-Changed trigger on Credit_Limit to show the Credit_Limit_Alert instead of the message when a customer’s credit limit is exceeded. 3. Save and compile the form. Click Run Form to run the form and test the changes. 4. Create a generic alert in ORDG XX called Question_Alert that allows Yes and No replies. 5. Alter the When-Button-Pressed trigger on CONTROL.Exit_Button to use the Question_Alert to ask the operator to confirm that the form should terminate. (You can import the text from pr17_4.txt .) 6. Save and compile the form. Click Run Form to run the form and test the changes.