CHAPTER 6 LESSON B Creating Custom Forms

Lesson B Objectives  Suppress default system messages  Create alerts and messages to provide system feedback to users  Create applications that avoid user errors  Trap common runtime errors 2

Controlling System Messages 3

 By default, FRM- and ORA- messages are displayed in the Forms Services message line  They are useful for determining :  If the DBMS successfully inserts, updates, or deletes a record  The nature of errors that occur while the form is running 4

Controlling System Messages  Oracle classifies system messages according to:  their severity  Whether or not they require user intervention 5

System message severity levels Message Severity Level DescriptionExample 5Informative message that doesn’t require user intervention FRM-40400: Transaction complete: 1 records applied and saved 10Informative message that identifies a procedural mistake made by the user FRM-40201: Field is full: Can’t insert character 15Informative message that identifies a data- entry error, such as entering an incorrect data value in a text item FRM-50016: Legal characters are E 20Error message that identifies a condition that keeps a form trigger from working correctly FRM-40602: Can’t insert into or update data in a view 25Error message that identifies a condition that causes the form to operate incorrectly FRM-40919: Internal SQL statement execution error: %d >25Error message that identifies a condition that must be corrected immediately for the form to continue running FRM-40024: Out of memory 6

System message severity levels  Form developers can set the :SYSTEM.MESSAGE_LEVEL to suppress error messages equal to or less than a certain level  By default, the :SYSTEM.MESSAGE_LEVEL is 0, so all messages are displayed  The variable is commonly set in the PRE-FORM trigger 7

Providing System Feedback 8

 It is important for a Forms Builder application to provide feedback to users.  Feedback can be provided via the form message line or through the use of an alert. 9

Custom Messages  A custom message is a short (up to 200 characters) text string that the form developer displays on the form message line  The MESSAGE built-in is used to display a custom message. The syntax is: MESSAGE('message_string'); 10

Alerts  An alert is a pop-up dialog box or window that displays a message and buttons  We need alerts when:  The feedback requires a longer message than will fit on the message line  The user needs to select between alternate ways to proceed  Or, the user needs to acknowledge important messages 11

Creating an Alert  To create a new alert:  Select the Alerts node in the Object Navigator  Click on the create button  Specify the alert properties  An alert can have a maximum of three buttons 12

Alert Styles 1. Note alert  display an “i” for information  Conveys information to the user, such as confirming that the form has inserted a record 2. Caution alert  display an exclamation point “!”  Inform the user that he is about to make a choice that can’t be undone and could lead to a potentially damaging situation, such as deleting a record 3. Stop alert  display a red “X” or a red stoplight  Inform the user that he has instructed the system to perform an action that is not possible, such as trying to delete a record that is referenced as a foreign key another table 13

Displaying an Alert  To display an alert in a form, you use the SHOW_ALERT built-in function  The SHOW_ALERT function returns a numeric value indicating which button the user pressed. 14

Displaying an Alert  To display an alert during the execution of a trigger, you need to:  declare a numeric variable  Assign to this variable the value that the SHOW_ALERT function returns using the syntax: DECLARE alert_button NUMBER; BEGIN alert_button := SHOW_ALERT (‘alert_name’); END; 15

Displaying an Alert  To execute alternate program commands depending on the alert button that the user clicks, we create an IF/ELSEIF decision control structure  This structure:  Evaluates the value that the SHOW_ALERT function returns  Executes the appropriate program command 16

Displaying an Alert  Syntax to display an alert and execute alternate commands depending on the button the user clicked DECLARE alert_button NUMBER BEGIN alert_button := SHOW_ALERT (‘alert_name’); IF alert_button = ALERT_BUTTON1 THEN commands to execute for second alert button ELSEIF alert_button = ALERT_BUTTON2 THEN commands to execute for first alert button ELSEIF alert_button = ALERT_BUTTON3 THEN commands to execute for third alert button END IF; END; 17

Avoiding User Errors 18

Avoiding User Errors  A properly designed form can help users avoid errors  Techniques include validating user input, disabling command buttons, and disabling text items 19

Validating Form Input Values  When a user enters a value in a text item, it can be validated against business rules to determine whether the user made a data entry error  Text item validation can be performed using text item validation properties or validation triggers  A form can validate a text item’s value using specific text item validation properties that can be used in data block or custom forms 20

Text Item Validation Properties Property Node PropertyAllowable ValuesDescription DataData TypeChar, Number, Date, Alpha, Integer, Datetime, Long, Rnumber, Jdate, Edate, Time Ensure that input values are of the correct data type DataMaximum LengthInteger valueDefines the maximum number of characters the item will accept DataRequiredYes or NoSpecifies whether or not the value can be NULL DataLowest Allowed Value Integer valueFor numerical fields, specifies the lowest acceptable value DataHighest Allowed Value Integer valueFor numerical fields, specifies the highest acceptable value DataFormat MaskLegal format masksEnsure that user input is in the correct format List of Values Validate Form ListYes or NoSpecifies that the value entered by the user should be validated against the item’s LOV 21

Validation Unit  The level at which form validation occurs is called the validation unit  It can be set to validate a field whenever the user navigates away from the field; this is the default  Other possible values are Form, Data Block, and Record  However, for a custom form, validation should be performed at the Item level. 22

Form Validation Trigger  Text item validation properties work well for simple validation, but more complex validation can be coded in an item validation trigger  This is an item-level trigger associated with the WHEN-VALIDATE-ITEM event.  If the item does not satisfy the validation rules coded in the trigger, the form displays a message and raises a FORM_TRIGGER_FAILURE exception 23

Disabling Form Command Buttons to Avoid User Errors  It is a good idea to disable any button that should not be pressed at a particular time.  Example: in a form to enter student data, the Save New button should be disabled until the student’s last name is entered  The method used to disable a button is: SET_ITEM_PROPERTY('item_name‘, property_name,property_value);  In the case of disabling a button, property_name is ENABLED, and the value should be FALSE to disable the button and TRUE to enable it. 24

Disabling Text Item Navigation  When a form displays certain items such as primary keys, it is a good idea not to allow the user to modify the value  One way to do this is to prevent navigation to the field by making it nonnavigable  This means that the user cannot use the Tab key to navigate to the text item  To make an item nonnavigable, set the Keyboard Navigable property to No. 25

Disabling Text Item Navigation  Since the user can still navigate to the item using the mouse, it is also necessary to create a trigger that moves the form focus away from a text item whenever the mouse is placed there  The WHEN-MOUSE-UP event can be used to activate this trigger 26

Trapping Form Runtime Errors  The ON-ERROR event occurs when FRM- and ORA- messages are generated  There are four built-in procedures used for obtaining information about runtime errors 27

Forms Builder Built-in Procedures for Handling Errors Procedure NameData Returned DBMS_ERROR_CODEError number of the most recent database (ORA) error, represented as a negative integer DBMS_ERROR_TEXTError number and message text of the most recent ORA- error ERROR_CODEError number of the most recent Forms Services (FRM) error, represented as a positive integer ERROR_TEXTError number and text of the most recent FRM- error or message 28