How to Use WHEN-NEW-FORM-INSTANCE Trigger in Oracle Forms

In Oracle Forms, triggers are powerful tools that allow developers to define the behavior of a form at specific events. One of the most commonly used triggers during form startup is the WHEN-NEW-FORM-INSTANCE trigger. If you are new to Oracle Forms, understanding this trigger is essential because it controls what happens immediately after the form is opened.

In this guide, I will explain what this trigger does, how to create it, and provide practical use cases.

What is the WHEN-NEW-FORM-INSTANCE Trigger?

The WHEN-NEW-FORM-INSTANCE trigger fires once after the form is initialized and displayed but before the user can interact with it.

• It executes only one time per form session.
• It is useful for setting default values, initializing variables, opening other forms, or running setup code.
• It ensures the form is in a ready state before the user starts working.

👉 Think of it as the "form startup script" that runs automatically whenever the form is launched.

When Does It Fire?

The firing sequence is:

1. The user calls the form.
2. Oracle Forms loads all blocks and items.
3. WHEN-NEW-FORM-INSTANCE fires.
4. The user gains control to interact with the form.

This makes it different from triggers like WHEN-NEW-BLOCK-INSTANCE (fires when entering a block) or WHEN-NEW-ITEM-INSTANCE (fires when moving into a field).

How to Create a WHEN-NEW-FORM-INSTANCE Trigger

1. Open your form (.FMB) in Oracle Forms Builder.
2. In the Object Navigator, expand the Triggers node under the form.
3. Right-click and choose Create → Trigger.
4. Select WHEN-NEW-FORM-INSTANCE from the list.
5. Write your PL/SQL code in the trigger editor.
6. Save and compile the form.

Example 1: Display a Welcome Message

BEGIN
   MESSAGE('Welcome to the Student Management System');
   PAUSE;
END;

• This code shows a welcome message when the form starts.
• The PAUSE ensures the message is displayed until the user presses Enter.

Example 2: Setting Default Values

BEGIN
   :STUDENT.REG_DATE := SYSDATE;
   :STUDENT.STATUS := 'Active';
END;

• The registration date is set to the current system date.
• The default status is initialized as "Active".

Example 3: Navigating to a Specific Block

BEGIN
   GO_BLOCK('STUDENT');
   EXECUTE_QUERY;
END;

• When the form opens, the cursor goes directly to the STUDENT block.
• An automatic query runs, displaying existing student records.

Example 4: Calling Another Form at Startup

BEGIN
   CALL_FORM('menu_form');
END;

• Automatically opens another form (e.g., a menu form) when this form is launched.
• Useful when a form should always begin from a central navigation point.

Best Practices for Using WHEN-NEW-FORM-INSTANCE

• Keep the code lightweight. Heavy processing at startup may slow down form loading.
• Avoid putting large queries here; instead, use separate procedures for efficiency.
• Use this trigger for initialization tasks only; do not handle transactional logic here.
• If multiple setup actions are needed, call a stored procedure instead of writing lengthy PL/SQL directly in the trigger.

Common Mistakes

• Confusing with PRE-FORM Trigger:
  • PRE-FORM fires before form creation (at a lower level).
  • WHEN-NEW-FORM-INSTANCE fires after the form is fully created.
• Placing navigation code incorrectly: Using GO_ITEM or GO_BLOCK before items are ready may cause errors. Always test navigation logic.
• Long-running queries at startup: These can frustrate users; better load data on demand.

Conclusion

The WHEN-NEW-FORM-INSTANCE trigger is one of the most important triggers in Oracle Forms. It is the perfect place to put initialization logic such as displaying messages, setting default values, opening other forms, or preparing the form state before user interaction. By mastering this trigger, you ensure that every form you create is user-friendly and ready to run smoothly from the moment it opens.